萬盛學電腦網

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

PHP 生成 API 接口統一響應格式:JSON 與 XML 雙模式輸出類實現

前後端分離、微服務、開放平台場景下,統一的 API 響應結構至關重要。本文提供一個 Response 靜態類,支援按需輸出 JSON 或 XML,結構包含 code(業務狀態碼)、message(提示信息)、data(業務載荷),並處理 XML 特殊字符轉義與數組遞歸編碼。

類結構與核心方法

class Response {
    // 統一入口
    public static function show($code, $message, $data = [], $type = '') {
        if (!is_numeric($code)) return '';
        if ($type === 'json') return self::json($code, $message, $data);
        if ($type === 'xml')  return self::xml($code, $message, $data);
        // TODO: 支援其他格式(如 protobuf, msgpack)
        return self::json($code, $message, $data); // 默認 JSON
    }

    // JSON 輸出
    public static function json($code, $message, $data = []) {
        if (!is_numeric($code)) return '';
        return json_encode([
            'code'    => (int)$code,
            'message' => (string)$message,
            'data'    => $data
        ], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    }

    // XML 輸出
    public static function xml($code, $message, $data = []) {
        if (!is_numeric($code)) return '';
        header("Content-Type: text/xml; charset=UTF-8");
        $xml = "\n\n";
        $xml .= self::xmlEncode($data);
        $xml .= "";
        return $xml;
    }

    // 數組遞歸轉 XML
    private static function xmlEncode($data) {
        $xml = '';
        foreach ($data as $key => $value) {
            $attr = is_numeric($key) ? "id='$key'" : '';
            $tag = is_numeric($key) ? 'item' : $key;
            $xml .= "<$tag $attr>\n";
            $xml .= is_array($value) ? self::xmlEncode($value) : htmlspecialchars($value, ENT_QUOTES, 'UTF-8') . "\n";
            $xml .= "\n";
        }
        return $xml;
    }
}

使用範例

$grade = [
    'score' => [70, 95, 70.0, 60, '70'],
    'name'  => ['張三', '李四', '王五', '趙六', '天氣']
];

echo Response::show(200, 'success', $grade, 'json');
// {"code":200,"message":"success","data":{"score":[70,95,70,60,"70"],"name":["張三","李四","王五","趙六","天氣"]}}

echo Response::show(200, 'success', $grade, 'xml');
/*


70
95
...
張三
...

*/

生產級增強建議

  1. 狀態碼規範:遵循 HTTP 語義(200/201/400/401/403/404/422/500)並定義業務碼枚舉類。
  2. 異常處理:捕獲 JsonException、DOMException,返回統一錯誤結構並記錄日誌。
  3. XML 安全:防止 XXE 攻擊(不解析外部實體),輸出時 htmlspecialchars 轉義實體字符。
  4. 內容協商:根據 Accept 頭自動選擇格式,而非查詢參數控制。
  5. 序列化器模式:引入 symfony/serializer、jms/serializer 支援分組、版本化、循環引用處理。
  6. OpenAPI/Swagger 整合:從註解生成文檔,保證接口契約與實現一致。

XML 與 JSON 選型指引

維度JSONXML
體積/解析速度✓ 輕量、快較重、較慢
類型系統基本類型+數組/對象無原生類型,需 Schema
屬性/命名空間無✓ 豐富元數據
流式處理需流式解析器✓ SAX/StAX 原生流式
生態工具極其豐富企業級/舊系統主導

現代 REST API 首選 JSON;SOAP、金融/電信標準接口、需複雜元數據場景選 XML。

copyright © 萬盛學電腦網 all rights reserved