DevTool 團隊

JSON 貼進 Python 的三種姿勢:loads、字面量與型別註解的取捨

拿到一段 JSON 要在 Python 裡用,直接 json.loads、產生 dict 字面量、還是轉成帶型別註解的程式碼?這篇按用途分流:一次性指令碼 loads 讀原文最快,測試夾具與設定固化適合產生字面量(可讀、可改、可進版本庫),要型別安全上 dataclass 或 pydantic。講清映射規則與三個坑——true/false/null 的大小寫映射、超過 2^53 的大整數在瀏覽器端工具裡的精度邊界、帶連字號或數字開頭的鍵名不是合法識別字;最後是真話:手貼字典不是終點,真實專案裡 loads+模型類別比字面量可維護,往返轉換也不是無損校驗。

先分流:你要的是什麼

「JSON 轉 Python」背後是三種不同的需求,路線完全不同:

你的場景 正確姿勢 為什麼
一次性指令碼、資料來自檔案或介面 json.loads 讀原文 資料是「活的」,執行時解析最直接
測試夾具、demo 資料、要手工調的設定 產生 dict 字面量(JSON 轉 Python 字典轉換器) 程式碼形態可讀可改可進版本庫,IDE 能檢查
結構被多處消費、要型別安全 字面量看清結構後,沉澱成 dataclass / pydantic 型別檢查、明確報錯、預設值與校驗

三個路線不互斥,常見的工作流是:轉換工具看清結構 → 小場景直接用字面量 → 結構穩定後升級成模型類別。

工具怎麼用才順

以本站 JSON 轉 Python 字典轉換器 為例(雙向轉換,瀏覽器本機處理):

  • 方向:JSON→Python 產生 dict 字面量;Python→JSON 反向還原——除錯「我手裡這段到底該是什麼形態」時很方便;
  • 形態選項:要不要按字母序排鍵(對齊兩份結構時有用,平時關掉保序更自然)、要不要產生變數賦值與型別註解(data: dict = {...})、單雙引號與縮排風格——按你專案的風格約定來;
  • 框架預設:Django / Flask / FastAPI 三個片段預設,轉出的資料直接嵌進對應框架的用法骨架裡;
  • 錯誤定位:JSON 不合法時給出行列與原因,不是一句 parse error。

映射規則與三個坑

基礎映射表(轉字面量時大小寫嚴格區分,這是新手第一坑):

JSON Python
true / false True / False(首字母大寫,小寫在 Python 裡是語法錯)
null None
數字、字串 直接對應
陣列 [...] 串列 list
物件 {...} 字典 dict

三個更深的坑:

一、大整數精度邊界。 瀏覽器端工具用 JS 引擎解析,Number 的安全整數上限是 2^53-1——雪花 ID 這類大整數在解析階段就丟了精度,轉出的數字「看起來正常但就是錯的」。Python 的 int 無限精度,所以大整數場景的正解是把 JSON 存檔案、Python 側 json.loads 讀原文。

二、鍵名不是合法識別字。 "content-type"、"123abc" 作為 dict 鍵沒問題(方括號存取),但想轉成屬性存取或模型類別欄位就要改名(連字號換底線、數字開頭加前綴)。工具產生字面量不受影響,自己寫 dataclass 時要處理。

三、鍵排序改變語意觀感。 「按字母序排鍵」打開後,兩份結構不同的資料也能對齊比較——但它改變了欄位的自然順序,寫測試斷言時要注意 dict 相等雖然不看順序,人眼 diff 會變。排序是工具,不是預設真理。

真話:手貼字典不是終點

  • 真實專案裡,loads + 模型類別比手貼字面量可維護:介面回傳的資料今天加個欄位、明天改個型別,字面量要人肉同步,pydantic 模型改一處全域生效還能給出錯時的明確報錯。字面量的黃金場景是「死資料」:夾具、demo、一次性設定;
  • 雙向轉換不是無損往返:鍵排序會改變順序、型別註解反向不還原、Python 側的元組與集合 JSON 裡本來就沒有對應物——別拿「轉過去再轉回來等於原文」當校驗手段,要比對就用結構化比對工具;
  • 產生的程式碼是起點不是承諾:轉換器按你給的那份樣本推斷結構——樣本裡沒出現的欄位它不知道,可選欄位它當成必有。上線前把「我以為的結構」和「實際的結構」用真實資料對一遍。

常見問題

產生的 Python 字面量和 json.loads 的結果有什麼區別?

得到的東西等價,形態不同:字面量是一段可以直接編輯、提交進版本庫的程式碼;json.loads 是執行時從原文解析。判斷標準:資料是「死的」用字面量,是「活的」用 loads。字面量另有個隱性好處:IDE 能對它做語法檢查與補全,JSON 文字則要等執行時才暴露問題。

什麼時候該用 dataclass 或 pydantic,而不是手貼字典?

當這段結構會被多處程式碼消費、欄位較多、或來自不可信來源時:dataclass/pydantic 給你型別檢查、欄位缺失的明確報錯、預設值與校驗邏輯。反過來,一次性指令碼、結構簡單穩定的小設定,手貼字典更快更直接。常見組合:先用轉換工具看清結構,確認穩定後再沉澱成模型類別。

JSON 鍵名帶連字號或數字開頭,轉成 Python 怎麼處理?

作為 dict 的鍵沒有任何問題——Python 的鍵是字串,方括號存取即可。坑在兩處:屬性存取不行,必須方括號;產生型別註解或 dataclass 欄位時,不合法識別字要嘛改名要嘛加前綴。轉換工具產生字面量不受影響,但你自己寫模型類別時要處理這個映射。

超過 2^53 的大整數轉換會出問題嗎?

會,而且很隱蔽:瀏覽器端轉換工具用 JavaScript 引擎解析,安全整數上限是 2^53-1——超過這個量級的整數在解析階段就已經丟精度了,轉出來的程式碼裡是錯的數字,而且看起來毫無異常。Python 本身的 int 無限精度,所以正解是把 JSON 原文存成檔案,Python 側用 json.loads 讀。