yii2项目实战-restful api之授权验证完整案例

什么是restful风格的api呢？我们之前有写过大篇的文章来介绍其概念以及基本操作。

既然写过了，那今天是要说点什么吗？

这篇文章主要针对实际场景中api的部署来写。

我们今天就来大大的侃侃那些年api遇到的授权验证问题！独家干活，如果看完有所受益，记得不要忘记给我点赞哦。

业务分析

我们先来了解一下整个业务逻辑

用户在客户端填写登录表单
用户提交表单，客户端请求登录接口login
服务端校验用户的帐号密码，并返回一个有效的token给客户端
客户端拿到用户的token，将之存储在客户端比如cookie中
客户端携带token访问需要校验的接口比如获取用户个人信息接口
服务端校验token的有效性，校验通过，返回客户端需要的信息，校验失败，需要用户重新登录
本文我们以用户登录，获取用户的个人信息为例进行详细的一个说明。

以上，便是我们本篇文章要实现的重点。先别激动，也别紧张，分析好了之后，细节部分我们再一步一个脚印走下去。

准备工作

你应该已经有了一个api应用，如果你还没有，请先移步这里→_→ Restful api基础
对于客户端，我们准备采用postman进行模拟，如果你的google浏览器还没有安装postman，请先自行下载
要测试的用户表需要有一个名字叫做 api_token 的字段，没有的请先自行添加，并保证该字段足够长度
api应用开启了路由美化，并先配置post类型的login操作和get类型的signup-test操作
关闭了user组件的session会话
关于第5点，找到api/config/main.php，对user组件的配置修改如下

'components' => [
    'user' => [ 
        'identityClass' => 'common\models\User',
        'enableAutoLogin' => true,
        'enableSession' => false,
        'loginUrl' => null,
    ],
    // other code ......
],

对于第4点，通常我们可以对urlManager这样配置（依然是api/config/main.php）

'components' => [
    'urlManager' => [
        'enablePrettyUrl' => true,
        'showScriptName' => false,
        'enableStrictParsing' => true,
        'rules' => [
            [
                'class' => 'yii\rest\UrlRule',
                'controller' => ['v1/user'],
                'extraPatterns' => [
                    'POST login' => 'login',
                    'GET signup-test' => 'signup-test',
                ]
            ],
        ]
    ],
    // ......
],

但是，当api应用需要配置的路由逐渐增多的时候，会导致我们的配置文件main.php变得非常冗余，不美观。我们准备在api/config目录下增加一个url-rules.php，专门用于管理需要配置的路由，现在我们把urlManager::rules改写如下

'urlManager' => [
    'enablePrettyUrl' => true,
    'showScriptName' => false,
    'enableStrictParsing' => true,
    'rules' => require(__DIR__ . '/url-rules.php'),
],

同样，我们看下url-rules.php是怎么改写的，有兴趣的可以在继续阅读之前先动手尝试一番

<?php
/**
 * 在这里配置所有的路由规则
 */
$urlRuleConfigs = [
    [
        'controller' => ['v1/user'],
        'extraPatterns' => [
            'POST login' => 'login',
            'GET signup-test' => 'signup-test',
        ],
    ],
];
/**
 * 基本的url规则配置
 */
function baseUrlRules($unit)
{
    $config = [
        'class' => 'yii\rest\UrlRule',
    ];
    return array_merge($config, $unit);
}
return array_map('baseUrlRules', $urlRuleConfigs);

如此一来，以后我们增加新的路由，只需要在$urlRuleConfigs数组中增加单元项即可。

signup-test 是我们后面添加测试用户的操作，为登录操作提供便利。其他操作我们后续再做添加。

认证类的选择

我们在 api\modules\v1\controllers\UserController 中设定的 model 类指向 common\models\User 类，为了说明重点这里我们就不单独拿出来重写了，看各位需要，有必要的话再单独copy一个User类到 api\models下。

校验用户权限一开始我们选择的是 yii\filters\auth\QueryParamAuth ，实际上我们建议选择 yii\filters\auth\HttpBearerAuth。

二者的区别：前者通过get方式传递token，后者通过header头传递。get传递token的方式有一个风险，以nginx为例，实际请求的地址假设是 /controller/action?token=123，那么nginx的access.log就会把这个访问地址记录下来，对于有访问这个日志文件的管理人员而言，显而易见我们就把用户的token暴露了，这是非常不好的一件事，所以我们推荐使用header头进行传递。即我们选择 yii\filters\auth\HttpBearerAuth 作为接收token并校验。

找到 api/modules/v1/controllers/UserController，我们重写父类的behaviors方法

use yii\filters\auth\HttpBearerAuth;
public function behaviors() 
{
    return ArrayHelper::merge(parent::behaviors(), [ 
        'authenticator' => [ 
            'class' => HttpBearerAuth::className() 
        ]
    ] );
}

如此一来，那岂不是所有访问user的操作都需要认证了？那不行，客户端第一次访问 login 操作的时候哪来的 token。yii\filters\auth\HttpBearerAuth 对外提供一个属性，用于过滤不需要验证的 action。我们将 UserController 的 behaviors 方法稍作如下修改

public function behaviors() 
{
    return ArrayHelper::merge (parent::behaviors(), [ 
            'authenticator' => [ 
                'class' => HttpBearerAuth::className(),
                'optional' => [
                    'login',
                    'signup-test'
                ],
            ] 
    ] );
}

optional处填写要忽略校验的action，如果不写，而我们恰巧又没有token可以传递，那么服务端默认会响应如下信息给客户端

{"code":401,"msg":"Unauthorized"}

这样 login 和 signup-test 操作无需权限验证即可访问了。

添加测试用户

为了测试登陆校验，我们写一个简单的方法，往user表里面插入两条数据。实际上这往往是一个“注册”操作，为了简便，这里模拟操作。

UserController增加signupTest操作，注意此方法不属于讲解范围之内，我们仅用于方便测试。

use common\models\User;
/**
 * 添加测试用户
 */
public function actionSignupTest ()
{
    $user = new User();
    $user->generateAuthKey();
    $user->setPassword('222');
    $user->username = '222';
    $user->email = '222@222.com';

    return $user->save(false);
}

如上，我们添加了一个username是222，密码是222的用户。但是有同学可能注意到了，postman中返回的结果是true，这就显然很是问题了。实际上服务端应该有一套自定义的响应规则，我们放后面再讲。

登录操作

假设用户在客户端输入用户名和密码进行登录，我们想让用户登录成功后，把 token 返回给用户。

来看Login操作的实现

use api\models\LoginForm;
/**
 * 登录
 */
public function actionLogin ()
{
    $model = new LoginForm;
    $model->setAttributes(Yii::$app->request->post());
    if (($user = $model->login())) {
        return [
            'code' => 0, 
            'data' => [
                'token' => $user->api_token
            ],
        ];
    } else {
        $errors = $model->errors;
        $firstError = current($errors);
        return [
            'code' => 10001, 
            'msg' => $firstError[0]
        ];
    }
}

有同学要问啦，这 Login 操作的返回值有点特殊呢。事实上这不仅仅是大家想要的格式数据，服务端返回固定格式的数据，客户端也方便处理。

下面我们看一下 LoginForm 的具体实现。

新建 api\models\LoginForm.php

<?php
namespace api\models;
use Yii;
use yii\base\Model;
use common\models\User;
/**
 * Login form
 */
class LoginForm extends Model
{
    public $username;
    public $password;
    private $_user;
    const GET_API_TOKEN = 'generate_api_token';
    public function init ()
    {
        parent::init();
        $this->on(self::GET_API_TOKEN, [$this, 'onGenerateApiToken']);
    }
    /**
     * @inheritdoc
     * 对客户端表单数据进行验证的rule
     */
    public function rules()
    {
        return [
            [['username', 'password'], 'required'],
            ['password', 'validatePassword'],
        ];
    }
    /**
     * 自定义的密码认证方法
     */
    public function validatePassword($attribute, $params)
    {
        if (!$this->hasErrors()) {
            $this->_user = $this->getUser();
            if (!$this->_user || !$this->_user->validatePassword($this->password)) {
                $this->addError($attribute, '用户名或密码错误.');
            }
        }
    }
    /**
     * @inheritdoc
     */
    public function attributeLabels()
    {
        return [
            'username' => '用户名',
            'password' => '密码',
        ];
    }
    /**
     * Logs in a user using the provided username and password.
     *
     * @return boolean whether the user is logged in successfully
     */
    public function login()
    {
        if ($this->validate()) {
            $this->trigger(self::GET_API_TOKEN);
            return $this->_user;
        } else {
            return null;
        }
    }
    /**
     * 根据用户名获取用户的认证信息
     *
     * @return User|null
     */
    protected function getUser()
    {
        if ($this->_user === null) {
            $this->_user = User::findByUsername($this->username);
        }
        return $this->_user;
    }
    /**
     * 登录校验成功后，为用户生成新的token
     * 如果token失效，则重新生成token
     */
    public function onGenerateApiToken ()
    {
        if (!User::apiTokenIsValid($this->_user->api_token)) {
            $this->_user->generateApiToken();
            $this->_user->save(false);
        }
    }
}

简单的看一下，我们在 UserController的login操作中调用LoginForm的login操作后都发生了什么

1、调用LoginForm的login方法

2、调用validate方法，随后对rules进行校验

3、rules校验中调用validatePassword方法，对用户名和密码进行校验

4、validatePassword方法校验的过程中调用LoginForm的getUser方法，通过common\models\User类的findByUsername获取用户，找不到或者common\models\User的validatePassword对密码校验失败则返回error

5、触发LoginForm::GENERATE_API_TOKEN事件，调用LoginForm的onGenerateApiToken方法,通过common\models\User的apiTokenIsValid校验token的有效性，如果无效，则调用User的generateApiToken方法重新生成

注意common\models\User类必须是用户的认证类，如果不知道如何创建完善该类，请围观这里 用户管理之user组件的配置

下面补充 common\models\User 的相关方法

/**
 * 生成 api_token
 */
public function generateApiToken()
{
    $this->api_token = Yii::$app->security->generateRandomString() . '_' . time();
}
/**
 * 校验api_token是否有效
 */
public static function apiTokenIsValid($token)
{
    if (empty($token)) {
        return false;
    }
    $timestamp = (int) substr($token, strrpos($token, '_') + 1);
    $expire = Yii::$app->params['user.apiTokenExpire'];
    return $timestamp + $expire >= time();
}

继续补充apiTokenIsValid方法中涉及到的token有效期，在 api\config\params.php 文件内增加

<?php
return [
    // ...
    // token 有效期默认1天，可以按照自己的项目需求配置
    'user.apiTokenExpire' => 1*24*3600,
];

到这里呢，客户端登录服务端返回token就完成了。

我们用postman模拟登陆操作

用户名密码正确的情况下，结果如下

{
    "code": 0,
    "data": {
        "token": "wx8xDJWgc8Y9sOomHeCvQAib1d4lkV43_1514461900"
    }
}

用户名或者密码错误时，结果如下

{
    "code": 10001,
    "msg": "用户名或密码错误."
}

按照文中一开始的分析，客户端应该把获取到的token存到本地，比如cookie中。以后再需要token校验的接口访问中，从本地读取比如从cookie中读取并访问接口即可。

根据token请求用户的认证操作

假设客户端已经把获取到的token保存起来了，我们再以访问用户信息的接口为例。

yii\filters\auth\HttpBearerAuth 类是从header头的Authorization这个key中进行获取的，其格式如下

Authorization: Bearer your-token

注意 Authorization: Bearer 是固定格式，其中 Bearer 后面是 空格 + 真正的token值（token是login操作下发的那个token）

下面我们对userProfile操作配置一个路由规则，api/config/url-rules.php内

'extraPatterns' => [
    'POST login' => 'login',
    'GET signup-test' => 'signup-test',
    'GET user-profile' => 'user-profile',
]

我们用postman模拟请求下 /v1/users/user-profile 接口，发现报错了，提示我们如下信息

\"findIdentityByAccessToken\" is not implemented.

这是怎么回事呢？

我们找到HttpBearerAuth的authenticate方法

public function authenticate($user, $request, $response)
{
    $authHeader = $request->getHeaders()->get('Authorization');
    if ($authHeader !== null && preg_match('/^Bearer\s+(.*?)$/', $authHeader, $matches)) {
        $identity = $user->loginByAccessToken($matches[1], get_class($this));
        if ($identity === null) {
            $this->handleFailure($response);
        }
        return $identity;
    }
    return null;
}

注意看有这么一句 $user->loginByAccessToken，随后我们找到 User类的findIdentityByAccessToken方法发现异常是这里抛出的。

这就好办了，我们就来实现下 common\models\User 类的 findIdentityByAccessToken 方法吧

public static function findIdentityByAccessToken($token, $type = null)
{
    // 如果token无效的话，
    if(!static::apiTokenIsValid($token)) {
        throw new \yii\web\UnauthorizedHttpException("token is invalid.");
    }
    return static::findOne(['api_token' => $token, 'status' => self::STATUS_ACTIVE]);
    // throw new NotSupportedException('"findIdentityByAccessToken" is not implemented.');
}

验证完token的有效性，下面就要开始实现获取用户信息的主要业务逻辑了。

从刚才的HttpBearerAuth的authenticate方法，我们发现，这个方法刚好是获取用户信息，所以我们在actionUserProfile中可以这么写

/**
 * 获取用户信息
 */
public function actionUserProfile ()
{
    // 到这一步，token都认为是有效的了
    // 下面只需要实现业务逻辑即可
    $user = $this->authenticate(Yii::$app->user, Yii::$app->request, Yii::$app->response);
    return [
        'id' => $user->id,
        'username' => $user->username,
        'email' => $user->email,
    ];
}

至于为什么可以直接调用authenticate方法，不懂的可以回去再看看我们之前讲过的行为。

通过postman模拟看下结果如何

注意header头部分的key-value的写法，实际上我们上面已经提醒过了。

有同学可能发现一个非常严重的问题，假如token写错了，我们来看一下结果

注意看，我们在token前面添加了一个字符 1，但是结果却完全不一样，更要命的是，http响应的状态码是401，并不是200！！！
另一个存在的问题也引起了我们的注意。

假如我们请求了一个不存在的路由，我们预期的结果是 {“msg”:”Not Found”,”code”:404}，但是服务端返回给我们的却是一个404页面的html代码！！！

怎么解决这几个问题是当下非常着急的事。

别着急，别着急，问题先放在这里，后面我们就解决掉。

服务端返回的数据类型定义

在postman中我们可以以何种数据类型输出的接口的数据，但是，有些人发现，当我们把postman模拟请求的地址copy到浏览器地址栏，返回的又却是xml格式了，而且我们明明在UserProfile操作中返回的是数组，这怎么回事？

这其实是官方捣的鬼啦，我们一层层源码追下去，发现在yii\rest\Controller类中，有一个 contentNegotiator行为，该行为指定了允许返回的数据格式formats是json和xml，返回的最终的数据格式根据请求头中Accept包含的首先出现在formats中的为准，你可以在yii\filters\ContentNegotiator的negotiateContentType方法中找到答案。

你可以在浏览器的请求头中看到

Accept:

text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8

即application/xml首先出现在formats中，所以返回的数据格式是xml类型，如果客户端获取到的数据格式想按照json进行解析，只需要设置请求头的Accept的值等于application/json即可。也就是说服务端定义好json和xml，至于客户端想要什么类型的数据，完全取决于客户端Accept头的设置。这是一种很好的设置。

但是有同学可能要说，这样太麻烦了，啥年代了，谁还用xml，我就想服务端输出json格式的数据，怎么做？

以 UserProfile 为例，我们可以在 return 之前设置 Response::format

Yii::$app->response->format = yii\web\Response::FORMAT_JSON;

但是，一个项目下来，每个操作都这么写，不仅麻烦，而且不够灵活，如果真有一天要用xml怎么办？一个一个的再去改？难怪你天天加班到半夜哦。

Reponse 组件有一个 EVENT_BEFORE_SEND 事件，我们可以为这个事件绑定一段事件处理程序，统一处理。

来看看怎么做。api\config\main.php文件中增加对response的配置

'response' => [
    'class' => 'yii\web\Response',
    'on beforeSend' => function ($event) {
        $response = $event->sender;
        $response->format = yii\web\Response::FORMAT_JSON;
    },
],

有同学完全懵B中，这写法完全看不懂呀，我们在yii2源码分析里全面彻底的都做了讲解，有兴趣的可以去看看。

如此，不管你客户端传什么，服务端最终输出的都会是json格式的数据了。

当然，你也可以配置 yii\filters\ContentNegotiator 行为，建议优先选择上面的配置。

自定义错误处理机制

再来看另外一个比较常见的问题：

你看我们上面几个方法哈，返回的结果是各式各样的，这样就给客户端解析增加了困扰，而且一旦有异常抛出，返回的代码还都是一堆一堆的，头疼，怎么办？

说到这个问题之前呢，我们先说一下yii中相关的异常处理类，当然，有很多。比如下面常见的一些，其他的自己去挖掘

yii\web\BadRequestHttpException
yii\web\ForbiddenHttpException
yii\web\NotFoundHttpException
yii\web\ServerErrorHttpException
yii\web\UnauthorizedHttpException
yii\web\TooManyRequestsHttpException

实际开发中各位要善于去利用这些类去捕获异常，抛出异常。

我们回到重点，来说说如何自定义接口异常响应或者叫自定义统一的数据格式，比如向下面这种配置，统一响应客户端的格式标准。

'response' => [
    'class' => 'yii\web\Response',
    'on beforeSend' => function ($event) {
        $response = $event->sender;
        $response->data = [
            'code' => $response->getStatusCode(),
            'data' => $response->data,
            'message' => $response->statusText
        ];
        $response->format = yii\web\Response::FORMAT_JSON;
    },
],

统一response响应

来说最后一个问题，如何统一响应格式，可能你注意到我们上面几个操作中，返回的格式以及错误的响应格式，乱七八糟的，这对一个客户端的同学来说无疑是非常麻烦的一件事。当然，这也非常能说明你能力的一个问题。

其实还是 Response::EVENT_BEFORE_SEND 事件处理程序的问题。你只需要有一套严格的返回值，在该事件的处理程序中配合处理一下就好了，下面是我针对上面几种返回值封装的简单例子，你可以参考一下

'response' => [
    'class' => 'yii\web\Response',
    'on beforeSend' => function ($event) {
        $response = $event->sender;
        $code = $response->getStatusCode();
        $msg = $response->statusText;

        $rdata = [];

        if ($code != 200) {
            $response->setStatusCode(200);
            $rdata['msg'] = $msg;
            $rdata['code'] = $code;
        } else {
            $data = $response->data;
            if (isset($data['code'])) {
                $rdata['code'] = $data['code'];
            }
            if (isset($data['data'])) {
                $rdata['data'] = $data['data'];
            }
            if (isset($data['msg'])) {
                $rdata['msg'] = $data['msg'];
            }
        }
        $response->data = $rdata;
        $response->format = yii\web\Response::FORMAT_JSON;
    },
],

其实这部分完全可以按照自己的方法自定义，这里简单的举一个例子给各位参考。

补充：有同学反馈，postman模拟正常，ajax跨域请求就报404，怎么解？

此类问题只需要做两个步骤：

1、对要请求的路由支持OPTIONS请求，以user-profile为例，其路由配置修改如下

'GET,OPTIONS user-profile' => 'user-profile',

2、对应控制器的behaviors方法增加一个跨域过滤，允许请求来源域访问，同时允许请求头携带authorization，这个是携带token的key

public function behaviors()
{
    return array_merge(parent::behaviors(), [
        'corsFilter'  => [
            'class' => \yii\filters\Cors::className(),
            'cors'  => [
                'Origin' => ['*'],
                'Access-Control-Request-Headers' => ['authorization'],
            ],
        ],
        // ...
    ]);
}

另外，由于web服务器的作用，apache和nginx都应该做单独的配置或者重启，具体各位可以google搜索一下。