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