# 接口響應與在線調試
對于接口響應，PhalApi默認使用了HTTP＋JSON。通過HTTP/HTTPS協議進行通訊，返回的結果則使用JSON格式進行傳遞。正常情況下，當接口服務正常響應時，如前面的Hello World接口，可能看到以下這樣的響應頭部信息和返回內容。
```html
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
... ...
{"ret":200,"data":{"title":"Hello World!"},"msg":""}
```
而當接口項目拋出了未捕捉的異常，或者因PHP語法問題而出現Error時，則沒有內容返回，并且得到一個500的響應狀態碼。類似如下：
```
HTTP/1.1 500 Internal Server Error
```
## 響應結構
回顧一下默認接口服務返回的內容。類似如下：
```html
{
"ret": 200,
"data": {
"title": "Hello World!",
"content": "PHPer您好，歡迎使用PhalApi！",
"version": "2.0.0",
"time": 1499477583
},
"msg": ""
}
```
ret字段是返回狀態碼，200表示成功；data字段是項目提供的業務數據，由接口開發人員定義；msg是異常情況下的錯誤提示信息。下面分別說之。
### 業務數據 data
業務數據data為接口和客戶端主要溝通對接的數據部分，可以為任何類型，由接口開發人員定義定義。但為了更好地擴展、向后兼容，建議都使用可擴展的集合形式，而非原生類型。也就是說，應該返回一個數組，而不應返回整型、布爾值、字符串這些基本類型。
業務數據主要是在Api層返回，即對應接口類的方法的返回結果。如下面的默認接口服務```?s=Site.Index```的實現代碼。
```php
<?php
namespace App\Api;
use PhalApi\Api;
class Site extends Api {
public function index() {
return array(
'title' => 'Hello World!',
'content' => \PhalApi\T('Hi {name}, welcome to use PhalApi!', array('name' => $this->username)),
'version' => PHALAPI_VERSION,
'time' => $_SERVER['REQUEST_TIME'],
);
}
```
實際上，具體的業務數據需要一段復雜的處理，以滿足特定業務場景下的需要。Api層需要與Domain層和Model層共同協作，完成指定的功能。這里暫且知道接口結果是在Api層返回，對應接口類成員方法返回的結果即可。
### 返回狀態碼 ret
返回狀態碼ret，用于表示接口響應的情況。參照自HTTP的狀態碼，ret主要分為四大類：正常響應、重定向、非法請求、服務器錯誤。
分類|ret范圍|基數|說明
---|---|---|---
正常響應|200～299|200|表示接口服務正常響應
重定向|300～399|300|表示重定向，對應異常類[RedirectException](https://github.com/phalapi/kernal/blob/master/src/Exception/RedirectException.php)的異常碼
非法請求|400～499|400|表示客戶端請求非法，對應異常類[BadRequestException](https://github.com/phalapi/kernal/blob/master/src/Exception/BadRequestException.php)的異常碼
服務器錯誤|500～599|500|表示服務器內容錯誤，對應異常類[InternalServerErrorException](https://github.com/phalapi/kernal/blob/master/src/Exception/InternalServerErrorException.php)的異常碼
正常響應時，通常返回ret = 200，并且同時返回data部分的業務數據，以便客戶端能實現所需要的業務功能。
值得注意的是，拋出的異常應該繼承于[PhalApi\Exception](https://github.com/phalapi/kernal/blob/master/src/Exception.php)類，并且構造函數的第一個參數，是返回給客戶端的錯誤提示信息，對應下面將講到的msg字段。第二個參數是返回狀態碼的**疊加值**，也就是說最終的ret狀態碼都會在400的基數上加上這個疊加值，即：401 = 400 + 1。
例如，常見地，當簽名失敗時可以返回一個401錯誤，并提示“簽名失敗”。
```php
<?php
namespace App\Api;
use PhalApi\Api;
use PhalApi\Exception\BadRequestException;
class Hello extends Api {
public function fail() {
throw new BadRequestException('簽名失敗', 1);
}
}
```
會得到以下結果輸出：
```
{
"ret": 401,
"data": [],
"msg": "Bad Request: 簽名失敗"
}
```
### 錯誤提示信息 msg
當接口不是正常響應，即ret不在2XX系列內時，msg字段會返回相應的錯誤提示信息。即當有異常觸發時，會自動將異常的錯誤信息作為錯誤信息msg返回。
## 擴展：如何使用其他返回格式？
除了使用JSON格式返回外，還可以使用其他格式返回結果。
例如在部分H5混合應用頁面進行異步請求的情況下，客戶端需要服務端返回JSONP格式的結果，則可以這樣在DI配置文件./config/di.php中去掉以下注釋。
```php
// 支持JsonP的返回
if (!empty($_GET['callback'])) {
$di->response = new \PhalApi\Response\JsonpResponse($_GET['callback']);
}
```
目前，PhalApi 2.x 已經支持的響應格式有：
響應格式|實現類
---|---
JSON格式|[PhalApi\Response\JsonResponse](https://github.com/phalapi/kernal/blob/master/src/Response/JsonResponse.php)
JSONP格式|[PhalApi\Response\JsonResponse](https://github.com/phalapi/kernal/blob/master/src/Response/JsonResponse.php)
XML格式|[PhalApi\Response\JsonResponse](https://github.com/phalapi/kernal/blob/master/src/Response/JsonResponse.php)
控制臺格式|[PhalApi\Response\JsonResponse](https://github.com/phalapi/kernal/blob/master/src/Response/JsonResponse.php)
當需要返回一種當前PhalApi沒提供的格式，需要返回其他格式時，可以：
+ 1、實現抽象方法[PhalApi\Response::formatResult($result)](https://github.com/phalapi/kernal/blob/master/src/Response.php)并返回格式化后結果
+ 2、在./config/di.php文件中重新注冊```\PhalApi\DI()->response```服務
## 在線調試
### 開啟調試調試
開啟調試模式很簡單，主要有兩種方式：
+ **單次請求開啟調試**：默認添加請求參數```&__debug__=1```
+ **全部請求開啟調試**：把配置文件```./Config/sys.php```文件中的配置改成```'debug' => true,```
### 調試信息有哪些？
正常響應的情況下，當開啟調試模式后，會返回多一個```debug```字段，里面有相關的調試信息。如下所示：
```
{
"ret": 200,
"data": {
},
"msg": "",
"debug": {
"stack": [ // 自定義埋點信息
],
"sqls": [ // 全部執行的SQL語句
]
}
}
```
> 溫馨提示：調試信息僅當在開啟調試模式后，才會返回并顯示。
在發生未能捕捉的異常時，并且開啟調試模式后，會將發生的異常轉換為對應的結果按結果格式返回，即其結構會變成以下這樣：
```
{
"ret": 0, // 異常時的錯誤碼
"data": [],
"msg": "", // 異常時的錯誤信息
"debug": {
"exception": [ // 異常時的詳細堆棧信息
],
"stack": [ // 自定義埋點信息
],
"sqls": [ // 全部執行的SQL語句
]
}
}
```
+ **查看全部執行的SQL語句**
debug.sqls中會顯示所執行的全部SQL語句，由框架自動搜集并統計。最后顯示的信息格式是：
```
[序號 - 當前SQL的執行時間ms]所執行的SQL語句及參數列表
```
示例：
```
[1 - 0.32ms]SELECT * FROM tbl_user WHERE (id = ?); -- 1
```
表示是第一條執行的SQL語句，消耗了0.32毫秒，SQL語句是```SELECT * FROM tbl_user WHERE (id = ?);```，其中參數是1。
+ **查看自定義埋點信息**
debug.stack中埋點信息的格式如下：
```
[#序號 - 距離最初節點的執行時間ms - 節點標識]代碼文件路徑(文件行號)
```
示例：
```
[#0 - 0ms]/path/to/phalapi/public/index.php(6)
```
表示，這是第一個埋點（由框架自行添加），執行時間為0毫秒，所在位置是文件```/path/to/phalapi/public/index.php```的第6行。即第一條的埋點發生在框架初始化時。
與SQL語句的調試信息不同的是，自定義埋點則需要開發人員根據需要自行紀錄，可以使用全球追蹤器```PhalApi\DI()->tracer```進行紀錄，其使用如下：
```php
// 添加紀錄埋點
PhalApi\DI()->tracer->mark();
// 添加紀錄埋點，并指定節點標識
PhalApi\DI()->tracer->mark('DO_SOMETHING');
```
通過上面方法，可以對執行經過的路徑作標記。你可以指定節點標識，也可以不指定。對一些復雜的接口，可以在業務代碼中添加這樣的埋點，追蹤接口的響應時間，以便進一步優化性能。當然，更專業的性能分析工具推薦使用XHprof。
> 參考：用于性能分析的[XHprof擴展類庫](http://git.oschina.net/dogstar/PhalApi-Library/tree/master/Xhprof)。
+ **查看異常堆棧信息**
當有未能捕捉的接口異常時，開啟調試模式后，框架會把對應的異常轉換成對應的返回結果，并在debug.exception中體現。而不是像正常情況直接500，頁面空白。這些都是由框架自動處理的。
例如，讓我們故意制造一些麻煩，手動拋出一個異常。
```php
class Hello extends Api {
public function fail() {
throw new Exception('這是一個演示異常調試的示例', 501);
}
}
```
再次請求后，除了SQL語句和自定義埋點信息外，還會看到這樣的異常堆棧信息。然后便可根據返回的異常信息進行排查定位問題。
+ **添加自定義調試信息**
當需要添加其他調試信息時，可以使用```PhalApi\DI()->response->setDebug()```進行添加。
如：
```php
class Hello extends Api {
public function fail() {
$x = 'this is x';
$y = array('this is y');
\PhalApi\DI()->response->setDebug('x', $x);
\PhalApi\DI()->response->setDebug('y', $y);
}
}
```
請求后，可以看到：
```
"debug": {
"x": "this is x",
"y": [
"this is y"
]
}
```
