簡介該資源是面向Java開發(fā)者的JSON完整示例包聚焦JSON數(shù)據(jù)交換格式的語法學(xué)習(xí)與解析/生成實(shí)戰(zhàn)。包體共22個(gè)文件、約2.88MB以json-lib系列jar包及commons等常用依賴為主同時(shí)包含可直接運(yùn)行的Java源文件、編譯后的class文件、項(xiàng)目配置文件以及一份JSON語法筆記導(dǎo)入IDE即可對(duì)照學(xué)習(xí)。目前已有3577人學(xué)習(xí)下載。示例覆蓋JSON對(duì)象、數(shù)組、嵌套對(duì)象等基本結(jié)構(gòu)演示字符串、數(shù)字、布爾值、null等數(shù)據(jù)類型的構(gòu)建與讀取并通過代碼展示JSON與Java對(duì)象之間的相互轉(zhuǎn)換。筆記部分還整理了鍵需雙引號(hào)、末項(xiàng)不能帶逗號(hào)等易錯(cuò)規(guī)則適合剛接觸JSON、希望快速掌握數(shù)據(jù)交換技能的開發(fā)者參考也可直接移植到實(shí)際接口調(diào)試或Web開發(fā)中復(fù)用。1. 一個(gè)看似簡單的格式為什么需要「完整例子」搜「json完整例子」的人通常不是沒看過 JSON 教程而是手頭正壓著一批數(shù)據(jù)要么是接口文檔只給了字段名沒給結(jié)構(gòu)要么是自己寫的 JSON 被前端一句「解析失敗」打回來要么是想把配置從 ini 遷到 JSON 卻不知道怎么組織層級(jí)。JSON 的語法半小時(shí)能學(xué)完但「能寫出來」和「一次寫對(duì)」是兩回事——完整例子的價(jià)值在于把字符串、數(shù)字、布爾、null、數(shù)組、對(duì)象六種數(shù)據(jù)類型按真實(shí)業(yè)務(wù)的形態(tài)組合起來讓你看到嵌套、轉(zhuǎn)義、空值這些寫的時(shí)候必須做的決策。這篇文章給的是可以直接抄走的完整例子、真實(shí)場景模板和排錯(cuò)手段適合正在寫接口、做配置、抓數(shù)據(jù)的開發(fā)者讀完能少走很多彎路。2. JSON 語法基礎(chǔ)從最小對(duì)象到完整數(shù)據(jù)類型示例2.1 六種數(shù)據(jù)類型完整例子首先要覆蓋的對(duì)象JSON 的全部數(shù)據(jù)類型只有六種字符串、數(shù)字、布爾值、null、數(shù)組、對(duì)象。數(shù)量少但很多寫錯(cuò)的人恰恰是在這六種類型的邊界上栽的跟頭。字符串必須用雙引號(hào)包裹單引號(hào)不合法數(shù)字支持整數(shù)和小數(shù)但不能有前導(dǎo)零不能寫 NaN 或 Infinity布爾值只有小寫的 true 和 falsenull 表示空值但「字段缺失」和「值為 null」在解析結(jié)果里是兩種完全不同的狀態(tài)數(shù)組用方括號(hào)元素可以是任意類型也可以混合對(duì)象用花括號(hào)鍵必須是帶雙引號(hào)的字符串。我見過的常見誤解是把 JSON 當(dāng)成 JavaScript 對(duì)象字面量。兩者寫法高度相似但 JSON 是一套獨(dú)立的數(shù)據(jù)交換格式它不允許注釋、不允許尾逗號(hào)、不允許不加引號(hào)的鍵名。凡是「在 JS 里能跑」的寫法放到 JSON.parse 里可能就是 SyntaxError。下面這張表把六種類型的合法寫法和常見錯(cuò)誤列在一起寫之前掃一眼能省不少排錯(cuò)時(shí)間類型合法示例常見錯(cuò)誤寫法字符串name: 示例單引號(hào)、中文引號(hào)數(shù)字price: 19.90019、NaN、Infinity布爾active: trueTrue、False、1nullremark: nullnull、NULL數(shù)組tags: [a, b]用圓括號(hào)、元素缺逗號(hào)對(duì)象user: {id: 1}鍵不加引號(hào)、尾逗號(hào)2.2 一個(gè)覆蓋全部語法的完整 JSON 示例文件下面這個(gè)例子故意把六種類型全部塞進(jìn)去同時(shí)包含兩層以上的嵌套你可以直接存成 example.json 做測試{ title: 訂單數(shù)據(jù)示例, orderId: ORD-2024-001, amount: 2999.50, quantity: 3, inStock: true, urgent: false, remark: null, tags: [加急, 禮品, 已付款], customer: { name: 示例用戶, level: 2, member: true, lastLoginAt: null }, items: [ { sku: SKU-A100, price: 899.00, attrs: { color: 黑, size: L } }, { sku: SKU-B200, price: 99.00, attrs: { color: 白, size: M } } ] }這個(gè)文件里title、orderId 是字符串a(chǎn)mount、quantity、level 是數(shù)字inStock、urgent、member 是布爾值remark 和 lastLoginAt 是 nulltags 是字符串?dāng)?shù)組customer 是對(duì)象items 是對(duì)象數(shù)組attrs 是對(duì)象套對(duì)象。如果你想驗(yàn)證某個(gè)解析器的行為邊界這個(gè)文件幾乎覆蓋了全部語法面。有幾個(gè)點(diǎn)值得單獨(dú)說。amount 寫成 2999.50 是合法的但解析后會(huì)被當(dāng)作 2999.5 處理小數(shù)末尾的 0 不會(huì)保留所以別指望 JSON 能保存「精確到分」的原始字符串金額這種字段要么用整數(shù)分存儲(chǔ)要么用字符串。null 字段在序列化時(shí)通常會(huì)保留鍵名這和「直接不寫這個(gè)鍵」不同后文會(huì)專門講。縮進(jìn)我這里用了兩個(gè)空格是個(gè)人推薦的默認(rèn)值緊湊、可讀、深嵌套時(shí)不會(huì)讓行寬失控。2.3 縮進(jìn)、換行與格式化玄學(xué)還是規(guī)范縮進(jìn)不影響 JSON 的合法性但影響排查問題的效率。兩個(gè)空格和四個(gè)空格都常見團(tuán)隊(duì)內(nèi)部統(tǒng)一即可真正影響合法性的只有三件事鍵必須帶雙引號(hào)、字符串必須用雙引號(hào)、不允許尾逗號(hào)?？s進(jìn)只是給人看的機(jī)器完全不關(guān)心。換行同理。JSON 里的空白字符在語法層面完全等價(jià)你可以把整個(gè) JSON 壓成一行做傳輸也可以格式化成一棵清晰的樹。我一般遵循「傳輸用緊湊型、落盤用格式化」的習(xí)慣接口響應(yīng)為了減小體積常常去空格本地配置文件則保持格式化方便 diff 和 review。如果你拿到一個(gè)被壓縮成一行的大 JSON別用肉眼去讀直接丟給格式化工具幾秒鐘就能變成可讀結(jié)構(gòu)。注意格式化工具只能調(diào)整空白和縮進(jìn)不會(huì)幫你修復(fù)語法錯(cuò)誤。如果 JSON 本身有尾逗號(hào)或單引號(hào)工具會(huì)直接報(bào)錯(cuò)這時(shí)候先按第 4 章的清單排查。3. 真實(shí)場景中的 JSON 完整例子配置文件與 API 響應(yīng)3.1 把 JSON 當(dāng)配置文件一個(gè)服務(wù)配置的完整例子JSON 做配置文件的優(yōu)勢是層級(jí)表達(dá)能力強(qiáng)ini 風(fēng)格的扁平鍵值對(duì)在表達(dá)「數(shù)據(jù)庫連接池 日志輪轉(zhuǎn) 功能開關(guān)」這類組合時(shí)非常吃力。下面這個(gè)例子是一個(gè)典型的服務(wù)配置我把它當(dāng)模板用了很久{ server: { host: 0.0.0.0, port: 8080, workers: 4, shutdownTimeoutSeconds: 30 }, database: { host: 127.0.0.1, port: 3306, name: app_db, user: app_user, password: change_me, poolSize: 10, options: { charset: utf8mb4, timezone: 08:00 } }, logging: { level: info, file: /var/log/app.log, maxSizeMb: 100, backupCount: 7 }, features: { enableCache: true, cacheTtlSeconds: 300, rateLimit: { enabled: true, maxRequestsPerMinute: 120 } } }層級(jí)設(shè)計(jì)是配置文件里最關(guān)鍵的決策。我的習(xí)慣是「第一層按模塊分第二層按參數(shù)分超過兩層就警惕」上面的 server、database、logging、features 是第一層options 和 rateLimit 是第二層嵌套再往下就建議拆成獨(dú)立配置或用配置中心了。嵌套太深會(huì)讓使用者每次取值都寫一長串路徑比如 features.rateLimit.maxRequestsPerMinute在代碼里維護(hù)起來非常痛苦。這個(gè)配置里還藏著一個(gè)常用教訓(xùn)密碼以明文寫在 JSON 里。JSON 沒有注釋機(jī)制所以你不能像 ini 那樣在文件里寫「這是測試密碼上線前要換」常見的做法是用環(huán)境變量占位符替代敏感字段或者在啟動(dòng)時(shí)由配置中心注入。至少要做到這個(gè)文件不進(jìn)版本庫。另外端口號(hào)寫成數(shù)字而不是字符串是有意為之配置加載后會(huì)被類型化如果你的代碼里 expects 字符串需要先做一次類型轉(zhuǎn)換這是 YAML 和 JSON 配置里常見的類型陷阱。3.2 API 響應(yīng)里的 JSON列表、分頁與錯(cuò)誤碼怎么設(shè)計(jì)接口返回的 JSON 是另一個(gè)高頻場景。下面是我推薦的一種「統(tǒng)一響應(yīng)殼」結(jié)構(gòu)所有接口都返回同一個(gè)外殼code 表示業(yè)務(wù)狀態(tài)碼message 是人類可讀的說明data 放真正的業(yè)務(wù)數(shù)據(jù){ code: 0, message: success, data: { list: [ { id: 1001, title: 第一個(gè)商品, price: 19.90, stock: 120, tags: [熱銷], seller: { id: 5, name: 店鋪甲 } }, { id: 1002, title: 第二個(gè)商品, price: 299.00, stock: 0, tags: [], seller: { id: 9, name: 店鋪乙 } } ], page: 1, pageSize: 10, total: 2 } }分頁參數(shù)放在 data 里而不是外殼里是我見過比較穩(wěn)妥的約定。code 為 0 表示成功非 0 表示業(yè)務(wù)失敗HTTP 狀態(tài)碼只表達(dá)傳輸層結(jié)果比如 200、404、500業(yè)務(wù)成功與否由 code 決定兩層分開前端才能精確處理「接口通了但業(yè)務(wù)失敗」的情況。注意第二個(gè)商品的 stock 是 0而 tags 是空數(shù)組這兩個(gè)值和 null 語義完全不同前端渲染時(shí)要區(qū)分「無庫存」和「無標(biāo)簽」。一個(gè)容易踩的坑是錯(cuò)誤響應(yīng)格式不統(tǒng)一。有的接口失敗時(shí)只返回{code: 500, message: error}有的直接把 data 丟掉還有的在 data 里塞一個(gè) error 對(duì)象。我的建議是所有失敗響應(yīng)都保持和成功響應(yīng)一樣的外殼結(jié)構(gòu)data 可以置 null但鍵不能缺。前端拿到響應(yīng)先解外殼再解數(shù)據(jù)代碼路徑單一比到處判斷某個(gè)鍵是否存在好維護(hù)得多。3.3 從接口返回里提取字段Python 與 JavaScript 的最小解析代碼有了完整例子下一個(gè)訴求就是怎么解析。下面用 Python 和 JavaScript 各給一段最小解析代碼。Python 側(cè)用標(biāo)準(zhǔn)庫 jsonimport json with open(api_response.json, r, encodingutf-8) as f: data json.load(f) if data[code] ! 0: raise RuntimeError(f業(yè)務(wù)錯(cuò)誤: {data[message]}) page data[data][page] total data[data][total] print(f第 {page} 頁共 {total} 條) for item in data[data][list]: title item[title] price item[price] stock item[stock] print(title, price, stock)這段代碼先解析文件為 Python 字典再判斷業(yè)務(wù)碼最后遍歷列表。參數(shù)說明json.load 接收文件對(duì)象json.loads 接收字符串兩者別混文件必須用 encodingutf-8 打開否則含中文的 JSON 在部分環(huán)境下會(huì)拋 UnicodeDecodeError取嵌套字段要逐層用方括號(hào)比如 data[data][list]中間任何一層鍵不存在都會(huì)拋 KeyError不要指望缺鍵時(shí)返回 None。JavaScript 側(cè)用內(nèi)置的 JSON.parseconst data JSON.parse(responseText); if (data.code ! 0) { throw new Error(data.message); } const { list, page, total } data.data; console.log(第 ${page} 頁共 ${total} 條); list.forEach((item) { console.log(item.title, item.price, item.stock); });JSON.parse 的入?yún)⒈仨毷亲址绻阋呀?jīng)拿到一個(gè)對(duì)象再傳給 JSON.parse 會(huì)原樣返回不報(bào)錯(cuò)但也沒有意義。解構(gòu)賦值在這里很好用data.data.list 這種路徑用解構(gòu)一次拆平后續(xù)代碼可讀性會(huì)好很多。注意 responseText 的來源如果是 XMLHttpRequest要確認(rèn)請求已完成且狀態(tài)是 200否則 parse 的可能是空字符串直接拋 SyntaxError。4. 手寫 JSON 的避坑指南5 個(gè)最常見的翻車現(xiàn)場4.1 尾逗號(hào)與單引號(hào)為什么編輯器不幫你糾錯(cuò)現(xiàn)象手寫的 JSON 里最后一個(gè)鍵值對(duì)后面習(xí)慣性加了逗號(hào)或者所有字符串都用了單引號(hào)貼進(jìn)代碼里 JSON.parse 直接拋 SyntaxErrorPython 的 json.load 報(bào) JSONDecodeError。原因JSON 規(guī)范明確禁止尾逗號(hào)也明確要求雙引號(hào)。很多人在寫 JavaScript 對(duì)象字面量時(shí)養(yǎng)成了加尾逗號(hào)、用單引號(hào)的習(xí)慣但 JSON 不是 JS 對(duì)象字面量解析器嚴(yán)格按規(guī)范執(zhí)行不會(huì)因?yàn)槟恪缚雌饋聿畈欢唷咕头判?。編輯器默認(rèn)也不會(huì)把 .json 文件當(dāng) JS 處理語法高亮和自動(dòng)糾錯(cuò)都不生效。解決寫完后統(tǒng)一用工具校驗(yàn)。命令行里python -m json.tool data.json是最快的檢查方式有語法錯(cuò)誤會(huì)直接告訴你第幾行第幾個(gè)字符出問題編輯器里裝帶 JSON 校驗(yàn)的插件寫錯(cuò)時(shí)實(shí)時(shí)標(biāo)紅。養(yǎng)成「寫完即校驗(yàn)」的習(xí)慣后這類問題幾乎不會(huì)再出現(xiàn)。4.2 數(shù)字與 null 的邊界0、空字符串、缺失字段現(xiàn)象接口返回里字段值為 0、空字符串、null或者干脆沒有這個(gè)鍵前端用 if(field) 判斷時(shí)把它們?nèi)慨?dāng)成 falsy導(dǎo)致「庫存為 0 的商品」和「沒有庫存字段的商品」被當(dāng)成同一種情況頁面渲染錯(cuò)亂。原因JSON 里的空值語義和編程語言里的 falsy 語義不同。0 是有效數(shù)字空字符串是有效字符串null 是顯式空值而字段缺失在解析結(jié)果里表現(xiàn)為「鍵不存在」。在 Python 里取缺失鍵會(huì)拋 KeyError在 JavaScript 里得到 undefined這兩者都和 null 嚴(yán)格區(qū)分。解決前后端先約定語義。我一般規(guī)定有值就寫真實(shí)值無值用 null絕不通過「不寫這個(gè)鍵」來表達(dá)空。前端判斷時(shí)用value null同時(shí)覆蓋 null 和 undefined再用value 0、value 精確處理邊界。不要用 if(value) 這種寬松判斷處理業(yè)務(wù)字段它會(huì)把 0 和空字符串一起吞掉。4.3 轉(zhuǎn)義字符與 Unicode中文變成 \uXXXX 怎么辦現(xiàn)象從接口拿到的 JSON 里中文全是 \u4f60\u597d 這樣的轉(zhuǎn)義序列看著像亂碼或者字符串里本身包含雙引號(hào)和反斜杠手寫時(shí)沒轉(zhuǎn)義解析直接報(bào)錯(cuò)。原因JSON 字符串里的雙引號(hào)必須寫成 反斜杠必須寫成 \這是語法要求。而中文變成 \uXXXX 通常是發(fā)送方在序列化時(shí)開啟了 ASCII 轉(zhuǎn)義比如 Python 的 json.dumps 默認(rèn)會(huì)把非 ASCII 字符轉(zhuǎn)成 \u 序列這是合法 JSON只是人眼不友好。解決不要手改轉(zhuǎn)義序列。解析后正常顯示中文格式化工具也會(huì)還原 Unicode如果你要自己生成 JSON用語言自帶的序列化函數(shù)而不是字符串拼接。Python 里 json.dumps(data, ensure_asciiFalse) 可以保留中文配合 indent 參數(shù)控制縮進(jìn)生成的文件直接可讀。記住一個(gè)原則JSON 的讀寫都應(yīng)該經(jīng)過解析器永遠(yuǎn)不要手工拼接字符串。4.4 嵌套層級(jí)過深解析器真的會(huì)拒絕嗎現(xiàn)象一個(gè) JSON 嵌套了 50 層Python 的 json.load 拋 RecursionError某些 C 語言實(shí)現(xiàn)的解析器直接棧溢出進(jìn)程崩潰。原因遞歸下降解析器按調(diào)用棧處理嵌套默認(rèn)遞歸深度有限制。Python 的 json 模塊在嵌套超過約 1000 層時(shí)會(huì)觸發(fā) RecursionErrorC 系解析器可能更早出問題。深度嵌套的數(shù)據(jù)大多數(shù)來自程序自動(dòng)生成手寫很少會(huì)觸發(fā)但一旦觸發(fā)就是進(jìn)程級(jí)故障比語法錯(cuò)誤嚴(yán)重得多。解決設(shè)計(jì)數(shù)據(jù)結(jié)構(gòu)時(shí)把嵌套控制在 10 層以內(nèi)這既是解析安全也是可讀性要求。超過 10 層應(yīng)該考慮用展開的列表加 id 引用來建模比如把無限級(jí)菜單改成平鋪節(jié)點(diǎn)數(shù)組加 parentId 字段。如果數(shù)據(jù)源是別人給的、無法控制深度改用流式解析器Python 里可以換用 ijson它邊讀邊解析不依賴調(diào)用棧深度。4.5 用工具驗(yàn)證json.tool 與在線校驗(yàn)器的取舍現(xiàn)象肉眼審查了幾遍覺得沒問題發(fā)給對(duì)方還是被退回最后發(fā)現(xiàn)是某個(gè)字符串里的雙引號(hào)沒轉(zhuǎn)義。這種事非常常見尤其是嵌套多、字符串長的 JSON人腦會(huì)自動(dòng)忽略結(jié)構(gòu)錯(cuò)誤。原因肉眼檢查對(duì)嵌套多、字符串長的 JSON 不可靠引號(hào)配對(duì)這種需要逐字符確認(rèn)的細(xì)節(jié)人眼很容易跳過。寫完 JSON 直接復(fù)制粘貼到業(yè)務(wù)代碼里等運(yùn)行時(shí)報(bào)錯(cuò)再回頭查中間的時(shí)間全部浪費(fèi)了。解決本地命令行工具是首選。python -m json.tool data.json能校驗(yàn)并格式化jq . data.json同樣能做額外還能提取字段、過濾數(shù)據(jù)。在線校驗(yàn)器只在萬不得已時(shí)用把接口數(shù)據(jù)貼到網(wǎng)頁上有泄露風(fēng)險(xiǎn)尤其是包含用戶信息或內(nèi)部字段的數(shù)據(jù)。我現(xiàn)在的習(xí)慣是任何手動(dòng)改過的 JSON提交前必須過一遍 json.tool這個(gè)動(dòng)作十秒鐘能擋掉絕大多數(shù)低級(jí)錯(cuò)誤屬于投入產(chǎn)出比最高的一道防線。5. JSON Schema給「完整例子」加一道質(zhì)量檢驗(yàn)5.1 為什么光有例子不夠完整例子能告訴你數(shù)據(jù)「長什么樣」但不能保證別人寫的或程序生成的數(shù)據(jù)「符合預(yù)期」。對(duì)方可能漏了必填字段可能把 price 傳成了字符串可能嵌套結(jié)構(gòu)完全不對(duì)。這個(gè)時(shí)候需要 JSON Schema——用一份描述性文件規(guī)定數(shù)據(jù)結(jié)構(gòu)數(shù)據(jù)進(jìn)來先校驗(yàn)不合格直接拒收不用等運(yùn)行到業(yè)務(wù)邏輯深處才爆出詭異問題。JSON Schema 本身也是一個(gè) JSON這是它最妙的地方定義結(jié)構(gòu)的文件和被校驗(yàn)的數(shù)據(jù)用同一種格式表達(dá)。它支持聲明必填字段、字段類型、取值范圍、數(shù)組長度、對(duì)象嵌套規(guī)則是給「完整例子」加自動(dòng)化檢驗(yàn)最直接的手段。把 Schema 掛在接口文檔旁邊等于把「例子」升級(jí)成了「契約」。5.2 一個(gè)最小可用的 Schema 示例對(duì)應(yīng)第 2.2 節(jié)的訂單例子寫一個(gè)最小 Schema校驗(yàn)它的核心字段{ $schema: http://json-schema.org/draft-07/schema#, title: 訂單數(shù)據(jù)校驗(yàn), type: object, required: [orderId, amount, customer, items], properties: { orderId: { type: string, minLength: 1 }, amount: { type: number, minimum: 0 }, inStock: { type: boolean }, remark: { type: [string, null] }, tags: { type: array, items: { type: string }, maxItems: 20 }, customer: { type: object, required: [name], properties: { name: { type: string }, level: { type: integer, minimum: 1, maximum: 5 } } }, items: { type: array, minItems: 1, items: { type: object, required: [sku, price], properties: { sku: { type: string }, price: { type: number, minimum: 0 } } } } } }這段 Schema 里最值得注意的聲明required 數(shù)組列出必須存在的鍵remark 的 type 是[string, null]表示它允許為空amount 用 minimum 限制不能為負(fù)items 里的元素對(duì)象被遞歸聲明了結(jié)構(gòu)數(shù)組內(nèi)每個(gè)對(duì)象都必須有 sku 和 price。每一層嵌套都要寫對(duì)應(yīng)的 type 和 properties這正是「完整例子」變成「完整契約」的過程例子給的是形態(tài)Schema 給的是約束。注意一個(gè)細(xì)節(jié)level: { type: integer }卡住了浮點(diǎn)數(shù)如果你接口里的 level 可能返回 2.5這里會(huì)校驗(yàn)失敗所以定義 Schema 前要先確認(rèn)業(yè)務(wù)上真的只接受整數(shù)。Schema 寫得越嚴(yán)誤傷越多寫得越松校驗(yàn)越?jīng)]意義。這個(gè)度需要對(duì)著真實(shí)數(shù)據(jù)調(diào)幾輪。5.3 用 Schema 校驗(yàn)數(shù)據(jù)的命令行實(shí)踐Python 生態(tài)里有現(xiàn)成的 jsonschema 庫安裝后幾行代碼就能跑校驗(yàn)pip install jsonschema校驗(yàn)?zāi)_本import json from jsonschema import validate, ValidationError with open(schema.json, r, encodingutf-8) as f: schema json.load(f) with open(data.json, r, encodingutf-8) as f: data json.load(f) try: validate(instancedata, schemaschema) print(校驗(yàn)通過) except ValidationError as e: print(f校驗(yàn)失敗: {e.message}) print(f出錯(cuò)位置: {list(e.path)})validate 函數(shù)接收兩個(gè)參數(shù)instance 是要校驗(yàn)的數(shù)據(jù)schema 是結(jié)構(gòu)定義。校驗(yàn)失敗時(shí) ValidationError 會(huì)帶出具體錯(cuò)誤信息和字段路徑比如19.9 is not of type integer一眼就能定位問題。如果你不想寫腳本也可以用命令行工具 check-jsonschema把 schema 文件和待校驗(yàn)文件直接丟給它。我一般在接口聯(lián)調(diào)階段就把 Schema 掛進(jìn)自動(dòng)化測試每次 mock 數(shù)據(jù)先過 Schema再進(jìn)業(yè)務(wù)代碼。這樣「例子對(duì)不對(duì)」由機(jī)器說了算而不是靠人肉 review。Schema 和例子放同一個(gè)目錄改接口先改 Schema 再改例子兩邊漂移會(huì)大幅減少。這也是一個(gè)能被團(tuán)隊(duì)長期復(fù)用的資產(chǎn)比散落在文檔里的字段說明可靠得多。6. 把 JSON 例子變成自己的模板格式化與生成技巧先記一個(gè)通用習(xí)慣拿到任何 JSON 第一件事是jq .格式化而不是直接打開看。壓縮成一行的大 JSON 用肉眼讀是災(zāi)難格式化后結(jié)構(gòu)一目了然。jq 還能順手提取字段比如從第 3.2 節(jié)的接口響應(yīng)里只挑商品名和價(jià)格jq . data.json jq .data.list[] | {title, price} api_response.json第一個(gè)命令做格式化校驗(yàn)第二個(gè)命令做字段提取。jq 的過濾器語法值得花半小時(shí)學(xué)它是處理 JSON 最順手的命令行工具比 grep 可靠得多。第二個(gè)習(xí)慣JSON 靠代碼生成不靠手寫。尤其是配置文件和接口響應(yīng)這種會(huì)被反復(fù)修改的結(jié)構(gòu)手寫容易漏引號(hào)、加錯(cuò)逗號(hào)生成則永遠(yuǎn)正確。下面是一段 Python 生成配置文件的腳本import json config { server: { host: 0.0.0.0, port: 8080, workers: 4 }, features: { enableCache: True, cacheTtlSeconds: 300 } } with open(config.json, w, encodingutf-8) as f: json.dump(config, f, ensure_asciiFalse, indent2)json.dump 的三個(gè)關(guān)鍵參數(shù)ensure_asciiFalse 保留中文原文indent2 輸出帶縮進(jìn)的格式化文本sort_keysTrue 可選按字母序排鍵方便 diff。生成完畢后仍然跑一遍 json.tool 確認(rèn)雙保險(xiǎn)。第三個(gè)習(xí)慣是維護(hù)自己的模板庫。把第 2.2 節(jié)的完整類型示例、第 3.1 節(jié)的配置模板、第 3.2 節(jié)的接口響應(yīng)殼、第 5.2 節(jié)的 Schema 骨架存成模板文件新建項(xiàng)目直接復(fù)制改字段比每次從零開始寫省很多時(shí)間。我吃過一次虧某個(gè)項(xiàng)目里手寫了一個(gè) 200 行的嵌套 JSON沒校驗(yàn)就提交結(jié)果 CI 直接掛掉排查發(fā)現(xiàn)是第三層某個(gè)字符串忘了轉(zhuǎn)義那之后所有 JSON 改動(dòng)都必須過工具不再相信自己的眼睛。希望你從第一個(gè) JSON 起就養(yǎng)成這個(gè)習(xí)慣少走我走過的彎路希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取