自 PHP 5.2 起內建 json_encode() / json_decode(),但許多開發者僅停留在基本用法。本文深入解析編碼選項、資料類型映射、大數字精度、Unicode 處理、錯誤處理、效能調優,並提供生產級封裝類別。
編碼選項位元組合速查表
| 常數 | 值 | 效果 | 推薦場景 |
JSON_HEX_TAG | 1 | < > 轉為 \u003C \u003E | 防 XSS,嵌入 HTML/JS 時必加 |
JSON_HEX_AMP | 2 | & 轉為 \u0026 | 嵌入 HTML 屬性值時 |
JSON_HEX_APOS | 4 | ' 轉為 \u0027 | 嵌入 JS 單引號字串 |
JSON_HEX_QUOT | 8 | " 轉為 \u0022 | 嵌入 JS 雙引號字串 |
JSON_FORCE_OBJECT | 16 | 索引陣列輸出為物件 {} | API 要求物件格式 |
JSON_NUMERIC_CHECK | 32 | 數值字串轉為數字型別 | ⚠️ 危險:可能導致大數字精度損失、電話號碼變科學記號 |
JSON_BIGINT_AS_STRING | 256 | 大整數 (超出 IEEE 754) 輸出為字串 | ✅ 必加:處理 64 位 ID、金額分 |
JSON_PRETTY_PRINT | 64 | 美化縮排輸出 | 除錯、日誌、配置檔 |
JSON_UNESCAPED_SLASHES | 128 | 不轉義 / (預設轉義 \/) | URL、路徑輸出更易讀 |
JSON_UNESCAPED_UNICODE | 256 | 不轉義中文等 Unicode 字元 | ✅ 強烈推薦:可讀性、體積較小 |
JSON_PRESERVE_ZERO_FRACTION | 512 | 浮點數保留 .0 (1.0 → 1.0 不變 1) | API 契約要求浮點格式 |
JSON_UNESCAPED_LINE_TERMINATORS | 1024 | 不轉義 U+2028/U+2029 (JS 行終止符) | 嵌入 JS 模板字串 |
JSON_THROW_ON_ERROR | 256 | 錯誤拋出 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) |
| null | null | null | null |
| true/false | true/false | true/false | true/false |
| int (64位內) | number | int | int |
| int (超出 64位) | number | float (精度損失!) | float |
| float | number | float | float |
| string | string | string | string |
| 索引陣列 (連續 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" |
效能優化實戰
- 重用編碼器實例:PHP 8.1+
JsonEncoder 類 (實驗性) 或自行快取 json_encode 結果
- 避免重複編碼:API 回應直接輸出已編碼 JSON 字串 (從 Redis/資料庫讀取預存 JSON)
- 大陣列分塊編碼:
json_encode 記憶體峰值約為輸出字串 2-3 倍,超大資料用生成器分批 + 串流輸出
- igbinary 序列化:內部快取/Session 儲存用
igbinary_serialize() 比 json_encode() 快 2-3 倍、體積小 30%
- 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 處理既安全又高效。