nlohmann/jsonJSON for Modern C序列化全指南dump()、流輸出、pretty-print 與格式化【免費(fèi)下載鏈接】jsonJSON for Modern C項(xiàng)目地址: https://gitcode.com/GitHub_Trending/js/json序列化Serialization是把內(nèi)存中的 JSON 值重新還原為 JSON 文本的過程是解析Parsing的逆操作。本文以本項(xiàng)目文檔 docs/mkdocs/docs/features/serialization.md 為主線結(jié)合核心 API 文檔與底層實(shí)現(xiàn) serializer.hpp系統(tǒng)講解dump()的全部參數(shù)、operator流式輸出、UTF-8 與非法字節(jié)處理、NaN/無窮值/二進(jìn)制值的行為以及 C20std::format/std::print與 {fmt} 庫的格式化用法。讀完本文你將能精確控制 JSON 輸出的縮進(jìn)、轉(zhuǎn)義與容錯(cuò)策略并避開序列化過程中的各類坑。序列化把 JSON 值變回 JSON 文本在 nlohmann/json 中序列化指把一個(gè)basic_json值轉(zhuǎn)換成一段合法的 JSON 文本與 解析 恰好相反。這一操作的核心入口是成員函數(shù)dump()它把值序列化為一個(gè)字符串string_t返回#include nlohmann/json.hpp using json nlohmann::json; json j {{pi, 3.141}, {happy, true}}; std::string s j.dump(); // {happy:true,pi:3.141}如果希望把值直接寫入某個(gè)輸出流例如文件或std::cout庫提供了 流運(yùn)算符operatorstd::cout j std::endl;值得一提的是流輸出在內(nèi)部仍然調(diào)用dump()但其縮進(jìn)級別由流的width可配合std::setw控制縮進(jìn)字符由流的fill可配合std::setfill控制例如std::setw(4)等價(jià)于dump(4)。dump 返回的是JSON 文本不是裸值一個(gè)常見的誤解是dump()會把字符串值原樣取出。請務(wù)必記住dump()永遠(yuǎn)返回一段 JSON 文本。因此當(dāng) JSON 值本身是字符串時(shí)序列化結(jié)果會包含包圍它的雙引號并對特殊字符做轉(zhuǎn)義json j hello; std::string s j.dump(); // hello含引號若想取得字符串內(nèi)部的實(shí)際內(nèi)容不帶引號、不轉(zhuǎn)義應(yīng)使用類型轉(zhuǎn)換getstd::string()而不是dump()。dump() 的四個(gè)參數(shù)詳解dump()的完整簽名見 dump API 文檔如下string_t dump(const int indent -1, const char indent_char , const bool ensure_ascii false, const error_handler_t error_handler error_handler_t::strict) const;indent非負(fù)時(shí)啟用 pretty-print每級縮進(jìn)該數(shù)量的空格0只插入換行、不插入空格-1默認(rèn)為最緊湊的單行形式。indent_char當(dāng)indent 0時(shí)使用的縮進(jìn)字符默認(rèn)是空格可傳\t等任意字符。ensure_ascii為true時(shí)把全部非 ASCII 字符以\uXXXX序列轉(zhuǎn)義使輸出只含 ASCII 字符。error_handler遇到非法 UTF-8 時(shí)的處理策略取值見error_handler_t默認(rèn)strict。該 API 參考了 Python 的json.dumps()目前支持其indent與ensure_ascii兩個(gè)參數(shù)。從實(shí)現(xiàn)看dump()具有強(qiáng)異常安全保證拋出異常時(shí)不會對任何 JSON 值造成改動且整體復(fù)雜度為線性。緊湊輸出與 Pretty-print默認(rèn)情況下dump()產(chǎn)生最緊湊的表示不含任何多余空白。傳入非負(fù)的indent后輸出會按每級若干空格進(jìn)行美化。文檔配套的完整示例見 examples/dump.cpp其輸出見 examples/dump.output#include iostream #include nlohmann/json.hpp using json nlohmann::json; int main() { // create JSON values json j_object {{one, 1}, {two, 2}}; json j_array {1, 2, 4, 8, 16}; json j_string Hell? !; // call dump() std::cout objects: \n j_object.dump() \n\n j_object.dump(-1) \n\n j_object.dump(0) \n\n j_object.dump(4) \n\n j_object.dump(1, \t) \n\n; // ... 數(shù)組與字符串部分類似 }不同參數(shù)對應(yīng)的實(shí)際輸出為objects: {one:1,two:2} // dump()最緊湊 {one:1,two:2} // dump(-1)等價(jià)于默認(rèn) { one: 1, // dump(0)只換行不縮進(jìn) two: 2 } { one: 1, // dump(4)每級 4 空格 two: 2 } { one: 1, // dump(1, \t)縮進(jìn)字符改為制表符 two: 2 } arrays: [1,2,4,8,16] // dump() 緊湊形式 [ 1, // dump(4) 2, 4, 8, 16 ]觀察輸出可以總結(jié)出三條規(guī)則縮進(jìn)字符可通過第二個(gè)參數(shù)修改例如制表符\tindent為0時(shí)只插入換行、不插入前導(dǎo)空格默認(rèn)indent -1選擇緊湊單行形式。這些行為與底層實(shí)現(xiàn)一一對應(yīng)。在 serializer.hpp 中dump()會對對象/數(shù)組進(jìn)行遞歸序列化緊湊模式下對象成員寫作key:value而 pretty-print 模式下寫作key: value并在元素間追加,\n與前導(dǎo)縮進(jìn)。縮進(jìn)字符串在構(gòu)造時(shí)預(yù)分配初始indent_string為 512 個(gè)字符若遞歸層級超出則按兩倍擴(kuò)容從而避免逐層拼接帶來的開銷。非 ASCII 字符與 ensure_ascii字符串在庫內(nèi)部以 UTF-8 存儲與序列化見 類型說明 中關(guān)于字符串的部分。默認(rèn)情況下dump()會把合法的非 ASCII 字符原樣拷貝到輸出而將第三個(gè)參數(shù)ensure_ascii設(shè)為true則會把所有非 ASCII 字符轉(zhuǎn)義成\uXXXX序列使輸出嚴(yán)格只含 ASCIIjson j 蘋果; j.dump(); // 蘋果 j.dump(-1, , true); // \u82f9\u679c全 ASCII在官方示例中Hell? !的默認(rèn)輸出與ensure_ascii輸出分別是Hell? ! Hell\u00f6 \ud83d\ude00!即?轉(zhuǎn)義為\u00f6而 emoji屬于補(bǔ)充平面、由代理對編碼被轉(zhuǎn)義為\ud83d\ude00。ensure_ascii輸出對下游系統(tǒng)若只支持 ASCII 編碼例如某些日志管道、遺留存儲非常實(shí)用。處理非法 UTF-8strict / replace / ignore如果一個(gè)字符串內(nèi)部含有非法 UTF-8 序列例如其中存放的是 Latin-1 等其他編碼的數(shù)據(jù)默認(rèn)的strict模式下序列化會直接失敗并拋出type_error.316異常。dump()的第四個(gè)參數(shù)error_handler用于選擇處理策略其取值定義在枚舉error_handler_t源碼見 serializer.hpp取值行為strict默認(rèn)遇到非法 UTF-8 時(shí)拋出type_error.316異常replace用 Unicode 替換字符 UFFFD替代非法字節(jié)ignore靜默丟棄非法字節(jié)合法字節(jié)原樣拷貝配套示例 examples/error_handler_t.cpp 構(gòu)造了含非法字節(jié)\xA9的字符串?\xA9ü三種策略的運(yùn)行結(jié)果見 examples/error_handler_t.output為[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9 string with replaced invalid characters: ?ü string with ignored invalid characters: ?ü即strict拋出含非法字節(jié)索引與字節(jié)值的異常信息replace輸出替換字符ignore則直接把非法字節(jié)刪去。序列化不可信輸入的注意事項(xiàng)API 文檔特別提醒當(dāng)序列化的數(shù)據(jù)可能含非法或不可信的 UTF-8例如直接取自網(wǎng)絡(luò)輸入、未經(jīng)校驗(yàn)的字節(jié)流時(shí)默認(rèn)的strict模式會拋出異常。在崩潰敏感路徑上處理這類數(shù)據(jù)應(yīng)當(dāng)顯式傳入error_handler_t::replace替換為 UFFFD或error_handler_t::ignore丟棄非法字節(jié)或用try/catch包裹dump()調(diào)用。避免非法 UTF-8 的最佳實(shí)踐最根本的修復(fù)方式是在存入JSON 值之前就確保所有字符串均為合法 UTF-8。寬字符wchar_t/std::wstring或 Latin-1 等編碼的轉(zhuǎn)換方法可參考 FAQ 中關(guān)于非 ASCII 字符的解析錯(cuò)誤說明。從源碼實(shí)現(xiàn)看轉(zhuǎn)義過程由dump_escaped()serializer.hpp 中的私有成員完成它對字符串逐字節(jié)進(jìn)行 UTF-8 狀態(tài)機(jī)校驗(yàn)常量UTF8_ACCEPT/UTF8_REJECT用于維護(hù)解碼狀態(tài)同時(shí)完成控制字符的\uXXXX轉(zhuǎn)義、ensure_ascii處理與非法字節(jié)的判定最終按error_handler決定拋異常、替換還是丟棄。數(shù)字、NaN/無窮值與二進(jìn)制值數(shù)字保證 round-trip 的精度浮點(diǎn)數(shù)在 JSON 中沒有精度的概念但 nlohmann/json 會以足夠往返round-trip的精度序列化數(shù)字即序列化→再解析后數(shù)值保持不變詳見 數(shù)字處理文檔。底層實(shí)現(xiàn)serializer.hpp做了分層處理若number_float_t是 IEEE-754 單精度或雙精度浮點(diǎn)通過is_iec559、digits、max_exponent檢測則調(diào)用detail::to_chars()頭文件 to_chars.hpp使用 Grisu2 算法生成最短的、保證strtof/strtod往返的十進(jìn)制表示對于其他浮點(diǎn)類型如long double相關(guān)配置回退到snprintf的%.*g/%.*Lg格式并顯式移除千分位分隔符、把本地化小數(shù)點(diǎn)改寫為.必要時(shí)補(bǔ)寫.0確保輸出始終是符合 JSON 語法的數(shù)字字面量。NaN 與無窮值序列化為 nullNaN與±infinity無法用 JSON 表示因此dump()會把它們序列化為null。這在源碼中有直接體現(xiàn)dump_float()開頭即判斷if (!std::isfinite(x))并輸出nullserializer.hpp。若需要保留這些特殊值應(yīng)改用 二進(jìn)制格式CBOR、MessagePack 等進(jìn)行序列化。二進(jìn)制值僅作調(diào)試用的輔助對象binary_t類型的二進(jìn)制值沒有對應(yīng)的 JSON 表示dump()會將其序列化為一個(gè)包含兩個(gè)鍵的輔助對象bytes以整數(shù)數(shù)組形式給出的字節(jié)序列subtype子類型整數(shù)若沒有子類型則為null。例如緊湊輸出形如{bytes:[1,2,3],subtype:null}。從 serializer.hpp 的實(shí)現(xiàn)可見二進(jìn)制值被當(dāng)作對象輸出并通過has_subtype()判斷是否渲染subtype。注意這只是調(diào)試用途的表示無法再被parse()還原為原始二進(jìn)制數(shù)據(jù)parse不會把此類對象自動轉(zhuǎn)回 binary 值想要無損往返請使用 二進(jìn)制格式 或 binary_values 相關(guān)說明。使用 std::format、std::print 與 {fmt}從版本 3.12.0 起只要標(biāo)準(zhǔn)庫提供format頭由宏JSON_HAS_STD_FORMAT控制JSON 值就可以直接用 C20 的std::format格式化。這是通過std::formatterbasic_json特化實(shí)現(xiàn)的該特化同樣讓 JSON 值可用于std::format_to以及 C23 的std::print/std::printlnstd::print({}, j); // 緊湊形式等價(jià)于 j.dump() std::print({:2}, j); // 以縮進(jìn) 2 美化輸出等價(jià)于 j.dump(2) std::println({:#}, j); // 以默認(rèn)縮進(jìn)美化輸出等價(jià)于 j.dump(4)格式化規(guī)格與dump()參數(shù)一一對應(yīng){}緊湊序列化行為同dump(){:#}alternate form行為同dump(4)即默認(rèn) 4 空格縮進(jìn)美化寬度如{:2}或{:#2}等價(jià)于dump(width)——寬度本身即隱含美化輸出因?yàn)榭s進(jìn)寬度對緊湊輸出沒有意義fill-and-align 前綴如{:.#}、{:.3}用于指定自定義縮進(jìn)字符等價(jià)于dump(indent, indent_char)。其中對齊方向字符//^對 JSON 值沒有獨(dú)立含義僅其前面的填充字符生效。需要留意的是上述格式規(guī)格只支持這一子集其余標(biāo)準(zhǔn) format 規(guī)格正負(fù)號、0標(biāo)志、精度、L、動態(tài)寬度{:{}}、尾部類型字符等會拋出std::format_error。特化僅對char版basic_json生效。對于 {fmt} 庫fmtlib庫內(nèi)附帶了一個(gè)format_as輔助函數(shù)。注意其行為依賴fmt的版本具體細(xì)節(jié)與完整的fmt::formatter特化配方參見 FAQ 相關(guān)條目。兩個(gè)格式化入口的對照可參考 std_formatter 示例 及其 輸出。序列化到其他格式除 JSON 文本外同一個(gè)值還可以序列化為更緊湊的 二進(jìn)制格式BJData、BSON、CBOR、MessagePack、UBJSON。這些格式的序列化由 binary_writer.hpp 承擔(dān)它們是dump()之外按需選用的補(bǔ)充通道例如保留 NaN/無窮值與二進(jìn)制類型。底層dump 是如何分派的把 JSON 值序列化為文本的核心邏輯集中在 serializer.hpp 的serializer::dump()它首先通過switch按value_t類型分派然后對每種類型執(zhí)行專門的輸出例程對象/數(shù)組遞歸調(diào)用自身空對象/數(shù)組直接寫{}/[]字符串與對象鍵交給dump_escaped()做轉(zhuǎn)義整數(shù)由dump_integer()使用 100 項(xiàng)兩位數(shù)字查找表從后向前生成十進(jìn)制字符受 Andrei Alexandrescu Fastware 的 fast int2ascii 思路啟發(fā)避免反轉(zhuǎn)結(jié)果浮點(diǎn)如前所述IEEE-754 單/雙精度走 Grisu2to_chars其余走snprintf并做本地化清洗布爾/null分別輸出true/false/nulldiscarded輸出discarded僅在異常內(nèi)部場景出現(xiàn)。整個(gè)序列化過程對流的寫入統(tǒng)一通過output_adapter抽象完成這也是為什么同一個(gè) serializer 既能寫std::string又能直接寫任意std::ostream。單元測試對序列化行為的覆蓋可見 tests/src/unit-serialization.cpp 與 tests/src/unit-unicode*.cpp。版本演進(jìn)小結(jié)dump()及相關(guān)特性的演進(jìn)歷史見 dump API 文檔 的 Version history整理如下1.0.0dump()首次引入3.0.0新增縮進(jìn)字符indent_char、ensure_ascii選項(xiàng)與異常處理并棄用舊式流運(yùn)算符j o4.0.0 將移除請改用o j3.4.0新增錯(cuò)誤處理枚舉error_handler_t3.8.0新增二進(jìn)制值的序列化支持3.12.0支持經(jīng)std::format系列接口格式化 JSON 值受JSON_HAS_STD_FORMAT控制。總結(jié)與延伸閱讀序列化是 nlohmann/json 使用頻率最高的操作之一。掌握dump()的indent/indent_char/ensure_ascii/error_handler四個(gè)參數(shù)、區(qū)分dump()與getstd::string()、正確處理非法 UTF-8 與不可信輸入、理解 NaN/二進(jìn)制值的特殊行為就能在生產(chǎn)環(huán)境中穩(wěn)定、可控地輸出 JSON。如需繼續(xù)深入建議閱讀以下資料dump()序列化為 JSON 字符串operator序列化到輸出流to_string()JSON 指針等類型的字符串化輔助std::formatterbasic_json配合std::format/std::print使用format_as配合 {fmt} 庫使用解析Parsing序列化的逆操作【免費(fèi)下載鏈接】jsonJSON for Modern C項(xiàng)目地址: https://gitcode.com/GitHub_Trending/js/json創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考