### 概述
> api應用（TP5.1的時候叫模塊）主要是為前后端分離項目準備的，可以使用已有的功能進行api接口的快速開發
接口執行流程為：
1. 前端訪問`/api/xx/xx`請求接口
2. `ApiBaseController`基類進行初始化（判斷登錄/鑒權/防止重復提交/token被盜檢測等）工作
3. 執行具體`Controller`中的業務邏輯
4. 返回執行的結果
### 接口開發
- 在`/app/api/controller`文件夾下創建相應的控制器，繼承`ApiBaseController`類。
- 配置`$loginExcept`變量，把無需登錄驗證的`url`加入到里面。
- 在具體方法中直接返回`api_success`或`api_error`即可。
### 配置文件
接口配置參數在/app/api/config/api.php文件中，內容如下：
```php
return [
// api跨域設置
'cross_domain' => [
// 是否允許跨域
'allow' => env('api.allow_cross_domain', true),
// header設置
'header' => [
'Access-Control-Allow-Origin' => '*',
'Access-Control-Allow-Methods' => '*',
// 這個地方可以加入更多自定義的header
'Access-Control-Allow-Headers' => 'Content-Type,' . (env('api.token_position') === 'header' ? env('api.token_field') : 'token'),
// 這個地方也可以加入更多的自定義header
'Access-Control-Request-Headers' => 'Origin, Content-Type, Accept, ' . (env('api.token_position') === 'header' ? env('api.token_field') : 'token'),
],
],
// api響應配置
'response' => [
// HTTP狀態碼和業務狀態碼同步
'http_code_sync' => env('api.http_code_sync', false),
],
'auth' => [
'jwt_key' => env('api.jwt_key', 'f2244f5316b70ef2887514b65caf795f'),
'jwt_exp' => (int)env('api.jwt_exp', 3600),
'jwt_aud' => env('api.jwt_aud', 'a'),
'jwt_iss' => env('api.jwt_iss', 's'),
'enable_refresh_token' => (bool)env('api.enable_refresh_token', true),
'refresh_token_exp' => (int)env('api.refresh_token_exp', 1296000),
'reuse_check' => (bool)env('api.reuse_check', true),
'token_position' => env('api.token_position', 'header'),
'token_field' => env('api.token_field', 'token'),
]
];
```
### 登錄校驗
安全校驗采用`jwt`進行校驗，`jwt`采用extend中自行封裝的jwt擴展包，在`/app/api/traits/ApiAuthTrait.php`中封裝了相關方法。
#### 登錄驗證流程
#### jwt配置
> 當自動刷新token的時候，前端保存后端傳過來的新token，此后都用新的token進行訪問。如果不想使用oken刷新可以把過期時間設置的大一些，例如1年之類的。
~~~
protected $config = [
//token在header中的name
'name' => 'token',
//加密使用的secret
'secret' => '552ac90778a976c72f7f673db174df30',
//頒發者
'iss' => 'iss',
//使用者
'aud' => 'aud',
//過期時間，以秒為單位，默認2小時
'ttl' => 30,
//刷新時間，以秒為單位，默認14天，以
'refresh_ttl' => 1209600,
//是否自動刷新，開啟后可自動刷新token，附在header中返回，name為`Authorization`,字段為`Bearer `+$token
'auto_refresh' => true,
//黑名單寬限期，以秒為單位，首次token刷新之后在此時間內原token可以繼續訪問
'blacklist_grace_period' => 60
];
~~~
### 返回數據
返回數據為json格式，正常情況下會包括`code`,`msg`,`data`字段，分別代表狀態碼，消息，主數據。
```json
{
"code": 200,
"msg": "success",
"data": {}
}
```
### 返回狀態碼
> 因 HTTP 狀態碼多的嚇人，所以目前默認采用`200`HTTP態碼來控制接口的返回，前端需要判斷業務狀態可以直接獲取返回`body`內的`code`進行判斷，如果需要HTTP狀態碼與業務狀態碼統一可自行在`.env`中配置。
目前定義的業務狀態碼有以下幾種：
* 200 代表成功。所有的接口成功返回都是200
* 400 表示客戶端錯誤。例如輸入的字段類型不匹配等
* 401 未登錄/登錄狀態失效。代表需要客戶端發起登錄流程
* 403 表示此用戶無權限。例如普通用戶無法觀看vip課程，可直接返回403
* 404 接口不存在。訪問了不存在的接口就會返回404
* 500 代表失敗。具體原因可參考body內msg字段
其中，我們用的最多的就是`200`和`500`了，401在登錄鑒權的地方可以自動返回，一般無需自己處理，`404`系統也自定義好了，無需手動處理，`500`在`/application/common/exception/Http.php`文件中也做了捕獲處理。`400`和`403`可酌情使用，不想麻煩的也可以直接用500來代替。
### 開發示例
#### 登錄
登錄功能可以直接參考`/application/api/controller/AuthController.php`中的`login`方法。
#### 資源控制器
可以直接參考`/application/api/controller/UserController.php`控制器。
