萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 統一數據返回格式化類:多格式輸出、JSONP、XML、回調函數支持

一、設計動機

API 接口需要統一的響應格式,支持多種輸出格式(JSON、XML、JSONP、原生數組),便於前端對接、文檔生成、自動化測試。

二、DataReturn 類完整實現

<?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 .= '';
        }
        $xml .= "</$root>";
        return $xml;
    }

    /** 檢查數組鍵是否存在且非空 */
    private function exists($arr, $key) {
        return isset($arr[$key]) && $arr[$key] !== '';
    }
}
?>

三、使用示例

1. 標準 JSON API

<?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":"張三"}}
?>

2. JSONP 跨域調用

<?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 模式: 
?>

3. XML 輸出(對接老系統)

<?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();
/* 輸出:

  
  
  
    
  

*/
?>

4. 內部調用獲取數組

<?php
$ret = new DataReturn([
    'type' => 'ARRAY',
    'retcode' => 0,
    'data' => ['total' => 100]
]);
// 內部調用不直接輸出,可擴展 getArray() 方法返回
$arr = $ret->getArray(); // 需類中添加 public getArray() { return $this->returnData; }
?>

四、擴展:HTTP 狀態碼映射

<?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();
?>

五、現代框架對比

框架響應類特性
LaravelJsonResponse / Response::json()宏定義、資源類、自動 JSONP
SymfonyJsonResponse序列化器、標準化錯誤格式
ThinkPHPJson / Xml / Jsonp 類驅動模式、配置映射
本類DataReturn零依賴、輕量、字段映射配置化

六、最佳實踐建議

  1. 統一錯誤碼體系:業務碼(10001=參數錯誤)與 HTTP 碼映射
  2. 數據結構規範:data 固定為對象/數組,不返回純量
  3. 移除 BOM:確保文件 UTF-8 無 BOM,避免 JSON 解析失敗
  4. 異常統一捕獲:框架異常處理器中統一實例化 DataReturn 輸出
  5. API 版本管理:通過 Header 或 URL 版本控制響應格式演進

DataReturn 類以 100 行代碼解決了 API 響應格式標準化的核心痛點,是輕量級項目、微服務、老系統改造的理想選擇。

copyright © 萬盛學電腦網 all rights reserved