Api参数规则

参数规则的概念

我们在调用接口时，大多数情况下，需要传入参数，如注册用户时，就需要传入用户的必要信息（如用户名、密码等等）才能完成注册功能，PhalAPI引入了参数规则这一概念，即：通过配置参数的规则，自动实现对参数的获取和验证，同时自动生成在线接口文档。

参数规则是针对各个接口服务而配置的多维规则数组，由接口类的getRules()方法返回。其中：

一维下标是接口类的方法名，对应接口服务的Action；
二维下标是类属性名称，对应在服务端获取通过验证和转换化的最终客户端参数；
三维下标name是接口参数名称，对应外部客户端请求时需要提供的参数名称。

代码示意如下：

public function getRules() {
    return array(
        '接口类方法名' => array(
            '接口类属性' => array('name' => '接口参数名称', ... ... ),
        ),
    );
}

在接口实现类里面getRules()成员方法配置参数规则后，便可以通过类属性的方式，根据配置指定的名称获取对应的接口参数，如：

<?php
namespace App\Api;

use PhalApi\Api;

class User extends Api {

    public function getRules() {
        return array(
            'login' => array(
                'username' => array('name' => 'username'),
                'password' => array('name' => 'password'),
            ),
        );
    }

    public function login() {
        return array('username' => $this->username, 'password' => $this->password);
    }
}

上述Api可以通过如下方式访问并传入参数：

http://localhost/phpapi/public/?s=user.login&username=yangjh&password=123

显示结果如下：

{"ret":200,"data":{"username":"yangjh","password":"123"},"msg":""}

设置参数规则

PhalAPI设置了三个级别的参数规则设置机制，优先级别由低到高分别是：

系统参数规则；
应用参数规则；
接口参数规则。

系统参数

系统参数是指被框架保留使用的参数。目前已被PhalApi占用的系统参数只有一个，即：service参数（缩写为s参数）。

应用参数

应用参数是指在一个接口系统中，全部项目的全部接口都需要的参数或者通用的参数。假设全部的接口服务都需要必须的签名sign参数，就可以通过./config/app.php中的apiCommonRules进行应用参数规则的配置。例如：

    'apiCommonRules' => array(
        'sign' => array('name' => 'sign', 'require' => true),
    ),

接口参数

接口参数是指各个具体的接口服务所需要的参数，为特定的接口服务所持有，独立配置。例如：

public function getRules() {
        return array(
            'login' => array(
                'username' => array('name' => 'username', 'require' => true，'regex' => '/^[\x80-\xff]{6,}$/'),
                'password' => array('name' => 'password', 'require' => true, 'min' => 6),
            ),
        );
    }

PhalAPI内置了常用的规则，比如长度大小、是否为空、编码方式等等，其中regex标记，可以非常方便地指定验证用的正则表达式。

API接口参数