萬盛學電腦網

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

PHP JSON 處理完全指南:json_encode/decode 進階用法、陷阱與效能優化

自 PHP 5.2 起內建 json_encode() / json_decode(),但許多開發者僅停留在基本用法。本文深入解析編碼選項、資料類型映射、大數字精度、Unicode 處理、錯誤處理、效能調優,並提供生產級封裝類別。

編碼選項位元組合速查表

常數值效果推薦場景
JSON_HEX_TAG1< > 轉為 \u003C \u003E防 XSS,嵌入 HTML/JS 時必加
JSON_HEX_AMP2& 轉為 \u0026嵌入 HTML 屬性值時
JSON_HEX_APOS4' 轉為 \u0027嵌入 JS 單引號字串
JSON_HEX_QUOT8" 轉為 \u0022嵌入 JS 雙引號字串
JSON_FORCE_OBJECT16索引陣列輸出為物件 {}API 要求物件格式
JSON_NUMERIC_CHECK32數值字串轉為數字型別⚠️ 危險:可能導致大數字精度損失、電話號碼變科學記號
JSON_BIGINT_AS_STRING256大整數 (超出 IEEE 754) 輸出為字串✅ 必加:處理 64 位 ID、金額分
JSON_PRETTY_PRINT64美化縮排輸出除錯、日誌、配置檔
JSON_UNESCAPED_SLASHES128不轉義 / (預設轉義 \/)URL、路徑輸出更易讀
JSON_UNESCAPED_UNICODE256不轉義中文等 Unicode 字元✅ 強烈推薦:可讀性、體積較小
JSON_PRESERVE_ZERO_FRACTION512浮點數保留 .0 (1.0 → 1.0 不變 1)API 契約要求浮點格式
JSON_UNESCAPED_LINE_TERMINATORS1024不轉義 U+2028/U+2029 (JS 行終止符)嵌入 JS 模板字串
JSON_THROW_ON_ERROR256錯誤拋出 JsonException (PHP 7.3+)✅ 必加:避免靜默失敗返回 false

推薦預設選項組合 (生產環境 API)

const JSON_DEFAULT_FLAGS = 
    JSON_UNESCAPED_UNICODE 
  | JSON_UNESCAPED_SLASHES 
  | JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT // 安全嵌入
  | JSON_BIGINT_AS_STRING   // 保護大整數精度
  | JSON_THROW_ON_ERROR;    // 失敗拋出異常

// 使用
$json = json_encode($data, JSON_DEFAULT_FLAGS);

資料類型映射規則 (PHP → JSON → PHP)

PHP 型別JSON 型別解碼後 (預設)解碼後 (assoc=true)
nullnullnullnull
true/falsetrue/falsetrue/falsetrue/false
int (64位內)numberintint
int (超出 64位)numberfloat (精度損失!)float
floatnumberfloatfloat
stringstringstringstring
索引陣列 (連續 0..n)array []stdClass 物件索引陣列
關聯陣列 / 非連續索引object {}stdClass 物件關聯陣列
物件 (public 屬性)object {}stdClass 物件關聯陣列
資源/類別實例 (私有/保護屬性)❌ 錯誤/忽略--

關鍵陷阱:大整數精度損失

$id = '9223372036854775807'; // 2^63-1
$json = json_encode(['id' => $id]); // 未加 JSON_BIGINT_AS_STRING
// 輸出: {"id":9223372036854775807} (JSON 數字)
$decoded = json_decode($json, true);
var_dump($decoded['id']); // float(9.2233720368548E+18) 精度已損失!

// 正確做法
$json = json_encode(['id' => $id], JSON_BIGINT_AS_STRING);
// 輸出: {"id":"9223372036854775807"} (JSON 字串)
$decoded = json_decode($json, true);
var_dump($decoded['id']); // string(19) "9223372036854775807" 完美保留

解碼選項


// 返回關聯陣列而非 stdClass (最常用)
$data = json_decode($json, true); // 第 2 參數 true = associative

// PHP 7.3+ 深度限制 (預設 512,防止堆疊溢位)
$data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);

// 位元組選項 (PHP 7.3+)
$data = json_decode($json, flags: JSON_BIGINT_AS_STRING | JSON_THROW_ON_ERROR);

錯誤處理最佳實踐

<?php
function safeJsonEncode(mixed $data, int $flags = JSON_DEFAULT_FLAGS): string {
    try {
        return json_encode($data, $flags);
    } catch (JsonException $e) {
        // 記錄完整錯誤上下文
        error_log("JSON encode failed: {$e->getMessage()}, data: " . var_export($data, true));
        throw new RuntimeException('資料序列化失敗', 0, $e);
    }
}

function safeJsonDecode(string $json, bool $associative = true, int $depth = 512, int $flags = JSON_BIGINT_AS_STRING): mixed {
    try {
        return json_decode($json, $associative, $depth, $flags);
    } catch (JsonException $e) {
        error_log("JSON decode failed: {$e->getMessage()}, json: " . substr($json, 0, 500));
        throw new RuntimeException('資料反序列化失敗', 0, $e);
    }
}

常見錯誤 JSON 範例與修正

錯誤 JSON錯誤原因修正
{ 'key': 'value' }鍵名/字串必須用雙引號{ "key": "value" }
{ key: "value" }鍵名必須加雙引號{ "key": "value" }
{ "key": "value", }尾隨逗號非標準 JSON{ "key": "value" }
{ "key": undefined }undefined 非 JSON 型別{ "key": null }
{ "key": NaN }NaN/Infinity 非 JSON 數字{ "key": null } 或字串
"\xFF"非法 Unicode 逸出序列"\u00FF"

效能優化實戰

  1. 重用編碼器實例:PHP 8.1+ JsonEncoder 類 (實驗性) 或自行快取 json_encode 結果
  2. 避免重複編碼:API 回應直接輸出已編碼 JSON 字串 (從 Redis/資料庫讀取預存 JSON)
  3. 大陣列分塊編碼:json_encode 記憶體峰值約為輸出字串 2-3 倍,超大資料用生成器分批 + 串流輸出
  4. igbinary 序列化:內部快取/Session 儲存用 igbinary_serialize() 比 json_encode() 快 2-3 倍、體積小 30%
  5. SIMD 加速:PHP 8.2+ json_encode 內建 SIMD 優化,升級 PHP 版本即享受紅利

生產級封裝類別

<?php
declare(strict_types=1);

namespace App\Utils;

use JsonException;
use RuntimeException;

final class Json {
    public const ENCODE_FLAGS = 
        JSON_UNESCAPED_UNICODE 
      | JSON_UNESCAPED_SLASHES 
      | JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT
      | JSON_BIGINT_AS_STRING
      | JSON_THROW_ON_ERROR;

    public const DECODE_FLAGS = JSON_BIGINT_AS_STRING | JSON_THROW_ON_ERROR;

    public static function encode(mixed $data, int $flags = self::ENCODE_FLAGS): string {
        try {
            return json_encode($data, $flags);
        } catch (JsonException $e) {
            throw new RuntimeException('JSON 編碼失敗: ' . $e->getMessage(), 0, $e);
        }
    }

    public static function decode(string $json, bool $associative = true, int $flags = self::DECODE_FLAGS): mixed {
        try {
            return json_decode($json, $associative, 512, $flags);
        } catch (JsonException $e) {
            throw new RuntimeException('JSON 解碼失敗: ' . $e->getMessage(), 0, $e);
        }
    }

    public static function prettyEncode(mixed $data): string {
        return self::encode($data, self::ENCODE_FLAGS | JSON_PRETTY_PRINT);
    }

    public static function validate(string $json): bool {
        json_decode($json, false, 512, JSON_THROW_ON_ERROR);
        return true;
    }
}

結語

JSON 是現代 Web 通用語言,掌握 JSON_BIGINT_AS_STRING、JSON_THROW_ON_ERROR、JSON_UNESCAPED_UNICODE 三大旗標 能解決 99% 的編解碼坑。封裝統一工具類、配合 OpenAPI/Swagger 定義嚴格 Schema、啟用 PHP 8.2+ 享受 SIMD 加速,讓 JSON 處理既安全又高效。

copyright © 萬盛學電腦網 all rights reserved