用yii2给app写接口(下)

Posted 我是谁???

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了用yii2给app写接口(下)相关的知识,希望对你有一定的参考价值。

上一节里我们讲了如何用Yii2搭建一个能够给App提供数据的API后台应用程序。那么今天我们就来探讨下授权认证通过API接口向服务器提交数据以及如何控制API接口返回那些数据,不能返回那些数据。

授权认证

业务分析

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

  1. 用户在客户端填写登录表单
  2. 用户提交表单,客户端请求登录接口login
  3. 服务端校验用户的帐号密码,并返回一个有效的token给客户端
  4. 客户端拿到用户的token,将之存储在客户端比如cookie中
  5. 客户端携带token访问需要校验的接口比如获取用户个人信息接口
  6. 服务端校验token的有效性,校验通过,反正返回客户端需要的信息,校验失败,需要用户重新登录

本文我们以用户登录,获取用户的个人信息为例进行详细的完整版说明。

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

准备工作

  1. 对于客户端,我们准备采用postman进行模拟,如果你的google浏览器还没有安装postman,请先自行下载
  2. 要测试的用户表需要有一个api_token的字段,没有的请先自行添加,并保证该字段足够长度
  3. api应用开启了路由美化,并先配置post类型的login操作和get类型的signup-test操作
  4. 关闭了user组件的session会话

关于上面准备工作的第4点和第5点,我们贴一下代码方便理解


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


signup操作我们后面添加测试用户,为登录操作提供便利。 另外需要指出的是POST对应signup,不能对应signup-test,否则404错误。GET可以对应signup-test。我们这里采用的是POST方法。

认证类的选择

我们在api\\modules\\v1\\controllers\\UserController中设定的model类指向 api\\models\\User类 。

校验用户权限我们以 yii\\filters\\auth\\QueryParamAuth 为例


use yii\\filters\\auth\\QueryParamAuth;

public function behaviors() 
{
    return ArrayHelper::merge (parent::behaviors(), [ 
            \'authenticator\' => [ 
                \'class\' => QueryParamAuth::className() 
            ] 
    ] );
}

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


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


这样login操作就无需权限验证即可访问了。

添加测试用户

为了避免让客户端登录失败,我们先写一个简单的方法,往user表里面插入两条数据,便于接下来的校验。

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


use api\\models\\User;
/**
 * 添加测试用户
 */
public function actionSignup ()
{
    $user = new User();
    $user->username = \'admin\'; 
$user->setPassword(\'123456\');
$user->generateAuthKey();

$user->save(false);
return [ \'code\' => 200 ];
}

如上,我们添加了一个username是admin,密码是123456的用户

登录操作

假设用户在客户端输入用户名和密码进行登录,服务端login操作其实很简单,大部分的业务逻辑处理都在api\\models\\loginForm上,来先看看login的实现


use api\\models\\LoginForm;

/**
 * 登录
 */
public function actionLogin ()
{
    $model = new LoginForm;
    $model->setAttributes(Yii::$app->request->post());
    if ($user = $model->login()) {
        if ($user instanceof IdentityInterface) {
            return $user->api_token;
        } else {
            return $user->errors;
        }
    } else {
        return $model->errors;
    }
}

登录成功后这里给客户端返回了用户的token,再来看看登录的具体逻辑的实现:

新建api\\models\\LoginForm.php

<?php
namespace api\\models;

use Yii;
use yii\\base\\Model;
use api\\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给客户端就完成了。

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

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

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

yii\\filters\\auth\\QueryParamAuth类认定的token参数是 access-token,我们可以在行为中修改下


public function behaviors() 
{
    return ArrayHelper::merge (parent::behaviors(), [ 
            \'authenticator\' => [ 
                \'class\' => QueryParamAuth::className(),
                \'tokenParam\' => \'token\',
                \'optional\' => [
                    \'login\',
                    \'signup\'
                ],
            ] 
    ] );
}

这里将默认的access-token修改为token。

我们在配置文件的urlManager组件中增加对userProfile操作


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

我们用postman模拟请求访问下 /v1/users/user-profile?token=apeuT9dAgH072qbfrtihfzL6qDe_l4qz_1479626145发现,抛出了一个异常

\\"findIdentityByAccessToken\\" is not implemented.

这是怎么回事呢?

我们找到 yii\\filters\\auth\\QueryParamAuth 的authenticate方法,发现这里调用了 common\\models\\User类的loginByAccessToken方法,有同学疑惑了,common\\models\\User类没实现loginByAccessToken方法为啥说findIdentityByAccessToken方法没实现?如果你还记得common\\models\\User类实现了yii\\web\\user类的接口的话,你应该会打开yii\\web\\User类找答案。没错,loginByAccessToken方法在yii\\web\\User中实现了,该类中调用了common\\models\\User的findIdentityByAccessToken,但是我们看到,该方法中通过throw抛出了异常,也就是说这个方法要我们自己手动实现!

这好办了,我们就来实现下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的有效性,下面就要开始在UserController中实现主要的业务逻辑部分了。


/**
 * 获取用户信息
 */
public function actionUserProfile ($token)
{
    // 到这一步,token都认为是有效的了
    // 下面只需要实现业务逻辑即可,下面仅仅作为案例,比如你可能需要关联其他表获取用户信息等等
    $user = User::findIdentityByAccessToken($token);
    return [
        \'id\' => $user->id,
        \'username\' => $user->username, 
    ];
}

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

在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即可

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

办法就是用来解决问题滴,来看看怎么做。api\\config\\main.php文件中增加对response的配置


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

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

自定义错误处理机制

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

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

说到这个问题之前呢,我们先说一下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;
    },
],

说道了那么多,本文就要结束了,刚开始接触的同学可能有一些蒙,不要蒙,慢慢消化,先知道这么个意思,了解下restful api接口在整个过程中是怎么用token授权的就好。这样真正实际用到的时候,你也能举一反三!老样子,有任何问题或者赞美的话,下方留言哦

通过API接口向服务器提交数据

参看下图:

控制API接口返回那些数据,不能返回那些数据

其实就是控制返回的字段,具体怎么处理,等我有时间了再总结吧。

以上是关于用yii2给app写接口(下)的主要内容,如果未能解决你的问题,请参考以下文章

用yii2进行(curd)接口开发(普通类型)整个流程:

微信App支付

Yii2 使用 RESTful 写API接口 实例

yii2.0用户登录,退出判断(摘录)

Python如何调用别人写好的脚本

Yii2数据接口