API 接口需要統一的響應格式,支持多種輸出格式(JSON、XML、JSONP、原生數組),便於前端對接、文檔生成、自動化測試。
<?php
/**
* DataReturn - 統一數據返回格式化
* 支持:JSON, XML, CALLBACK(JSONP), ARRAY
* 字段映射配置化,適配不同業務規範
*/
class DataReturn {
private $type; // 輸出類型
private $xmlRoot; // XML 根節點名
private $callback; // JSONP 回調函數名
private $returnData; // 組裝後的數據結構
public function __construct(array $param = []) {
// 輸出類型:JSON, XML, CALLBACK, ARRAY
$this->type = strtoupper($param['type'] ?? 'JSON');
// XML 根節點
$this->xmlRoot = $param['xmlroot'] ?? 'xmlroot';
// JSONP 回調
$this->callback = $param['callback'] ?? '';
// 字段名映射配置
$format = [
'retcode' => $param['format']['retcode'] ?? 'retcode',
'msg' => $param['format']['msg'] ?? 'msg',
'data' => $param['format']['data'] ?? 'data',
];
// 組裝標準響應結構
$this->returnData = [
$format['retcode'] => $param['retcode'] ?? 0,
$format['msg'] => $param['msg'] ?? '',
$format['data'] => $param['data'] ?? '',
];
}
/** 輸出並終止腳本 */
public function data_return() {
ob_clean(); // 清除之前輸出
switch ($this->type) {
case 'JSON':
$this->json_return();
break;
case 'XML':
$this->xml_return();
break;
case 'CALLBACK':
$this->callback_return();
break;
case 'ARRAY':
$this->array_return();
break;
default:
$this->json_return();
}
exit();
}
/** JSON / JSONP 輸出 */
private function json_return() {
header('Content-Type: application/json; charset=utf-8');
$json = json_encode($this->returnData, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
if ($this->callback) {
// JSONP: callback({...})
echo $this->callback . '(' . $json . ');';
} else {
echo $json;
}
}
/** XML 輸出 */
private function xml_return() {
header('Content-Type: application/xml; charset=utf-8');
echo $this->xml_encode($this->returnData, $this->xmlRoot);
}
/** JSONP 輸出(Script 標籤注入模式) */
private function callback_return() {
header('Content-Type: text/html; charset=utf-8');
$cb = $this->callback ?: 'callback';
echo "<script type=\"text/javascript\"\n";
echo $cb . '(' . json_encode($this->returnData, JSON_UNESCAPED_UNICODE) . ");\n";
echo "</script>";
}
/** 原生數組返回(內部調用/測試用) */
private function array_return() {
// 不輸出,直接返回數組供調用者處理
// 實際項目中可拋出異常或設置屬性
var_dump($this->returnData);
}
/** 數組轉 XML(遞歸) */
private function xml_encode($data, $root) {
$xml = "<$root>";
foreach ($data as $key => $val) {
$key = is_numeric($key) ? 'item' : $key;
$xml .= '<' . $key . '>';
if (is_array($val) || is_object($val)) {
$xml .= $this->xml_encode($val, $key);
} else {
$xml .= '';
}
$xml .= '' . $key . '>';
}
$xml .= "</$root>";
return $xml;
}
/** 檢查數組鍵是否存在且非空 */
private function exists($arr, $key) {
return isset($arr[$key]) && $arr[$key] !== '';
}
}
?>
<?php
require 'DataReturn.class.php';
// 成功響應
$ret = new DataReturn([
'type' => 'JSON',
'retcode' => 0,
'msg' => 'success',
'data' => ['uid' => 1001, 'name' => '張三']
]);
$ret->data_return();
// 輸出: {"retcode":0,"msg":"success","data":{"uid":1001,"name":"張三"}}
?>
<?php
// 前端: $.getJSON('api.php?callback=?', ...)
$ret = new DataReturn([
'type' => 'CALLBACK',
'callback' => $_GET['callback'] ?? 'callback',
'retcode' => 0,
'data' => ['items' => [1,2,3]]
]);
$ret->data_return();
// 輸出: callback({"retcode":0,"msg":"","data":{"items":[1,2,3]}});
// 或 Script 模式:
?>
<?php
$ret = new DataReturn([
'type' => 'XML',
'xmlroot' => 'response',
'format' => ['retcode' => 'code', 'msg' => 'message', 'data' => 'result'],
'retcode' => 200,
'msg' => 'OK',
'data' => ['token' => 'abc123']
]);
$ret->data_return();
/* 輸出:
*/
?>
<?php
$ret = new DataReturn([
'type' => 'ARRAY',
'retcode' => 0,
'data' => ['total' => 100]
]);
// 內部調用不直接輸出,可擴展 getArray() 方法返回
$arr = $ret->getArray(); // 需類中添加 public getArray() { return $this->returnData; }
?>
<?php
// 擴展:自動設置 HTTP 狀態碼
private function setHttpStatus() {
$codeMap = [
0 => 200, // 成功
400 => 400, // 參數錯誤
401 => 401, // 未授權
403 => 403, // 禁止
404 => 404, // 不存在
500 => 500, // 服務器錯誤
503 => 503, // 服務不可用
];
$retcode = $this->returnData['retcode'] ?? 0;
$httpCode = $codeMap[$retcode] ?? 200;
http_response_code($httpCode);
}
// 在 data_return() 開頭調用
$this->setHttpStatus();
?>
| 框架 | 響應類 | 特性 |
|---|---|---|
| Laravel | JsonResponse / Response::json() | 宏定義、資源類、自動 JSONP |
| Symfony | JsonResponse | 序列化器、標準化錯誤格式 |
| ThinkPHP | Json / Xml / Jsonp 類 | 驅動模式、配置映射 |
| 本類 | DataReturn | 零依賴、輕量、字段映射配置化 |
data 固定為對象/數組,不返回純量DataReturn 類以 100 行代碼解決了 API 響應格式標準化的核心痛點,是輕量級項目、微服務、老系統改造的理想選擇。