Python JSON 實戰指南：Datetime 序列化與大型檔案串流處理

在 Python 後端與資料流程中，JSON 幾乎是預設交換格式。看似簡單的 json.dumps() / json.loads()，在遇到 datetime、多語字元與大型檔案時，常會暴露可維護性與效能問題。

本篇聚焦在可直接套用到實務的做法：

• • loads/dumps 與 load/dump 的使用邊界

• • datetime 無法序列化的穩定解法

• • ensure_ascii=False 的多語輸出策略

• • GB 級 JSON 的串流處理方式

• • json、orjson、ujson 的取捨

---

1) loads/dumps 與 load/dump

• • json.dumps(obj)：Python 物件 -> JSON 字串

• • json.loads(text)：JSON 字串 -> Python 物件

• • json.dump(obj, file)：Python 物件 -> 寫入檔案

• • json.load(file)：檔案 -> Python 物件

簡單記憶：有 s 代表 string。

---

2) 解決 datetime 序列化錯誤

常見錯誤如下：

from datetime import datetime
import json

json.dumps({"now": datetime.now()})
# TypeError: Object of type datetime is not JSON serializable

建議用自訂 Encoder 統一轉換規則：

from datetime import datetime, date
import json

class DateTimeEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, datetime):
            return obj.isoformat()
        if isinstance(obj, date):
            return obj.isoformat()
        return super().default(obj)

payload = {"now": datetime.now(), "today": date.today()}
print(json.dumps(payload, cls=DateTimeEncoder, ensure_ascii=False, indent=2))

若你需要固定格式（例如 YYYY-MM-DD HH:MM:SS），可改用 strftime(...)。

---

3) 為何會看到 \uXXXX

預設情況下，json.dumps() 會跳脫非 ASCII 字元：

import json
print(json.dumps({"message": "你好，世界"}))
# {"message": "\u4f60\u597d\uff0c\u4e16\u754c"}

要保留可讀文字：

import json
print(json.dumps({"message": "你好，世界"}, ensure_ascii=False))

寫檔時請搭配 UTF-8：

with open("data.json", "w", encoding="utf-8") as f:
    json.dump({"message": "你好，世界"}, f, ensure_ascii=False)

---

4) GB 級 JSON 的串流讀取

若用 json.load() 一次讀完整個大陣列，容易造成記憶體壓力。實務上建議兩條路徑：

路徑 A：優先 JSON Lines（.jsonl）

import json

def read_jsonl(path):
    with open(path, "r", encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if line:
                yield json.loads(line)

for obj in read_jsonl("events.jsonl"):
    pass

路徑 B：大型陣列檔案使用 ijson

pip install ijson

import ijson

def iter_huge_array(path):
    with open(path, "rb") as f:
        for item in ijson.items(f, "item"):
            yield item

---

5) json / orjson / ujson 如何選

• • json（標準函式庫）：相容性高、零額外相依

• • orjson：效能敏感路徑通常更有優勢

• • ujson：替換成本低，但仍需驗證邊界行為

orjson 最小範例：

import orjson
from datetime import datetime

data = {"name": "Alice", "now": datetime.now()}
raw = orjson.dumps(data)  # bytes
obj = orjson.loads(raw)

---

6) 上線前檢查清單

1. 字串用 loads/dumps，檔案用 load/dump

1. datetime 規則集中到單一 Encoder

1. 多語產品預設使用 ensure_ascii=False

1. 日誌/事件資料優先採 JSON Lines

1. 效能路徑改庫前先做基準測試

---

繼續使用 JSON Work 工具

• • JSON 驗證器

• • JSON 美化器

• • JSON 轉 YAML

所有工具都在瀏覽器本地執行，資料不會上傳伺服器。

---

參考資料

• • Python json 官方文件

• • ijson（PyPI）

• • orjson（PyPI）