# Api接口服务层
**Api接口层**称为接口服务层，负责对客户端的请求进行响应，处理接收客户端传递的参数，进行高层决策并对领域业务层进行调度，最后将处理结果返回给客户端。
## 接口参数规则配置
接口参数，对于接口服务本身来说，是非常重要的。对于外部调用的客户端来说，同等重要。对于接口参数，我们希望能够既减轻后台开发对接口参数获取、判断、验证、文档编写的痛苦；又能方便客户端快速调用，明确参数的意义。由此，我们引入了**参数规则**这一概念，即：通过配置参数的规则，自动实现对参数的获取和验证，同时自动生成在线接口文档。
### 一个简单的示例
假设我们现在需要提供一个用户登录的接口，接口参数有用户名和密码，那么新增的接口类和规则如下：
```php
// 文件 ./src/app/Api/User.php
<?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);
}
}
```
当请求此接口服务，并类似这样带上username和password参数时：
```
/?s=User.Login&username=dogstar&password=123456
```
就可以得到这样的返回结果。
```
{"ret":0,"data":{"username":"dogstar","password":"123456"},"msg":""}
```
### 参数规则格式
参数规则是针对各个接口服务而配置的多维规则数组，由接口类的```getRules()```方法返回。其中，
+ 一维下标是接口类的方法名，对应接口服务的Action；
+ 二维下标是类属性名称，对应在服务端获取通过验证和转换化的最终客户端参数；
+ 三维下标```name```是接口参数名称，对应外部客户端请求时需要提供的参数名称。
小结如下：
```php
public function getRules() {
return array(
'接口类方法名' => array(
'接口类属性' => array('name' => '接口参数名称', ... ... ),
),
);
}
```
在接口实现类里面```getRules()```成员方法配置参数规则后，便可以通过类属性的方式，根据配置指定的名称获取对应的接口参数，如上面的：```$this->username```和```$this->password```。
### 三级参数规则配置
参数规则主要有三种，分别是：系统参数规则、应用参数规则、接口参数规则。
#### 系统参数
系统参数是指被框架保留使用的参数。目前已被PhalApi占用的系统参数只有一个，即：service参数（缩写为s参数），前面已有介绍。
#### 应用参数
应用参数是指在一个接口系统中，全部项目的全部接口都需要的参数，或者通用的参数。假如我们的商城接口系统中全部的接口服务都需要必须的签名sign参数，以及非必须的版本号，则可以在```./config/app.php```中的```apiCommonRules```进行应用参数规则的配置：
```php
<?php
return array(
/**
* 应用接口层的统一参数
*/
'apiCommonRules' => array(
//签名
'sign' => array(
'name' => 'sign', 'require' => true,
),
//客户端App版本号，默认为：1.4.0
'version' => array(
'name' => 'version', 'default' => '1.4.0',
),
),
)
```
#### 接口参数
接口参数是指各个具体的接口服务所需要的参数，为特定的接口服务所持有，独立配置。并且进一步在内部又细分为两种：
+ **通用接口参数规则**：使用```*```作为下标，对当前接口类全部的方法有效。
+ **指定接口参数规则**：使用方法名作为下标，只对接口类的特定某个方法有效。
例如为了加强安全性，需要为全部的用户接口服务都加上长度为4位的验证码参数：
```php
public function getRules() {
return array(
'*' => array(
'code' => array('name' => 'code', 'require' => true, 'min' => 4, 'max' => 4),
),
'login' => array(
'username' => array('name' => 'username', 'require' => true),
'password' => array('name' => 'password', 'require' => true, 'min' => 6),
),
);
}
```
现在，当再次请求用户登录接口，除了要提供用户名和密码外，我们还要提供验证码code参数。并且，对于Api\User类的其他方法也一样。
#### 多个参数规则时的优先级
当同一个参数规则分别在应用参数、通用接口参数及指定接口参数出现时，后面的规则会覆盖前面的，即具体化的规则会替换通用的规则，以保证接口参数满足特定场合的定制要求。
简而言之，多个参数规则的优先级从高到下，分别是（正如你想到的那样）：
+ 1、指定接口参数规则
+ 2、通用接口参数规则
+ 3、应用参数规则
+ 4、系统参数规则
## 参数规则配置详细说明
具体的参数规则，根据不同的类型有不同的配置选项，以及一些公共的配置选项。目前，主要的类型有：字符串、整数、浮点数、布尔值、时间戳/日期、数组、枚举类型、文件上传和回调函数。
类型 type|参数名称 name|是否必须 require|默认值 default|最小值 min，最大值 max|更多配置选项（无特殊说明，均为可选）
---|---|---|---|---|---
字符串|string|TRUE/FALSE，默认FALSE|应为字符串|可选|regex选项用于配置正则匹配的规则；format选项用于定义字符编码的类型，如utf8、gbk、gb2312等
整数|int|TRUE/FALSE，默认FALSE|应为整数|可选|---
浮点数|float|TRUE/FALSE，默认FALSE|应为浮点数|可选|---
布尔值|boolean|TRUE/FALSE，默认FALSE|true/false|---|以下值会转换为TRUE：ok，true，success，on，yes，1，以及其他PHP作为TRUE的值
时间戳/日期|date|TRUE/FALSE，默认FALSE|日期字符串|可选，仅当为format配置为timestamp时才判断，且最值应为时间戳|format选项用于配置格式，为timestamp时会将字符串的日期转换为时间戳
数组|array|TRUE/FALSE，默认FALSE|字符串或者数组，为非数组会自动转换/解析成数组|可选，判断数组元素个数|format选项用于配置数组和格式，为explode时根据separator选项将字符串分割成数组, 为json时进行JSON解析
枚举|enum|TRUE/FALSE，默认FALSE|应为range选项中的某个元素|---|必须的range选项，为一数组，用于指定枚举的集合
文件|file|TRUE/FALSE，默认FALSE|数组类型|可选，用于表示文件大小范围，单位为B|range选项用于指定可允许上传的文件类型；ext选项用于表示需要过滤的文件扩展名
回调|callable/callback|TRUE/FALSE，默认FALSE|---|---|callable/callback选项用于设置回调函数，params选项为回调函数的第三个参数（另外第一个为参数值，第二个为所配置的规则）
### 公共配置选项
公共的配置选项，除了上面的类型、参数名称、是否必须、默认值，还有说明描述、数据来源。下面分别简单说明。
+ **类型 type**
用于指定参数的类型，可以是string、int、float、boolean、date、array、enum、file、callable，或者自定义的类型。未指定时，默认为字符串。
+ **参数名称 name**
接口参数名称，即客户端需要传递的参数名称。与PHP变量规则一样，以下划线或字母开头。此选项必须提供，否则会提示错误。
+ **是否必须require**
为TRUE时，表示此参数为必须值；为FALSE时，表示此参数为可选。未指定时，默认为FALSE。
+ **默认值 default**
未提供接口参数时的默认值。未指定时，默认为NULL。
+ **最小值 min，最大值 max**
部分类型适用。用于指定接口参数的范围，比较时采用的是闭区间，即范围应该为：[min, max]。也可以只使用min或max，若只配置了min，则表示：[min, +∞)；若只配置了maz，则表示：(-∞, max]。
+ **说明描述 desc**
用于自动生成在线接口详情文档，对参数的含义和要求进行扼要说明。未指定时，默认为空字符串。
+ **数据来源 source**
指定当前单个参数的数据来源，可以是post、get、cookie、server、request、header、或其他自定义来源。未指定时，默认为统一数据源。目前支持的source与对应的数据源映射关系如下：
source|对应的数据源
---|---
post | $_POST
get | $_GET
cookie | $_COOKIE
server | $_SERVER
request | $_REQUEST
header | $_SERVER['HTTP_X']
通过source参数可以轻松、更自由获取不同来源的参数。以下是一些常用的配置示例。
```php
// 获取HTTP请求方法，判断是POST还是GET
'method' => array('name' => 'REQUEST_METHOD', 'source' => 'server'),
// 获取COOKIE中的标识
'is_new_user' => array('name' => 'is_new_user', 'source' => 'cookie'),
// 获取HTTP头部中的编码，判断是否为utf-8
'charset' => array('name' => 'Accept-Charset', 'source' => 'header'),
```
若配置的source为无效或非法时，则会抛出异常。如配置了```'source' => 'NOT_FOUND'```，会得到：
```
"msg": "服务器运行错误: 参数规则中未知的数据源：NOT_FOUND"
```
### 9种参数类型
对于各种参数类型，结合示例说明如下。
+ **字符串 string**
当一个参数规则未指定类型时，默认为string。如最简单的：
```php
array('name' => 'username')
```
> **温馨提示：**这一小节的参数规则配置示例，都省略了类属性，以关注配置本身的内容。
这样就配置了一个参数规则，接口参数名字叫username，类型为字符串。
一个完整的写法可以为：
```php
array('name' => 'username', 'type' => 'string', 'require' => true, 'default' => 'nobody', 'min' => 1, 'max' => 10)
```
这里指定了为必选参数，默认值为nobody，且最小长度为1个字符，最大长度为10个字符，若传递的参数长度过长，如```&username=alonglonglonglongname```，则会异常失败返回：
```
"msg": "非法请求：username.len应该小于等于10, 但现在username.len = 21"
```
当需要验证的是中文的话，由于一个中文字符会占用3个字节。所以在min和max验证的时候会出现一些问题。为此，PhalApi提供了format配置选项，用于指定字符集。如：
```php
array('name' => 'username', 'type' => 'string', 'format' => 'utf8', 'min' => 1, 'max' => 10)
```
我们还可以使用```regex```下标来进行正则表达式的验证，一个邮箱的例子是：
```php
array('name' => 'email', 'regex' => "/^([0-9A-Za-z\\-_\\.]+)@([0-9a-z]+\\.[a-z]{2,3}(\\.[a-z]{2})?)$/i")
```
+ **整型 int**
整型即自然数，包括正数、0和负数。如通常数据库中的id，即可配置成：
```php
array('name' => 'id', 'type' => 'int', 'require' => true, 'min' => 1)
```
当传递的参数，不在其配置的范围内时，如```&id=0```，则会异常失败返回：
```
"msg": "非法请求：id应该大于或等于1, 但现在id = 0"
```
另外，对于常见的分页参数，可以这样配置：
```php
array('name' => 'page_num', 'type' => 'int', 'min' => 1, 'max' => 20, 'default' => 20)
```
即每页数量最小1个，最大20个，默认20个。
+ **浮点 float**
浮点型，类似整型的配置，此处略。
+ **布尔值 boolean**
布尔值，主要是可以对一些字符串转换成布尔值，如ok，true，success，on，yes，以及会被PHP解析成true的字符串，都会转换成TRUE。如通常的“是否记住我”参数，可配置成：
```php
array('name' => 'is_remember_me', 'type' => 'boolean', 'default' => TRUE)
```
则以下参数，最终服务端会作为TRUE接收。
```
?is_remember_me=ok
?is_remember_me=true
?is_remember_me=success
?is_remember_me=on
?is_remember_me=yes
?is_remember_me=1
```
+ **日期 date**
日期可以按自己约定的格式传递，默认是作为字符串，此时不支持范围检测。例如配置注册时间：
```php
array('name' => 'register_date', 'type' => 'date')
```
对应地，```register_date=2015-01-31 10:00:00```则会被获取到为："2015-01-31 10:00:00"。
当需要将字符串的日期转换成时间戳时，可追加配置选项```'format' => 'timestamp'```，则配置成：
```php
array('name' => 'register_date', 'type' => 'date', 'format' => 'timestamp')
```
则上面的参数再请求时，则会被转换成：1422669600。
此时作为时间戳，还可以添加范围检测，如限制时间范围在31号当天：
```php
array('name' => 'register_date', 'type' => 'date', 'format' => 'timestamp', 'min' => 1422633600, 'max' => 1422719999)
```
当配置的最小值或最大值为字符串的日期时，会自动先转换成时间戳再进行检测比较。如可以配置成：
```php
array('name' => 'register_date', ... ... 'min' => '2015-01-31 00:00:00', 'max' => '2015-01-31 23:59:59')
```
+ **数组 array**
很多时候在接口进行批量获取时，都需要提供一组参数，如多个ID，多个选项。这时可以使用数组来进行配置。如：
```php
array('name' => 'uids', 'type' => 'array', 'format' => 'explode', 'separator' => ',')
```
这时接口参数```&uids=1,2,3```则会被转换成：
```php
array ( 0 => '1', 1 => '2', 2 => '3', )
```
如果设置了默认值，那么默认值会从字符串，根据相应的format格式进行自动转换。如：
```php
array( ... ... 'default' => '4,5,6')
```
那么在未传参数的情况下，自动会得到：
```php
array ( 0 => '4', 1 => '5', 2 => '6', )
```
又如接口需要使用JSON来传递整块参数时，可以这样配置：
```php
array('name' => 'params', 'type' => 'array', 'format' => 'json')
```
对应地，接口参数```¶ms={"username":"test","password":"123456"}```则会被转换成：
```php
array ( 'username' => 'test', 'password' => '123456', )
```
> **温馨提示：**使用JSON传递参数时，建议使用POST方式传递。若使用GET方式，须注意参数长度不应超过浏览器最大限制长度，以及URL编码问。
若使用JSON格式时，设置了默认值为：
```php
array( ... ... 'default' => '{"username":"dogstar","password":"xxxxxx"}')
```
那么在未传参数的情况下，会得到转换后的：
```php
array ( 'username' => 'dogstar', 'password' => 'xxxxxx', )
```
特别地，当配置成了数组却未指定格式format时，接口参数会转换成只有一个元素的数组，如接口参数：```&name=test```，会转换成：
```php
array ( 0 => 'test' )
```
+ **枚举 enum**
在需要对接口参数进行范围限制时，可以使用此枚举型。如对于性别的参数，可以这样配置：
```php
array('name' => 'sex', 'type' => 'enum', 'range' => array('female', 'male'))
```
当传递的参数不合法时，如```&sex=unknow```，则会被拦截，返回失败：
```
"msg": "非法请求：参数sex应该为：female/male，但现在sex = unknow"
```
关于枚举类型的配置，这里需要特别注意配置时，应尽量使用字符串的值。 因为通常而言，接口通过GET/POST方式获取到的参数都是字符串的，而如果配置规则时指定范围用了整型，会导致底层规则验证时误判。例如接口参数为```&type=N```，而接口参数规则为：
```php
array('name' => 'type', 'type' => 'enum', 'range' => array(0, 1, 2))
```
则会出现以下这样的误判：
```php
var_dump(in_array('N', array(0, 1, 2))); // 结果为true，因为 'N' == 0
```
为了避免这类情况发生，应该使用使用字符串配置范围值，即可这样配置：
```php
array('name' => 'type', 'type' => 'enum', 'range' => array(`0`, `1`, `2`))
```
+ **文件 file**
在需要对上传的文件进行过滤、接收和处理时，可以使用文件类型，如：
```php
array(
'name' => 'upfile',
'type' => 'file',
'min' => 0,
'max' => 1024 * 1024,
'range' => array('image/jpeg', 'image/png') ,
'ext' => array('jpeg', 'png')
)
```
其中，min和max分别对应文件大小的范围，单位为字节；range为允许的文件类型，使用数组配置，且不区分大小写。
如果成功，返回的值对应的是```$_FILES["upfile"]```，即会返回：
```php
array(
'name' => ..., // 被上传文件的名称
'type' => ..., // 被上传文件的类型
'size' => ..., // 被上传文件的大小，以字节计
'tmp_name' => ..., // 存储在服务器的文件的临时副本的名称
)
```
对应的是：
+ $_FILES["upfile"]["name"] - 被上传文件的名称
+ $_FILES["upfile"]["type"] - 被上传文件的类型
+ $_FILES["upfile"]["size"] - 被上传文件的大小，以字节计
+ $_FILES["upfile"]["tmp_name"] - 存储在服务器的文件的临时副本的名称
+ $_FILES["upfile"]["error"] - 由文件上传导致的错误代码
> 参考：以上内容来自W3School，文件上传时请使用表单上传，并enctype 属性使用"multipart/form-data"。更多请参考[PHP 文件上传](http://www.w3school.com.cn/php/php_file_upload.asp)。
若需要配置默认值default选项，则也应为一数组，且其格式应类似如上。
其中，ext是对文件后缀名进行验证，当如果上传文件后缀名不匹配时将抛出异常。文件扩展名的过滤可以类似这样进行配置：
+ 单个后缀名 - 数组形式
```php
'ext' => array('jpg')
```
+ 单个后缀名 - 字符串形式
```php
'ext' => 'jpg'
```
+ 多个后缀名 - 数组形式
```php
'ext' => array('jpg', 'jpeg', 'png', 'bmp')
```
+ 多个后缀名 - 字符串形式（以英文逗号分割）
```php
'ext' => 'jpg,jpeg,png,bmp'
```
+ **回调 callable/callback**
当需要利用已有函数进行自定义验证时，可采用回调参数规则，如配置规则：
```php
array('name' => 'version', 'type' => 'callable', 'callback' => 'App\\Common\\Request\\Version::formatVersion')
```
然后，回调时将调用下面这个新增的类函数：
```php
<?php
namespace App\Common\Request;
use PhalApi\Exception\BadRequestException;
class Version {
public static function formatVersion($value, $rule) {
if (count(explode('.', $value)) < 3) {
throw new BadRequestException('版本号格式错误');
}
return $value;
}
}
```
回调函数的签名为：```function format($value, $rule, $params)```，第一个为参数原始值，第二个为所配置的规则，第三个可选参数为配置规则中的params选项。最后应返回转换后的参数值。
## 接口返回
回顾一下，在PhalApi中，掊口返回的结果的结构为：
```html
{
"ret": 200, // 状态码
"data": {
// 业务数据
},
"msg": "" // 错误提示信息
}
```
### 正常情况下的返回
正常情况下，在Api层返回的数据结果，会在返回结果的data字段中体现。例如：
```php
class Hello extends Api {
public function world() {
return array('title' => 'Hello World!');
}
}
```
对应：
```
{
"ret": 200,
"data": {
"title": "Hello World!"
},
"msg": ""
}
```
成功返回时，状态码ret为200，并且错误信息msg为空。
### 失败情况下的返回
对于异常情况，包括系统错误或者应用层的错误，可以通过抛出[PhalApi\Exception](https://github.com/phalapi/kernal/blob/master/src/Exception.php)系列的异常，中断请求并返回相关的错误信息。例如：
```php
class Hello extends Api {
public function fail() {
throw new BadRequestException('签名失败', 1);
}
}
```
会得到以下结果输出：
```
{
"ret": 401,
"data": [],
"msg": "Bad Request: 签名失败"
}
```
## 注释与在线文档
PhalApi提供了自动生成的在线接口文档，对于每一个接口服务，都有对应的在线接口详情文档。如默认接口服务```Site.Index```的在线接口详情文档为：
此在线接口详情文档，从上到下，依次说明如下。
### 接口服务名称
接口服务名称是指用于请求时的名称，对应s参数（或service参数）。接口服务的中文名称，为不带任何注解的注释，通常为接口类成员函数的第一行注释。
```php
class Site extends Api {
/**
* 默认接口服务
*/
public function index() {
}
}
```
### 接口说明
接口说明对应接口类成员函数的```@desc```注释。
```php
class Site extends Api {
/**
* 默认接口服务
* @desc 默认接口服务，当未指定接口服务时执行此接口服务
*/
public function index() {
}
}
```
### 接口参数
接口参数是根据接口类配置的参数规则自动生成，即对应当前接口类```getRules()```方法中的返回。其中最后的“说明” 字段对应参数规则中的desc选项。可以配置多个参数规则。此外，配置文件./config/app.php中的公共参数规则也会显示在此接口参数里。
```php
class Site extends Api {
public function getRules() {
return array(
'index' => array(
'username' => array('name' => 'username', 'default' => 'PHPer', ),
),
);
}
}
```
### 返回结果
返回结果对应接口类成员函数的```@return```注释，可以有多组，格式为：```@return 返回类型 返回字段 说明```。
```php
class Site extends Api {
/**
* 默认接口服务
* @desc 默认接口服务，当未指定接口服务时执行此接口服务
* @return string title 标题
* @return string content 内容
* @return string version 版本，格式：X.X.X
* @return int time 当前时间戳
*/
public function index() {
}
}
```
### 异常情况
异常情况对应```@exception```注释，可以有多组，格式为：```@exception 错误码 错误描述信息```。例如：
```php
/**
* @exception 406 签名失败
*/
public function index() {
```
刷新后，可以看到新增的异常情况说明。
### 公共注释
对于当前类的全部函数成员的公共```@exception```异常情况注释和```@return```返回结果注释，可在类注释中统一放置。而对于多个类公共的@exception```和```@return```注释，则可以在父类的类注释中统一放置。
也就是说，通过把```@exception```注解和```@return```注解移到类注释，可以添加全部函数成员都适用的注解。例如，Api\User类的全部接口都返回code字段，且都返回400和500异常，则可以：
```php
<?php
namespace App\Api;
use PhalApi\Api;
/**
* @return int code 操作码，0表示成功
* @exception 400 参数传递错误
* @exception 500 服务器内部错误
*/
class User extends Api {
```
这样就不需要在每个函数成员的注释中重复添加注解。此外，也可以在父类的注释中进行添加。对于相同异常码的```@exception```注解，子类的注释会覆盖父类的注释，方法的注释会覆盖类的注释；而对于相同的返回结果```@return```注释，也一样。
需要注意的是，注释必须是紧挨在类的前面，而不能是在namespace前面，否则会导致注释解析失败。
