Yii2 restful api创建，认证授权以及速率控制

下面是对restful从创建到速率控制的一个详细流程介绍，里面的步骤以及截图尽可能详细，熟悉restful的盆友可能觉得过于繁琐，新手不妨耐心仔细看一下。

一．Api的创建

1.复制一个frontend或者backend，将其重命名为api放在同级目录下

2.然后删除controllers和views文件夹，然后将api文件中的frontend替换为api（比如命名空间，相关配置等），这点非常重要！！！

3.打开cmd命令行，cd进入项目所在根目录C:wampwwwadvanced下，init 根据提示进行初始化设置，之后修改commonconfigmain-local.php文件中的数据库相关配置。这个比较简单。

4.需要修改commonconfigootstrap.php文件，对新建的应用增加alias别名，如下：

Yii::setAlias('@api', dirname(dirname(__DIR__)) . '/api');

5.为新建的api应用程序美化路由，为了后续方便访问，进行域名配置

1）首先保证你的web服务器开启rewrite规则，细节我们就不说了，不过这是前提。

2）给api目录配置一个访问地址:www.dsgn.com指向 api/web，不会的盆友请参考我的另一篇博客，关于Apache的域名配置

3）接着，在应用入口同级增加.htaccess文件就好，我们以apache为例

.htaccess文件内容：

Options +FollowSymLinks

IndexIgnore */*

RewriteEngine on

# if a directory or a file exists, use it directly

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

# otherwise forward it to index.php

RewriteRule . index.php

RewriteRule .svn/ /404.html

RewriteRule .git/ /404.html

6.用了便于演示说明，我们新建一张数据表good表，字段自己随意设置，并向其中插入几条数据。

CREATE TABLE `goods` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`name` varchar(100) NOT NULL DEFAULT '',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

INSERT INTO `goods` VALUES ('1', '11111');
INSERT INTO `goods` VALUES ('2', '22222');
INSERT INTO `goods` VALUES ('3', '333');
INSERT INTO `goods` VALUES ('4', '444');
INSERT INTO `goods` VALUES ('5', '555');

7.通过gii生成modules

注意：由于刚才配置的域名是访问到api/web,现在gii生成器的地址我用localhost去访问fronted/web/index.php

地址：http://localhost/advanced/frontend/web/index.php?r=gii

然后依次生成模块控制器模型

8.同时在 api/config/main.php 中做如下配置，这一步也很重要

1）添加module的配置

'modules' => [

'v1' => [

'class' => 'apimodulesv1Module',

2）修改controllerNamespace

'controllerNamespace' => 'apicontrollers',

3）开启urlManager，如下配置

'urlManager' => [

'enablePrettyUrl' => true,

'enableStrictParsing' => true,

'showScriptName' => false,

//为Goods配置Url规则

'rules' => [

['class' => 'yii estUrlRule', 'controller' => ['v1/good']],

4）删除

'errorHandler' => [

'errorAction' => 'site/error',

9. 重新配置控制器。为了实现restful风格的api,在yii2中，我们需要对 apimodulesv1controllers下的GoodController控制器进行一下改写

<?php

namespace apimodulesv1controllers;

use yii estActiveController;

class GoodController extends ActiveController

{

public $modelClass = 'apimodelsGood';

}

说明：翻阅资料的时候，看到有人提出，在这个控制器里面自定义方法，但是访问的时候报404

原因如下：RESTful是以资源为中心而不是页面,所以YII2给每个资源只给了有限的几个action,而且是以Action类的形式写的,

它默认有create, delete, update, index, view等的一下方法
所创建的 API 包括：
GET /users: 逐页列出所有用户
POST /users: 创建一个新用户
GET /users/123: 返回用户 123 的详细信息
PATCH /users/123 and PUT /users/123: 更新用户123
DELETE /users/123: 删除用户123

1)框架默认的action都写在yii est包下(XXXAction.php就表示相应的动词操作,源代码很少,你可以直接看看),

2)如果这个资源的所有动词都是默认的话是则它的controller里除了modelClass是不用写任何代码的.

3)如果想要自定义动词必须继承rest包下对应的Action类,然后在controller重写actions指向你的新action,从而实现重写

打开文件apimodulesv1controllersUserController,参考代码如下：

如果我们想在自己定义不同的api接口的话？那么我们可以通过配置实现，在main.php的主文件中:
'urlManager' => [
'enablePrettyUrl' => true,
'showScriptName' => false,
'rules' => [
[
'class' => 'yii estUrlRule',
'controller' => ['v1/users'],
'pluralize' => false,
'extraPatterns' => [
'GET versions' => 'version',
'GET search/<id:d+>' => 'search',
'POST newusers' => 'add'
],

],
],
],
"extraPatterns"这个属性是额外模式配置
a)'GET versions' => 'version',代表获取接口版本，例如/v1/users/versions ，对应的内联操作actionVersion();

b)'GET searches/<id:d+>' => 'search', 代表搜索一个指定id的用户，例如/v1/users/searches/1,对应的内联操作actionSearches();

c)'POST newusers' => 'add'，代表添加一个用户，例如/v1/users/newusers，对应的内联操作actionAdd();

我们只需要在控制器中实现这些方法，完成相应的逻辑业务，那么各个需要的接口就完成了。

9.模拟请求操作

到这一步就可以用postman来测试，不会安装或者调试的盆友请网上搜索一下，当然也可以用其他测试工具来调试。

从上面截图中可以清楚的看到，GET 方式请求http://www.dsgn.com/v1/goods，已经能够很方便的获取我们表中的数据了。

补充说明：1）Yii 将在末端使用的控制器的名称自动变为复数。这个要重点注意！

2）这个地方使用之所以使用goods这个复数，是因为在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。

一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

3）当然，用yii2的restful写api，暂时可以不用框架推荐的yii estUrlRule，就可以写出一般路由的api了，主要因为yii estUrlRule的路由简略了很多，不利于直接识别api代表的意思。

例子：

使用yii estUrlRule，访问链接为/profiles/3

使用一般URL规则'<controller:w+>/<action:w+>' => '<controller>/<action>', 访问链接为/profile/view?id=3

测试结果都一致。

httpx://api.yii.com/profile/view?id=1&expand=user

yii的restful要获得关联表数据必须要带一个expand参数表明需要使用的关联数据

4）如果是用restful自带的路由规则，要解决访问存在的复数问题的话，需要添加'pluralize' => false这个条件，具体如下：

'rules' => [

['class' => 'yii estUrlRule',

'controller' => ['v1/good'],

'pluralize' => false

到此为止，用http://www.dsgn.com/v1/good就能成功测试访问了。

但是，有个问题出现了，用postman测试的数据，可以看到是json格式的，那是因为postman测试工具可以自动转化成json美化格式，

实际中我们用浏览器访问该url看到如下，(这跟是否用复数访问没关系)

解决方法是，在GoodController控制器下重写behaviors函数，具体做法是加这样一段代码：

public function behaviors()

{

$behaviors=parent::behaviors();

$behaviors['contentNegotiator']['formats'] = [

'application/json'=>Response::FORMAT_JSON

];

return $behaviors;

}

说明：Yii2 RESTful支持JSON和XML格式，如果想指定返回数据的格式,需要配置yiifiltersContentNegotiator::formats属性

现在重新去访问http://www.dsgn.com/v1/good就可以看到以json格式解析出来了。O(∩_∩)O~~~

补充说明：

API的目录结构有2种方式：

之前的创建测试都是在方式1的情况下进行的，其实这两种方式的差异并不大，现在对方式2进行补充说明：

打开apiconfigmain.php中，有如下配置：

二、认证授权

1.需要设置认证的原因：和Web应用不同，RESTful APIs 通常是无状态的，也就意味着不应使用sessions 或 cookies，因此每个请求应附带某种授权凭证，因为用户授权状态可能没通过sessions 或 cookies维护，

常用的做法是每个请求都发送一个秘密的access token来认证用户，由于access token可以唯一识别和认证用户， API 请求应通过HTTPS来防止man-in-the-middle (MitM) 中间人攻击.

2.准备工作：首先，要创建一个user表，可以用yii2自带的migrate创建，不会的请查阅相关资料。或者用sql语句建表，如下

DROP TABLE IF EXISTS `user`;

CREATE TABLE `user` (

`id` int(10) unsigned NOT NULL AUTO_INCREMENT,

`username` varchar(20) NOT NULL DEFAULT '' COMMENT '用户名',

`password_hash` varchar(100) NOT NULL DEFAULT '' COMMENT '密码',

`password_reset_token` varchar(50) NOT NULL DEFAULT '' COMMENT '密码token',

`email` varchar(20) NOT NULL DEFAULT '' COMMENT '邮箱',

`auth_key` varchar(50) NOT NULL DEFAULT '',

`status` tinyint(3) unsigned NOT NULL DEFAULT '0' COMMENT '状态',

`created_at` int(10) unsigned NOT NULL DEFAULT '0' COMMENT '创建时间',

`updated_at` int(10) unsigned NOT NULL DEFAULT '0' COMMENT '更新时间',

`access_token` varchar(50) NOT NULL DEFAULT '' COMMENT 'restful请求token',

PRIMARY KEY (`id`),

UNIQUE KEY `username` (`username`),

UNIQUE KEY `access_token` (`access_token`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8;

插入一条或者几条数据,以便后期测试

3.配置user应用组件（不是必要的，但是推荐配置）：

说明：1）设置yiiwebUser::enableSession属性为false（因为RESTful APIs为无状态的，当yiiwebUser::enableSession为false，请求中的用户认证状态就不能通过session来保持）

　 2）设置yiiwebUser::loginUrl属性为null（显示一个HTTP 403 错误而不是跳转到登录界面）

3） 'identityClass' => 'apimodelsUser',

指定认证的model类，现在是在apimodelsUser这个类中，那么我们需要在apimodelsUser这个类中实现,yiiwebIdentityInterface这个类中的所有定义的接口方法

'user' => [

'identityClass' => 'apimodelsUser',

'enableAutoLogin' => true,

'enableSession'=>false,

'identityCookie' => ['name' => '_identity-api', 'httpOnly' => true],

4.为控制器配置authenticator行为指定认证方式

<?php

namespace apimodulesv1controllers;

use yii estActiveController;

use yiihelpersArrayHelper;

use yiifiltersauthQueryParamAuth;

class UserController extends ActiveController

{

public $modelClass = 'apimodelsUser';

public function behaviors() {

$behaviors = parent::behaviors();

$behaviors['authenticator'] = [

//注意：此处如果是在apache环境下采用HttpBearerAuth认证方式，需要在api/web下的.htaccess中加上一句：SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

'class' => QueryParamAuth::className(),

];

$behaviors['contentNegotiator']['formats'] = [

'application/json'=> Response::FORMAT_JSON

];

return $behaviors;

}

说明：behaviors()这个函数的是定义这个控制器类的行为，也就是每一次访问这个控制器的方法，

都会执行这个behaviors中定义的各种行为，认证也是这个流程，我们访问一个api接口时，

就会执行yiifiltersauthQueryParamAuth的这个文件的authenticate()这个方法

5.在api/config/main.php中

我们需要在配置文件中保证，步骤3配置user组件中曾提到过，这里作为补充说明。

'user' => [

'identityClass' => 'apimodelsUser',

这里是指定认证的model类，现在是在apimodelsUser这个类中，那么我们需要在apimodelsUser这个类中实现yiiwebIdentityInterface这个类中的所有定义的接口方法，在api/models/User.php中代码如下：

<?php

namespace apimodels;

use yiidbActiveRecord;

use yiiwebIdentityInterface;

class User extends ActiveRecord implements IdentityInterface{

public static function tableName()

{

return 'user';

}

public function rules()

{

return [

[['username', 'auth_key', 'password_hash', 'email', 'created_at', 'updated_at'], 'required'],

[['status', 'created_at', 'updated_at', 'allowance', 'allowance_updated_at'], 'integer'],

[['username', 'password_hash', 'password_reset_token', 'email'], 'string', 'max' => 255],

[['auth_key'], 'string', 'max' => 32],

[['access_token'], 'string', 'max' => 60],

[['username'], 'unique'],

[['email'], 'unique'],

[['password_reset_token'], 'unique'],

];

}

public function attributeLabels()

{

return [

'id' => 'ID',

'username' => 'Username',

'auth_key' => 'Auth Key',

'password_hash' => 'Password Hash',

'password_reset_token' => 'Password Reset Token',

'email' => 'Email',

'status' => 'Status',

'created_at' => 'Created At',

'updated_at' => 'Updated At',

'access_token' => 'Access Token',

'allowance' => 'Allowance',

'allowance_updated_at' => 'Allowance Updated At',

];

}

//实现接口里的全部方法

public static function findIdentity($id)

{

return static::findOne(['id' => $id, 'status' => self::STATUS_ACTIVE]);

}

public static function findIdentityByAccessToken($token, $type = null)

{

return static::findOne(['access_token' => $token]); //数据库user表中的字段access_token

}

//这个就是我们进行yiifiltersauthQueryParamAuth调用认证的函数，下面会说到。

/*=======用Yii提供的认证方式验证token时需要自定义的函数：一定要实现，否则会报错=======*/

public function loginByAccessToken($accessToken, $type) {

//查询数据库中有没有存在这个token

return static::findIdentityByAccessToken($accessToken, $type);

}

public static function findByUsername($username)

{

return static::findOne(['username' => $username, 'status' => self::STATUS_ACTIVE]);

}

public function getId()

{

return $this->getPrimaryKey();

}

public function getAuthKey()

{

return $this->auth_key;

}

public function validateAuthKey($authKey)

{

return $this->getAuthKey() === $authKey;

}

这样一来，整个认证的过程就完成了。

现在对数据库user表中的access_token和访问时需携带的参数access-token进行简单说明：

1.user表中的参数access_token作用：

在实现IdentityInterface接口类，重写findIdentityByAccessToken()方法中，根据access_token校验用户身份，获取用户信息

2.url访问时，通过携带的参数access-token作用:

利用该参数进行认证。此参数其实是对yiifiltersauthQueryParanAuth中的属性$tokenParam设置的值。

细心的盆友会发现，这其实是UserController中行为中配置authenticator行为对应的认证类。

$tokenParam这个属性是设置url附带的token的参数key,我们可以在behaviors()这个函数中配置修改:

更改之后url附带的参数key就应该是token.

4.如此一来，我们先通过postman模拟不带access-token请求看结果

提示401 我们没有权限访问！

5.我们在请求的链接上携带正确的access-token，认证通过后，控制器会再继续执行其他检查（频率限制、操作权限等），才可以返回正确的用户信息。

如果携带access-token在user表中找不到与该字段对应的值，那么结果跟步骤4中显示的还是一样。这里访问http://www.dsgn.com/v1/user?access-token=123456，进行测试:

如果此处要指定哪些字段放在结果中，可以使用fields或者expand参数，如：http://www.dsgn.com/v1/user?fields=id,username&access-token=123456，这样GET的结果就只显示包含id，username这2个字段的结果了

6.授权：在用户认证通过后，你可能想检查他是否有足够的权限来访问请求资源的这个动作，那么就在api/modules/controllers下对应的控制器中重写函数checkAccess

public function checkAccess($action, $model = null, $params = [])

{

}

三、速率控制

说明：为防止滥用，可以增加速率限制。例如，限制每个用户的API的使用是在60秒内最多5次的API调用，

如果一个用户同一个时间段内太多的请求被接收，将返回响应状态代码 429 (这意味着过多的请求)。

1.在我们启用了速率限制后，Yii会自动使用yiifiltersRateLimiter为yii estController配置一个行为过滤器来执行速率限制检查。

如果速度超出限制，该速率限制器将抛出一个yiiwebTooManyRequestsHttpException。

2.给user表添加2个字段

`allowance` int(10) unsigned NOT NULL DEFAULT '0' COMMENT 'restful剩余的允许的请求数',

`allowance_updated_at` int(10) unsigned NOT NULL DEFAULT '0' COMMENT 'restful请求的UNIX时间戳数',

3.在api相应的控制器下，behaviors函数下添加以下代码：

$behaviors['rateLimiter'] = [

'class' => RateLimiter::className(),

'enableRateLimitHeaders' => true,

];

3.在user表中使用两列来记录容差和时间戳信息。为了提高性能，可以考虑使用缓存或NoSQL存储这些信息。修改api/models/User.php，改动或者加入以下代码：

use yiifiltersRateLimitInterface;

class User extends ActiveRecord implements IdentityInterface,RateLimitInterface

//限制同一接口某时间段过多的请求，需要实现yiifiltersRateLimitInterface接口的全部方法====================

// 返回某一时间允许请求的最大数量，比如设置60秒内最多5次请求（小数量方便我们模拟测试）

public function getRateLimit($request, $action){

return [5, 60];

}

// 返回剩余的允许的请求和相应的UNIX时间戳数当最后一次速率限制检查时

public function loadAllowance($request, $action){

return [$this->allowance, $this->allowance_updated_at];

}

// 保存允许剩余的请求数和当前的UNIX时间戳

public function saveAllowance($request, $action, $allowance, $timestamp){

$this->allowance = $allowance;

$this->allowance_updated_at = $timestamp;

$this->save();

}

4.通过postman请求http://www.dsgn.com/v1/user?access-token=12345，通过测试结果发现，60秒内调用超过5次API接口，我们会得到状态为429太多请求的异常信息。

注意：以下红框里面的头信息内容，可以通过在api/models/User.php中,通过设置禁用掉

5.错误处理

Yii的REST框架的HTTP状态代码可参考如下：

200: OK。一切正常。

201: 响应 POST 请求时成功创建一个资源。Location header 包含的URL指向新创建的资源。

204: 该请求被成功处理，响应不包含正文内容 (类似 DELETE 请求)。

304: 资源没有被修改。可以使用缓存的版本。

400: 错误的请求。可能通过用户方面的多种原因引起的，例如在请求体内有无效的JSON 数据，无效的操作参数，等等。

401: 验证失败。

403: 已经经过身份验证的用户不允许访问指定的 API 末端。

404: 所请求的资源不存在。

405: 不被允许的方法。请检查 Allow header 允许的HTTP方法。

415: 不支持的媒体类型。所请求的内容类型或版本号是无效的。

422: 数据验证失败 (例如，响应一个 POST 请求)。请检查响应体内详细的错误消息。

429: 请求过多。由于限速请求被拒绝。

500: 内部服务器错误。这可能是由于内部程序错误引起的。