API接口层

Api接口层称为接口服务层，负责对客户端的请求进行响应，处理接收客户端传递的参数，调度Domain层进行业务逻辑处理，最后将处理结果返回给客户端。

创建API

当需要新增一个接口时，先要在Api层添加一个新的接口文件。将其存放在./src/app/Api/目录中，文件首字母大写，如Hello.php文件，并写入必要代码，如：

<?php
namespace App\Api;

use PhalApi\Api;

class Hello extends Api {

}

编写接口时，需要特别注意：

1. 默认所在命名空间必须为App\Api。
2. 具体实现的接口类必须是PhalApi\Api的子类。

调用API

通常情况下，接口访问的URL格式为：接口域名/public/?s=Namespace.Class.Action。其中s参数为service参数的缩写，也就是说，上述的url还可以为接口域名/public/?service=Namespace.Class.Action。

访问api的url由三部分组成，分别是：

1. Namespace 为可选参数，默认值为App，是Api命名空间前缀，多级命名空间时用下划线分割；
2. Class 必须指定接口类名，首字母大写；
3. 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格式进行传递。

数据结构

返回结果分为三部分：

1. ret字段是返回状态码，200表示成功；
2. data字段是项目提供的业务数据，由接口开发人员定义；
3. msg是异常情况下的错误提示信息。

例如：

{
    "ret": 200,
    "data": {
        "title": "Hello World!",
        "content": "PHPer您好，欢迎使用PhalApi！",
        "version": "2.0.0",
        "time": 1499477583
    },
    "msg": ""
}

状态码

返回状态码ret，用于表示接口响应的情况。参照自HTTP的状态码，ret主要分为四大类：正常响应、重定向、非法请求、服务器错误。

1. 正常响应，取值范围在200～299之间，表示接口服务正常响应；
2. 重定向，取值范围在300～399，表示重定向，对应异常类RedirectException的异常码
3. 非法请求，取值范围在400～499，表示客户端请求非法，对应异常类BadRequestException的异常码
4. 服务器错误，取值范围在500～599，表示服务器内容错误，对应异常类InternalServerErrorException的异常码