Api参数规则
参数规则的概念
我们在调用接口时,大多数情况下,需要传入参数,如注册用户时,就需要传入用户的必要信息(如用户名、密码等等)才能完成注册功能,PhalAPI引入了参数规则这一概念,即:通过配置参数的规则,自动实现对参数的获取和验证,同时自动生成在线接口文档。
参数规则是针对各个接口服务而配置的多维规则数组,由接口类的getRules()方法返回。其中:
一维下标是接口类的方法名,对应接口服务的Action;
二维下标是类属性名称,对应在服务端获取通过验证和转换化的最终客户端参数;
三维下标name是接口参数名称,对应外部客户端请求时需要提供的参数名称。
代码示意如下:
public function getRules(){
return array(
'接口类方法名' => array(
'接口类属性' => array('name' => '接口参数名称', ... ... ),
),
);
}
在接口实现类里面getRules()成员方法配置参数规则后,便可以通过类属性的方式,根据配置指定的名称获取对应的接口参数,如:
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标记,可以非常方便地指定验证用的正则表达式。