API接口层
Api接口层称为接口服务层,负责对客户端的请求进行响应,处理接收客户端传递的参数,调度Domain层进行业务逻辑处理,最后将处理结果返回给客户端。
创建API
当需要新增一个接口时,先要在Api层添加一个新的接口文件。将其存放在./src/app/Api/目录中,文件首字母大写,如Hello.php文件,并写入必要代码,如:
namespace App\Api;
use PhalApi\Api;
class Hello extends Api{
}
编写接口时,需要特别注意:
默认所在命名空间必须为App\Api。
具体实现的接口类必须是PhalApi\Api的子类。
调用API
通常情况下,接口访问的URL格式为:接口域名/public/?s=Namespace.Class.Action。其中s参数为service参数的缩写,也就是说,上述的url还可以为接口域名/public/?service=Namespace.Class.Action。
访问api的url由三部分组成,分别是:
Namespace 为可选参数,默认值为App,是Api命名空间前缀,多级命名空间时用下划线分割;
Class 必须指定接口类名,首字母大写;
Action 为待请求的接口类方法名,通常首字母大写。
若Class和Action均未指定时,默认为Site.Index。
以下的url都是合适的:
http://dev.phalapi.net/?s=Hello.World
http://dev.phalapi.net/?service=Hello.World
http://localhost/phpapi/public/?s=App.Hello.World
http://localhost/phpapi/public/?service=App.Hello.World
http://localhost/phpapi/public/
Api响应
对于接口响应,PhalApi默认使用了HTTP+JSON。通过HTTP/HTTPS协议进行通讯,返回的结果则使用JSON格式进行传递。
数据结构
返回结果分为三部分:
ret字段是返回状态码,200表示成功;
data字段是项目提供的业务数据,由接口开发人员定义;
msg是异常情况下的错误提示信息。
例如:
{
"ret": 200,
"data": {
"title": "Hello World!",
"content": "PHPer您好,欢迎使用PhalApi!",
"version": "2.0.0",
"time": 1499477583
},
"msg": ""
}
状态码
返回状态码ret,用于表示接口响应的情况。参照自HTTP的状态码,ret主要分为四大类:正常响应、重定向、非法请求、服务器错误。
正常响应,取值范围在200~299之间,表示接口服务正常响应;
重定向,取值范围在300~399,表示重定向,对应异常类RedirectException的异常码
非法请求,取值范围在400~499,表示客户端请求非法,对应异常类BadRequestException的异常码
服务器错误,取值范围在500~599,表示服务器内容错误,对应异常类InternalServerErrorException的异常码