戰(zhàn)指南)
說(shuō)真的我第一次在代碼里用上 std::format 的時(shí)候腦子里冒出來(lái)的想法不是“語(yǔ)法真漂亮”而是“早該有了”。printf 的年代我還沒(méi)怎么受折磨倒是 operator 那套流式格式化陪了我好多年。直到我真正想給一個(gè)自定義的業(yè)務(wù)結(jié)構(gòu)體加格式化輸出才發(fā)現(xiàn) std::format 的文檔里其實(shí)藏著一條暗線你想讓某個(gè)類型被 {} 格式化不是靠繼承也不是靠寫虛函數(shù)而是去特化 std::formatter。這條路如果沒(méi)摸熟很容易在一串莫名其妙的編譯錯(cuò)誤里打轉(zhuǎn)。這篇文章就圍繞 formatter 特化這件事展開把 parse 和 format 兩個(gè)接口的來(lái)龍去脈講清楚也會(huì)聊聊這種“特化即擴(kuò)展點(diǎn)”的設(shè)計(jì)模式在標(biāo)準(zhǔn)庫(kù)里到底是怎么運(yùn)作的。如果你在寫業(yè)務(wù)代碼看完可以直接把自定義的枚舉、結(jié)構(gòu)體、嵌套對(duì)象接到 std::format 上如果你對(duì)庫(kù)設(shè)計(jì)也有興趣能從這套機(jī)制里看到現(xiàn)代 C 擴(kuò)展點(diǎn)的一種典型形態(tài)。目標(biāo)讀者是已經(jīng)寫過(guò)一點(diǎn) C20、被 std::format 便利性吸引過(guò)、但沒(méi)仔細(xì)研究過(guò)自定義格式化器的人。1. 為什么 std::format 需要自定義格式化器1.1 printf 與 iostream 的舊賬C 語(yǔ)言留下的 printf 家族在 C20 之前幾乎是唯一的“格式化”心智模型?？伤袃蓚€(gè)硬傷類型不安全以及不可擴(kuò)展。類型不安全不用多說(shuō)int 和 double 寫錯(cuò)轉(zhuǎn)換符是編譯器完全不管的事不可擴(kuò)展更難受你想讓一個(gè)自定義的訂單結(jié)構(gòu)體出現(xiàn)在日志里printf 根本給不出一個(gè)干凈的方案。你只能先把它拼成一個(gè)字符串再 %s 打進(jìn)去等于手動(dòng)造序列化。后來(lái)大家轉(zhuǎn)向 iostream用 operator 重載來(lái)定義輸出。這確實(shí)解決了類型安全和基本擴(kuò)展問(wèn)題但代價(jià)是格式狀態(tài)是全局的格式化參數(shù)混在流里比如 std::setw、std::setprecision一旦忘了恢復(fù)就到處傳染。最要命的是性能一條日志輸出可能要多次函數(shù)調(diào)用和緩沖操作。std::format 的價(jià)值就在于格式說(shuō)明集中在一個(gè)字符串里參數(shù)類型編譯期檢查輸出目標(biāo)是輸出迭代器整個(gè)過(guò)程既兼顧了 printf 的緊湊又吸收了類型系統(tǒng)的安全性。1.2 自定義類型格式化的舊方案與新契約先看一個(gè)非常常見的數(shù)據(jù)結(jié)構(gòu)struct Point { int x; int y; };在 iostream 時(shí)代你要么給 Point 寫 operator要么寫一個(gè) to_string 方法。兩者都不是壞方案但問(wèn)題是它們和“格式化”本身是割裂的。比如調(diào)用方想控制寬度和對(duì)齊operator 就得聲明一堆流操縱符或者靠調(diào)用方自己拼。到 std::format 這邊事情變成了另一套契約庫(kù)提供一個(gè)主模板 std::formatterT, CharT默認(rèn)沒(méi)有實(shí)現(xiàn)。用戶為自己的類型特化這個(gè)模板提供兩個(gè)成員函數(shù)parse 和 format。當(dāng) std::format({}, p) 被實(shí)例化時(shí)編譯器自動(dòng)查找 std::formatter 。這套契約最大的好處是格式化能力不再依賴?yán)^承體系也不依賴某個(gè)命名約定模板特化本身就變成了擴(kuò)展點(diǎn)。你不需要修改 Point 的內(nèi)部也不需要 Point 繼承某個(gè) FormatterBase只要在 std 命名空間里給出合法的特化這個(gè)類型就“自動(dòng)”獲得了格式化能力。2. 認(rèn)識(shí)擴(kuò)展點(diǎn)std::formatter 特化的基本骨架2.1 formatter 最簡(jiǎn)單的特化給 Point 寫一個(gè)最簡(jiǎn)特化長(zhǎng)這樣#include format template struct std::formatterPoint { constexpr auto parse(std::format_parse_context ctx) { return ctx.begin(); } auto format(const Point p, std::format_context ctx) const { return std::format_to(ctx.out(), ({}, {}), p.x, p.y); } };這樣一行std::format({}, p)就能輸出(1, 2)。我把完整代碼寫出來(lái)的時(shí)候大部分人會(huì)覺得就這對(duì)就這。但不要急著往下跳parse 這里直接返回 ctx.begin() 只是最省事的寫法它對(duì)“沒(méi)有任何格式說(shuō)明符”的情況有效可一旦用戶寫出{:10}這種說(shuō)明符問(wèn)題就來(lái)了。這個(gè)特化的關(guān)鍵點(diǎn)在于模板參數(shù)是 Point而不是const Point或者Point。標(biāo)準(zhǔn)庫(kù)在查找格式化器時(shí)會(huì)對(duì)類型做 remove_cvref 處理所以特化 formatter 就夠用了。format 方法的第一個(gè)參數(shù)雖然是 const Point但這個(gè) const 是成員函數(shù)約定的一部分特化目標(biāo)類型仍然寫成非 const 的 Point。很多初學(xué)者在這里會(huì)把兩個(gè) const 概念搞混。2.2 parse 和 format 的調(diào)用時(shí)機(jī)與職責(zé)劃分有必要把這兩個(gè)階段的職責(zé)徹底理清因?yàn)檫@是整個(gè)擴(kuò)展點(diǎn)最容易出錯(cuò)的地方。parse 負(fù)責(zé)“解釋格式說(shuō)明符”。當(dāng) std::format 遇到{:10}時(shí)它會(huì)先把格式說(shuō)明符字符串抽出來(lái)構(gòu)造一個(gè) parse context然后調(diào)用 formatter 的 parse。parse 的輸入迭代器指向格式說(shuō)明符的第一個(gè)字符它需要消費(fèi)掉自己認(rèn)識(shí)的字符返回指向第一個(gè)不認(rèn)識(shí)的字符的迭代器。庫(kù)會(huì)檢查這個(gè)返回值如果它沒(méi)有指向}就認(rèn)定格式說(shuō)明非法拋 std::format_error。format 負(fù)責(zé)“真正把對(duì)象寫到輸出迭代器”。它在 parse 之后被調(diào)用此時(shí) formatter 內(nèi)部已經(jīng)保存了解析出來(lái)的各種配置比如寬度、對(duì)齊方式、自定義模式等。format 要做的事情很簡(jiǎn)單根據(jù)這些配置把 T 的內(nèi)容格式化輸出到 ctx.out()。我把這個(gè)過(guò)程類比成一個(gè)小的狀態(tài)機(jī)某個(gè)人先給你一段說(shuō)明你把關(guān)鍵信息記在心里然后對(duì)象遞到你面前你按照記住的說(shuō)明把它寫在紙上。parse 是“讀說(shuō)明”format 是“寫對(duì)象”。兩者通過(guò) formatter 對(duì)象的成員變量共享狀態(tài)所以 parse 必須保證所有被支持的格式說(shuō)明都要被正確處理否則 format 階段拿到的狀態(tài)就是殘缺的。還有一個(gè)細(xì)節(jié)是 parse 最好寫成 constexpr。標(biāo)準(zhǔn)庫(kù)實(shí)現(xiàn)里對(duì)格式字符串的編譯期檢查往往就是在常量表達(dá)式環(huán)境中調(diào)用 parse 來(lái)做到的。雖然寫不寫 constexpr 在很多場(chǎng)景下都能編譯通過(guò)但主流實(shí)現(xiàn)都傾向于要求它可被常量求值所以新手直接加上 constexpr 是穩(wěn)妥習(xí)慣。2.3 寬字符形式的擴(kuò)展點(diǎn)std::format 有兩套基本格式字符串char 和 wchar_t。對(duì)應(yīng)地formatter 的第二個(gè)模板參數(shù) CharT 默認(rèn)是 char。如果你希望定義的類型能被std::format(L{}, p)支持就需要再特化一個(gè) formatterPoint, wchar_ttemplate struct std::formatterPoint, wchar_t { constexpr auto parse(std::wformat_parse_context ctx) { return ctx.begin(); } auto format(const Point p, std::wformat_context ctx) const { return std::format_to(ctx.out(), L({}, {}), p.x, p.y); } };我實(shí)際遇到的業(yè)務(wù)場(chǎng)景里窄字符格式基本夠用但有幾次要給 Windows 下的日志接口喂寬字符字符串補(bǔ)特化就不可避免。如果只有 char 特化編譯器會(huì)給出一個(gè)特別長(zhǎng)的報(bào)錯(cuò)核心意思是“formatterPoint, wchar_t 不完整”。這時(shí)候別慌照著窄字符的版本補(bǔ)一個(gè)就完事。要注意的是wformat_parse_context 和 wformat_context 的別名都要從 wchar_t 版本拿別混著用。3. 讓格式化器讀懂格式說(shuō)明parse 的實(shí)現(xiàn)細(xì)節(jié)3.1 格式說(shuō)明符到底包含什么標(biāo)準(zhǔn)格式說(shuō)明符的完整語(yǔ)法是[[fill]align][sign][#][0][width][.precision][type]fill 是任意字符align 是、、^sign 是、-、空格width 是一串?dāng)?shù)字precision 是小數(shù)點(diǎn)加數(shù)字type 是字母。對(duì)自定義類型來(lái)說(shuō)標(biāo)準(zhǔn)允許你定義自己的一組 type 字符其他部分如果能解析則通常意味著你需要支持它們。這帶來(lái)一個(gè)很微妙的點(diǎn)如果你的 parse 只認(rèn)識(shí) type 字符c而用戶寫了{(lán):c10}即寬度 10、左對(duì)齊、類型字符 c那么你要么完整消費(fèi)掉這些標(biāo)準(zhǔn)語(yǔ)法要么明確拋異常。直接return ctx.begin()等于假裝什么都沒(méi)看見庫(kù)會(huì)認(rèn)為格式說(shuō)明里還有殘留字符最終照樣拋異常而且拋錯(cuò)的位置還不在你的代碼里排查起來(lái)非常費(fèi)勁。3.2 手動(dòng)解析一個(gè)完整例子為了看透 parse 的工作機(jī)制我寫一個(gè)帶自定義 type 和寬度的手動(dòng)解析版本。假設(shè) Point 支持p表示圓括號(hào)風(fēng)格、b表示方括號(hào)風(fēng)格并且只接受純數(shù)字寬度template struct std::formatterPoint { char style p; int width 0; constexpr auto parse(std::format_parse_context ctx) { auto it ctx.begin(); if (it ctx.end() || *it }) { return it; } if (*it p || *it b) { style *it; it; } if (it ctx.end() || *it }) { return it; } int w 0; while (it ! ctx.end() *it 0 *it 9) { w w * 10 (*it - 0); it; } if (it ! ctx.end() *it ! }) { throw std::format_error(Point 不支持該格式說(shuō)明); } width w; return it; } auto format(const Point p, std::format_context ctx) const { std::string body; if (style p) { body std::format(({}, {}), p.x, p.y); } else { body std::format([{}, {}], p.x, p.y); } if (width 0) { return std::format_to(ctx.out(), {}, body); } int pad width - static_castint(body.size()); if (pad 0) { return std::format_to(ctx.out(), {}, body); } return std::format_to(ctx.out(), {}{}, std::string(pad, ), body); } };parse 的消費(fèi)順序是先認(rèn) type 字符再認(rèn)寬度最后檢查是否已經(jīng)到了}。如果還有多余的字符直接拋 std::format_error。這個(gè)版本雖然簡(jiǎn)單但它是完整可編譯的能正確處理{:p10}這種說(shuō)明。注意我偷懶只處理了右對(duì)齊填充空格如果要做左對(duì)齊或居中對(duì)齊就得再解析 align 字符。我特別想提醒一件事手寫 parse 看起來(lái)并不難但它是一個(gè)典型的“邊界條件地獄”。你幾乎肯定會(huì)在某個(gè)細(xì)節(jié)上忘記處理比如 width 溢出、fill 后面沒(méi)有 align、出現(xiàn)在沒(méi)有 width 的位置等。標(biāo)準(zhǔn)庫(kù)給每個(gè)內(nèi)置類型都做了完整解析你沒(méi)必要為自定義類型再造一套輪子。這也是很多資深開發(fā)者最后都走向內(nèi)部復(fù)用標(biāo)準(zhǔn) formatter 的原因。3.3 復(fù)用標(biāo)準(zhǔn) formatter 的正確姿勢(shì)假設(shè)你有一個(gè) Person 類想讓它支持所有標(biāo)準(zhǔn)字符串格式化選項(xiàng)寬度、對(duì)齊、填充、截?cái)?。最聰明的辦法不是自己實(shí)現(xiàn)對(duì)齊邏輯而是讓 std::formatter std::string 替你干這些活template struct std::formatterPerson { std::formatterstd::string inner; constexpr auto parse(std::format_parse_context ctx) { return inner.parse(ctx); } auto format(const Person p, std::format_context ctx) const { return inner.format(p.name ( std::to_string(p.age) ), ctx); } };這個(gè)技巧是我在實(shí)際項(xiàng)目里反復(fù)用到的。它把一個(gè)自定義類型的格式化完全委托給字符串格式化器外部傳入的{:20}、{:.10}都會(huì)自動(dòng)生效而 inner 的 parse 已經(jīng)按照標(biāo)準(zhǔn)語(yǔ)法把所有邊界情況處理完了。你唯一要負(fù)責(zé)的就是決定這個(gè)對(duì)象變成什么樣的字符串文本。代價(jià)是很小的format 階段多一次字符串臨時(shí)對(duì)象的構(gòu)造和拷貝。對(duì)日志序列化這種場(chǎng)景來(lái)說(shuō)性能完全夠用。如果你對(duì)性能極端敏感非要避免臨時(shí)字符串那就只能手動(dòng)解析寬度和對(duì)齊并在 format 里直接用輸出迭代器寫字符比如用 format_to 把 x、分隔符、y 分段寫入。我個(gè)人的經(jīng)驗(yàn)是先寫清晰的委托版本性能分析真的指出熱點(diǎn)之后再把內(nèi)層替換成手寫路徑不要一開始就炫技。還有一個(gè)變體值得說(shuō)當(dāng)你想在同一類型里支持多種風(fēng)格說(shuō)明時(shí)可以繼續(xù)在這個(gè)內(nèi)部 formatter 之上加一個(gè)自己的 type 狀態(tài)。例如前面那個(gè) Point 的p/b風(fēng)格仍可以保留一個(gè) inner 來(lái)負(fù)責(zé)寬度對(duì)齊只額外解析一個(gè) type 字符。這樣 parse 的主邏輯是“先看一個(gè)字符是不是 p/b再把這個(gè) format 交給 inner 處理”代碼量比純手寫少很多也不會(huì)丟標(biāo)準(zhǔn)能力。4. 特化型擴(kuò)展點(diǎn)設(shè)計(jì)模式4.1 標(biāo)準(zhǔn)庫(kù)里的“特化即擴(kuò)展”家族std::formatter 并不是 C 標(biāo)準(zhǔn)庫(kù)里第一個(gè)使用模板特化做擴(kuò)展點(diǎn)的模板。前面還有 std::hash、std::char_traits、std::allocator、std::numeric_limits。它們共享一個(gè)核心思路主模板給出通用約定或留下未定義狀態(tài)用戶通過(guò)全特化或偏特化把自己的類型“注入”進(jìn)標(biāo)準(zhǔn)算法/容器/工具中。我對(duì)它們的理解是這類擴(kuò)展點(diǎn)的通配符就是“模板參數(shù)本身”。庫(kù)不需要知道你的類型長(zhǎng)什么樣它只知道存在一個(gè) formatter 于是它愿意在格式化流程中調(diào)用它它也不知道你的類型怎么算 hash但 std::unordered_map 會(huì)調(diào)用 std::hash 。類型成了庫(kù)和用戶之間的一枚鑰匙鑰匙齒形正確大門就自動(dòng)打開。這和定制點(diǎn)對(duì)象customization point object不一樣。定制點(diǎn)對(duì)象的核心是 ADL比如 std::ranges::begin 會(huì)在調(diào)用時(shí)去找用戶提供的成員 begin 或自由 begin 函數(shù)。formatter 不走 ADL它走“依賴類型參數(shù)的模板實(shí)例化”。兩種風(fēng)格各有用處但 formatter 用特化是更合適的原因在于格式化需要 parse 和 format 兩個(gè)階段共享狀態(tài)而不只是一個(gè)函數(shù)調(diào)用。4.2 特化比繼承和重載好在哪我見過(guò)不少庫(kù)喜歡給一組類型提供一個(gè)基類然后讓大家繼承并重寫虛函數(shù)來(lái)格式化。這在一個(gè)封閉的代碼庫(kù)里能跑通但一旦要接入第三方類型或者你的類型本來(lái)就沒(méi)有繼承關(guān)系的自由虛函數(shù)方案就直接卡殼。繼承還必然帶來(lái)動(dòng)態(tài)分派和堆分配對(duì) value semantics 極不友好。模板特化把這些麻煩全部繞過(guò)非侵入Point 完全可以是一個(gè)聚合類型連成員函數(shù)都不用加。值語(yǔ)義formatter 本身就是一個(gè)普通對(duì)象可以被拷貝、存放在任何容器里。編譯期可知std::format 可以推導(dǎo)出每個(gè)參數(shù)是否可格式化錯(cuò)誤在編譯期暴露。零繼承負(fù)擔(dān)沒(méi)有虛表沒(méi)有基類沒(méi)有運(yùn)行時(shí)類型信息。再用一個(gè)實(shí)際項(xiàng)目里的例子來(lái)說(shuō)我所在的團(tuán)隊(duì)維護(hù)著一個(gè)底層通訊庫(kù)里面有一堆消息結(jié)構(gòu)體每個(gè)結(jié)構(gòu)體都是純數(shù)據(jù)的聚合類型。我們不可能讓它們繼承某個(gè)公共格式化基類那會(huì)污染整個(gè)類設(shè)計(jì)。于是我們就在各自的消息類型旁邊放一個(gè) formatter 特化把協(xié)議字段的調(diào)試信息整理成可讀文本改動(dòng)面非常小也完全不碰消息類的內(nèi)部邏輯。4.3 與 concept 和定制點(diǎn)對(duì)象的配合C20 的 format 系列函數(shù)里對(duì)參數(shù)可格式化性的檢查并不是一個(gè)公開概念。到 C23標(biāo)準(zhǔn)給出了 std::formattable 概念它本質(zhì)上要求存在 std::formatterremove_cvref_t , CharT這個(gè) formatter 滿足 semiregular它能解析格式說(shuō)明它能格式化 T 的對(duì)象。換句話說(shuō)formattable 就是把“你有沒(méi)有特化過(guò) formatter”這個(gè)事實(shí)翻譯成一個(gè)可被約束檢查的表達(dá)式。你寫的特化只要滿足接口要求就會(huì)被自動(dòng)納入這套概念體系。如果想在自定義泛型函數(shù)里約束“某類型可被格式化”可以這樣做template typename T concept MyFormattable requires(const T v, std::format_context ctx) { typename std::formatterstd::remove_cvref_tT; std::formatterstd::remove_cvref_tT{}.format(v, ctx); };有了概念之后你可以在自己的代碼里寫出“只有可格式化的類型才能進(jìn)入日志系統(tǒng)”這樣的泛型約束。這是模板特化擴(kuò)展點(diǎn)和現(xiàn)代約束機(jī)制結(jié)合得很自然的地方特化是“提供實(shí)現(xiàn)”概念是“檢查是否提供實(shí)現(xiàn)”。我給一個(gè)我對(duì)這套模式的體感總結(jié)formatter 的擴(kuò)展點(diǎn)是“被動(dòng)型”的它不像 Python 那種鴨子類型運(yùn)行時(shí)詢問(wèn)“你行不行”而是在編譯期就把這件事釘死。你能從一個(gè)類型有沒(méi)有可用的 formatter 特化直接推斷它能不能被 {} 消費(fèi)這種確定性是運(yùn)行時(shí)分派給不了的。5. 實(shí)戰(zhàn)業(yè)務(wù)結(jié)構(gòu)體的多風(fēng)格格式化5.1 需求讓一個(gè)訂單結(jié)構(gòu)出現(xiàn)在日志里之前一個(gè)模擬項(xiàng)目里我需要把一個(gè)訂單結(jié)構(gòu)體打印到日志、調(diào)試輸出和導(dǎo)出文件里。三種場(chǎng)景想看到的內(nèi)容不太一樣日志里希望簡(jiǎn)潔A1001 | 199.00 | paid調(diào)試輸出希望路徑可讀比如包含字段名idA1001, amount199.00, statuspaid導(dǎo)出文件需要 CSVA1001,199.00,paid如果給 operator 實(shí)現(xiàn)你要不是寫三個(gè)重載要不就得靠調(diào)用方臨時(shí)改變流狀態(tài)。而用 formatter 特化我可以讓格式說(shuō)明符里的 type 字符來(lái)決定輸出風(fēng)格。5.2 實(shí)現(xiàn)一個(gè)帶格式“模式”的 Order formatter先定義簡(jiǎn)單結(jié)構(gòu)struct Order { std::string id; double amount; bool paid; };然后特化 formattertemplate struct std::formatterOrder { char mode 0; constexpr auto parse(std::format_parse_context ctx) { auto it ctx.begin(); if (it ctx.end() || *it }) { return it; } if (*it d || *it v || *it c) { mode *it; it; } if (it ! ctx.end() *it ! }) { throw std::format_error(Order 僅支持 d/v/c 格式模式); } return it; } auto format(const Order o, std::format_context ctx) const { std::string status o.paid ? paid : unpaid; switch (mode) { case d: return std::format_to(ctx.out(), {} | {:.2f} | {}, o.id, o.amount, status); case v: return std::format_to(ctx.out(), id{}, amount{:.2f}, status{}, o.id, o.amount, status); case c: return std::format_to(ctx.out(), {},{:.2f},{}, o.id, o.amount, status); default: return std::format_to(ctx.out(), {} | {:.2f} | {}, o.id, o.amount, status); } } };這樣調(diào)用起來(lái)非常直觀std::format({:d}, order); // A1001 | 199.00 | paid std::format({:v}, order); // idA1001, amount199.00, statuspaid std::format({:c}, order); // A1001,199.00,paid std::format({}, order); // 默認(rèn)走 d 風(fēng)格parse 里我消費(fèi)了 type 字符 d/v/c也檢查了后續(xù)直到}之間沒(méi)有多余內(nèi)容。這個(gè)實(shí)現(xiàn)不處理寬度、對(duì)齊等標(biāo)準(zhǔn)說(shuō)明符。如果實(shí)際項(xiàng)目需要日志列對(duì)齊我更傾向在上面 3.3 節(jié)說(shuō)的內(nèi)部 formatter 基礎(chǔ)上再加 mode也就是先解析 mode再把剩余說(shuō)明符委托給 std::formatter std::string 。這個(gè)設(shè)計(jì)讓“格式化”和“業(yè)務(wù)對(duì)象的序列化”保持在同一個(gè)位置而不是散落在各個(gè)調(diào)用點(diǎn)。團(tuán)隊(duì)里其他人只需要看這個(gè)特化就能知道 Order 能支持哪些輸出模式。5.3 嵌套 variant 和編譯期分派業(yè)務(wù)數(shù)據(jù)里經(jīng)常出現(xiàn)字段是可變的類型比如一個(gè)配置值可能是整數(shù)、浮點(diǎn)、字符串或者空。C 里最干凈的表達(dá)是 std::variant。如果直接在 formatter 里寫分支往往就會(huì)用到 std::visit 配合 if constexpr 做編譯期分派struct Value { std::variantstd::monostate, int, double, std::string v; }; template struct std::formatterValue { constexpr auto parse(std::format_parse_context ctx) { return ctx.begin(); } auto format(const Value val, std::format_context ctx) const { return std::visit([](const auto x) - std::format_context::iterator { using T std::remove_cvref_tdecltype(x); if constexpr (std::is_same_vT, std::monostate) { return std::format_to(ctx.out(), null); } else if constexpr (std::is_same_vT, int) { return std::format_to(ctx.out(), {}, x); } else if constexpr (std::is_same_vT, double) { return std::format_to(ctx.out(), {:.2f}, x); } else { return std::format_to(ctx.out(), \{}\, x); } }, val.v); } };這里 std::visit 是運(yùn)行時(shí)的變體分派而 if constexpr 是編譯期的類型條件。兩者疊加起來(lái)每個(gè) variant 可能攜帶的類型都在編譯期被展開成一段專門的格式化代碼。輸出效果類似 JSON 風(fēng)格的null、42、3.14、hello。這種做法非常能體現(xiàn) formatter 作為擴(kuò)展點(diǎn)的組合能力你不需要讓 variant 內(nèi)部元素各自實(shí)現(xiàn)什么接口只要它們本身是可格式化的外面套一層編譯期分派就能繼續(xù)遞歸工作。6. 常見問(wèn)題與編譯報(bào)錯(cuò)實(shí)錄6.1 特化放錯(cuò)命名空間寫自定義 formatter 最容易犯的第一個(gè)錯(cuò)誤是忘記把模板特化放進(jìn) std 命名空間。如果你在全局命名空間這樣寫template struct std::formatterPoint { ... };這其實(shí)是合法的前提是你顯式用了std::修飾。但如果你圖省事在全局命名空間寫template struct formatterPoint { ... };編譯器會(huì)把 formatter 當(dāng)成全局的自定義模板和標(biāo)準(zhǔn)庫(kù)的 formatter 沒(méi)有任何關(guān)系。std::format 在實(shí)例化時(shí)尋找的是 std::formatter 自然找不到。報(bào)錯(cuò)通常是一長(zhǎng)串“no type named formatter in std”或者類似的信息。我建議在代碼里寫成template struct std::formatterPoint { ... };幾乎所有主流實(shí)現(xiàn)都接受這種寫法語(yǔ)義清晰。有些老一點(diǎn)的編譯器或者特殊環(huán)境也可能要求你把它包裹在namespace std { ... }里那種寫法也完全沒(méi)問(wèn)題。6.2 parse 消費(fèi)了格式說(shuō)明卻仍報(bào)錯(cuò)第二個(gè)高頻坑是你在 parse 里明明處理了格式說(shuō)明但運(yùn)行程序時(shí) std::format 依然拋 std::format_error。這個(gè)問(wèn)題的根源往往是返回值沒(méi)有停在}之前。舉個(gè)例子你為了解析 type 字符做了it但沒(méi)有檢查此時(shí) it 是否已經(jīng)指向}然后直接返回 it。如果用戶寫的是{:p}且你只消費(fèi)了 p此時(shí) it 指向}那沒(méi)問(wèn)題但如果你把}也當(dāng)成可消費(fèi)字符往前挪了一步返回的迭代器位置就不對(duì)了。判斷標(biāo)準(zhǔn)很簡(jiǎn)單parse 返回的迭代器必須指向}或者指向格式字符串的末尾空說(shuō)明符的情況。一旦返回位置停在不該停的地方上層格式化函數(shù)就會(huì)認(rèn)為有未識(shí)別的說(shuō)明符于是拋異常。排查時(shí)我習(xí)慣在 parse 里故意打印或斷點(diǎn)觀察 it 的值一眼就能看出是不是消費(fèi)過(guò)頭了。另一個(gè)相關(guān)坑parse 里檢查了某種情況并拋 std::format_error但異常被某個(gè)更外層的字符串格式化邏輯僥幸吞掉了導(dǎo)致你看到的行為很奇怪。這種情況通常出現(xiàn)在嵌套格式化內(nèi)部比如你在一個(gè) formatter 的 format 里又調(diào)用 std::format 格式化一個(gè)內(nèi)部類型內(nèi)部類型拋出的異常需要被異常處理邏輯捕獲。避免的辦法是不要在任何 format 階段去捕獲解析階段的異常讓異常自然向上傳播。6.3 輸出迭代器與臨時(shí)緩沖區(qū)的坑format 返回的是輸出迭代器正常使用時(shí)我們幾乎從不檢查它。但如果你在 formatter 的 format 內(nèi)部維護(hù)了一個(gè)臨時(shí) buffer就可能出現(xiàn)迭代器失效問(wèn)題。就拿 3.3 那節(jié)委托給 std::formatter std::string 的例子來(lái)說(shuō)inner.format 接收的 std::string 是我們臨時(shí)拼出來(lái)的它在函數(shù)返回后就銷毀了但返回的迭代器已經(jīng)被妥善寫入了 ctx.out()所以問(wèn)題不大。真正要小心的是你自己保存 ctx.out() 的迭代器然后在循環(huán)里反復(fù)寫。某些輸出迭代器是單遍的拷貝之后再寫入行為未必符合直覺。我用過(guò)幾條實(shí)用規(guī)則每條路徑只調(diào)用一次 ctx.out()然后一路用完。不要在多個(gè)分支里分別拿 ctx.out() 并交叉使用。如果確實(shí)需要先構(gòu)造完整字符串再統(tǒng)一寫出去那就一次 format_to 搞定不要分多次寫。6.4 和 operator 共存不少代碼庫(kù)既有 operator又要接入 std::format。最直接的做法是在 operator 里調(diào)用 std::formatstd::ostream operator(std::ostream os, const Order o) { return os std::format({}, o); }這樣二者輸出的效果完全一致還避免了重復(fù)實(shí)現(xiàn)。但要注意一個(gè)問(wèn)題包含 的編譯單元會(huì)顯著增加編譯時(shí)間。如果 operator 所在的頭文件被大量 include整個(gè)項(xiàng)目的編譯成本容易上升。我的做法是把 operator 的實(shí)現(xiàn)放 .cpp 文件或者單獨(dú)用一個(gè)頭文件存放所有自定義 formatter 特化只在需要格式化的地方 include。還有一個(gè)關(guān)于可見性的問(wèn)題formatter 特化和 operator 一樣必須在“調(diào)用 std::format 的那個(gè)翻譯單元”可見。如果你把特化放在某個(gè)靜態(tài)庫(kù)的 .cpp 內(nèi)部調(diào)用方看不到特化編譯器就會(huì)認(rèn)為類型不可格式化。解決方案很簡(jiǎn)單把特化放到一個(gè)頭文件里跟類型聲明放一起保證任何看到類型的地方都能看到特化。最后分享兩個(gè)實(shí)操細(xì)節(jié)在收尾之前我還想講兩個(gè)從實(shí)際項(xiàng)目里悟到的細(xì)節(jié)。第一個(gè)是關(guān)于“不要在 format 里過(guò)度拼接中間字符串”。我見過(guò)有人把 formatter 的 format 寫成auto format(const Order o, std::format_context ctx) const { std::string tmp o.id | std::to_string(o.amount) | std::to_string(o.paid); return std::format_to(ctx.out(), {}, tmp); }這當(dāng)然能跑但對(duì)性能不友好。如果這個(gè) formatter 用在每秒鐘上萬(wàn)條的日志路徑上建議改成直接 std::format_to(ctx.out(), {} | {:.2f} | {}, ...)讓數(shù)據(jù)直接流向輸出迭代器省掉中間字符串。先寫清晰版本熱點(diǎn)明確后性能優(yōu)化通常只需要改 formatter 內(nèi)部對(duì)外調(diào)用方完全無(wú)感這本身就是這套擴(kuò)展點(diǎn)設(shè)計(jì)給維護(hù)者留下的余地。第二個(gè)細(xì)節(jié)是當(dāng)你想讓自定義類型支持{:?}這種格式類型時(shí)不要害怕在 parse 里拋 std::format_error。有些人過(guò)度擔(dān)心異常會(huì)破壞格式化的優(yōu)雅性但 std::format 明確用異常來(lái)表示格式字符串非法這是接口約定的一部分。你認(rèn)真拋異常用戶才能第一時(shí)間看到錯(cuò)誤說(shuō)明這比返回一個(gè)錯(cuò)位的迭代器讓庫(kù)拋出含糊錯(cuò)誤要友好得多。C 的 std::format 這套擴(kuò)展點(diǎn)表面上是幾個(gè)成員函數(shù)的組合骨子里卻是“模板特化即開放接口”的現(xiàn)代 C 設(shè)計(jì)思路。你一旦習(xí)慣了用 formatter 去表達(dá)一個(gè)類型的多個(gè)輸出視圖會(huì)發(fā)現(xiàn)它能替代掉不少過(guò)去靠流操縱符和序列化函數(shù)拼接才能做到的事。這篇文章寫到的代碼都來(lái)自我用過(guò)的真實(shí)場(chǎng)景至少在我的項(xiàng)目里它們已經(jīng)穩(wěn)定跑了好一陣。如果你也正在給某個(gè)自定義類型接 std::format希望讀完這篇能少走幾步彎路直接寫出自己真正需要的特化。 std::format自定義格式化器：formatter特化與實(shí)戰(zhàn)指南
說(shuō)真的我第一次在代碼里用上 std::format 的時(shí)候腦子里冒出來(lái)的想法不是“語(yǔ)法真漂亮”而是“早該有了”。printf 的年代我還沒(méi)怎么受折磨倒是 operator 那套流式格式化陪了我好多年。直到我真正想給一個(gè)自定義的業(yè)務(wù)結(jié)構(gòu)體加格式化輸出才發(fā)現(xiàn) std::format 的文檔里其實(shí)藏著一條暗線你想讓某個(gè)類型被 {} 格式化不是靠繼承也不是靠寫虛函數(shù)而是去特化 std::formatter。這條路如果沒(méi)摸熟很容易在一串莫名其妙的編譯錯(cuò)誤里打轉(zhuǎn)。這篇文章就圍繞 formatter 特化這件事展開把 parse 和 format 兩個(gè)接口的來(lái)龍去脈講清楚也會(huì)聊聊這種“特化即擴(kuò)展點(diǎn)”的設(shè)計(jì)模式在標(biāo)準(zhǔn)庫(kù)里到底是怎么運(yùn)作的。如果你在寫業(yè)務(wù)代碼看完可以直接把自定義的枚舉、結(jié)構(gòu)體、嵌套對(duì)象接到 std::format 上如果你對(duì)庫(kù)設(shè)計(jì)也有興趣能從這套機(jī)制里看到現(xiàn)代 C 擴(kuò)展點(diǎn)的一種典型形態(tài)。目標(biāo)讀者是已經(jīng)寫過(guò)一點(diǎn) C20、被 std::format 便利性吸引過(guò)、但沒(méi)仔細(xì)研究過(guò)自定義格式化器的人。1. 為什么 std::format 需要自定義格式化器1.1 printf 與 iostream 的舊賬C 語(yǔ)言留下的 printf 家族在 C20 之前幾乎是唯一的“格式化”心智模型?？伤袃蓚€(gè)硬傷類型不安全以及不可擴(kuò)展。類型不安全不用多說(shuō)int 和 double 寫錯(cuò)轉(zhuǎn)換符是編譯器完全不管的事不可擴(kuò)展更難受你想讓一個(gè)自定義的訂單結(jié)構(gòu)體出現(xiàn)在日志里printf 根本給不出一個(gè)干凈的方案。你只能先把它拼成一個(gè)字符串再 %s 打進(jìn)去等于手動(dòng)造序列化。后來(lái)大家轉(zhuǎn)向 iostream用 operator 重載來(lái)定義輸出。這確實(shí)解決了類型安全和基本擴(kuò)展問(wèn)題但代價(jià)是格式狀態(tài)是全局的格式化參數(shù)混在流里比如 std::setw、std::setprecision一旦忘了恢復(fù)就到處傳染。最要命的是性能一條日志輸出可能要多次函數(shù)調(diào)用和緩沖操作。std::format 的價(jià)值就在于格式說(shuō)明集中在一個(gè)字符串里參數(shù)類型編譯期檢查輸出目標(biāo)是輸出迭代器整個(gè)過(guò)程既兼顧了 printf 的緊湊又吸收了類型系統(tǒng)的安全性。1.2 自定義類型格式化的舊方案與新契約先看一個(gè)非常常見的數(shù)據(jù)結(jié)構(gòu)struct Point { int x; int y; };在 iostream 時(shí)代你要么給 Point 寫 operator要么寫一個(gè) to_string 方法。兩者都不是壞方案但問(wèn)題是它們和“格式化”本身是割裂的。比如調(diào)用方想控制寬度和對(duì)齊operator 就得聲明一堆流操縱符或者靠調(diào)用方自己拼。到 std::format 這邊事情變成了另一套契約庫(kù)提供一個(gè)主模板 std::formatterT, CharT默認(rèn)沒(méi)有實(shí)現(xiàn)。用戶為自己的類型特化這個(gè)模板提供兩個(gè)成員函數(shù)parse 和 format。當(dāng) std::format({}, p) 被實(shí)例化時(shí)編譯器自動(dòng)查找 std::formatter 。這套契約最大的好處是格式化能力不再依賴?yán)^承體系也不依賴某個(gè)命名約定模板特化本身就變成了擴(kuò)展點(diǎn)。你不需要修改 Point 的內(nèi)部也不需要 Point 繼承某個(gè) FormatterBase只要在 std 命名空間里給出合法的特化這個(gè)類型就“自動(dòng)”獲得了格式化能力。2. 認(rèn)識(shí)擴(kuò)展點(diǎn)std::formatter 特化的基本骨架2.1 formatter 最簡(jiǎn)單的特化給 Point 寫一個(gè)最簡(jiǎn)特化長(zhǎng)這樣#include format template struct std::formatterPoint { constexpr auto parse(std::format_parse_context ctx) { return ctx.begin(); } auto format(const Point p, std::format_context ctx) const { return std::format_to(ctx.out(), ({}, {}), p.x, p.y); } };這樣一行std::format({}, p)就能輸出(1, 2)。我把完整代碼寫出來(lái)的時(shí)候大部分人會(huì)覺得就這對(duì)就這。但不要急著往下跳parse 這里直接返回 ctx.begin() 只是最省事的寫法它對(duì)“沒(méi)有任何格式說(shuō)明符”的情況有效可一旦用戶寫出{:10}這種說(shuō)明符問(wèn)題就來(lái)了。這個(gè)特化的關(guān)鍵點(diǎn)在于模板參數(shù)是 Point而不是const Point或者Point。標(biāo)準(zhǔn)庫(kù)在查找格式化器時(shí)會(huì)對(duì)類型做 remove_cvref 處理所以特化 formatter 就夠用了。format 方法的第一個(gè)參數(shù)雖然是 const Point但這個(gè) const 是成員函數(shù)約定的一部分特化目標(biāo)類型仍然寫成非 const 的 Point。很多初學(xué)者在這里會(huì)把兩個(gè) const 概念搞混。2.2 parse 和 format 的調(diào)用時(shí)機(jī)與職責(zé)劃分有必要把這兩個(gè)階段的職責(zé)徹底理清因?yàn)檫@是整個(gè)擴(kuò)展點(diǎn)最容易出錯(cuò)的地方。parse 負(fù)責(zé)“解釋格式說(shuō)明符”。當(dāng) std::format 遇到{:10}時(shí)它會(huì)先把格式說(shuō)明符字符串抽出來(lái)構(gòu)造一個(gè) parse context然后調(diào)用 formatter 的 parse。parse 的輸入迭代器指向格式說(shuō)明符的第一個(gè)字符它需要消費(fèi)掉自己認(rèn)識(shí)的字符返回指向第一個(gè)不認(rèn)識(shí)的字符的迭代器。庫(kù)會(huì)檢查這個(gè)返回值如果它沒(méi)有指向}就認(rèn)定格式說(shuō)明非法拋 std::format_error。format 負(fù)責(zé)“真正把對(duì)象寫到輸出迭代器”。它在 parse 之后被調(diào)用此時(shí) formatter 內(nèi)部已經(jīng)保存了解析出來(lái)的各種配置比如寬度、對(duì)齊方式、自定義模式等。format 要做的事情很簡(jiǎn)單根據(jù)這些配置把 T 的內(nèi)容格式化輸出到 ctx.out()。我把這個(gè)過(guò)程類比成一個(gè)小的狀態(tài)機(jī)某個(gè)人先給你一段說(shuō)明你把關(guān)鍵信息記在心里然后對(duì)象遞到你面前你按照記住的說(shuō)明把它寫在紙上。parse 是“讀說(shuō)明”format 是“寫對(duì)象”。兩者通過(guò) formatter 對(duì)象的成員變量共享狀態(tài)所以 parse 必須保證所有被支持的格式說(shuō)明都要被正確處理否則 format 階段拿到的狀態(tài)就是殘缺的。還有一個(gè)細(xì)節(jié)是 parse 最好寫成 constexpr。標(biāo)準(zhǔn)庫(kù)實(shí)現(xiàn)里對(duì)格式字符串的編譯期檢查往往就是在常量表達(dá)式環(huán)境中調(diào)用 parse 來(lái)做到的。雖然寫不寫 constexpr 在很多場(chǎng)景下都能編譯通過(guò)但主流實(shí)現(xiàn)都傾向于要求它可被常量求值所以新手直接加上 constexpr 是穩(wěn)妥習(xí)慣。2.3 寬字符形式的擴(kuò)展點(diǎn)std::format 有兩套基本格式字符串char 和 wchar_t。對(duì)應(yīng)地formatter 的第二個(gè)模板參數(shù) CharT 默認(rèn)是 char。如果你希望定義的類型能被std::format(L{}, p)支持就需要再特化一個(gè) formatterPoint, wchar_ttemplate struct std::formatterPoint, wchar_t { constexpr auto parse(std::wformat_parse_context ctx) { return ctx.begin(); } auto format(const Point p, std::wformat_context ctx) const { return std::format_to(ctx.out(), L({}, {}), p.x, p.y); } };我實(shí)際遇到的業(yè)務(wù)場(chǎng)景里窄字符格式基本夠用但有幾次要給 Windows 下的日志接口喂寬字符字符串補(bǔ)特化就不可避免。如果只有 char 特化編譯器會(huì)給出一個(gè)特別長(zhǎng)的報(bào)錯(cuò)核心意思是“formatterPoint, wchar_t 不完整”。這時(shí)候別慌照著窄字符的版本補(bǔ)一個(gè)就完事。要注意的是wformat_parse_context 和 wformat_context 的別名都要從 wchar_t 版本拿別混著用。3. 讓格式化器讀懂格式說(shuō)明parse 的實(shí)現(xiàn)細(xì)節(jié)3.1 格式說(shuō)明符到底包含什么標(biāo)準(zhǔn)格式說(shuō)明符的完整語(yǔ)法是[[fill]align][sign][#][0][width][.precision][type]fill 是任意字符align 是、、^sign 是、-、空格width 是一串?dāng)?shù)字precision 是小數(shù)點(diǎn)加數(shù)字type 是字母。對(duì)自定義類型來(lái)說(shuō)標(biāo)準(zhǔn)允許你定義自己的一組 type 字符其他部分如果能解析則通常意味著你需要支持它們。這帶來(lái)一個(gè)很微妙的點(diǎn)如果你的 parse 只認(rèn)識(shí) type 字符c而用戶寫了{(lán):c10}即寬度 10、左對(duì)齊、類型字符 c那么你要么完整消費(fèi)掉這些標(biāo)準(zhǔn)語(yǔ)法要么明確拋異常。直接return ctx.begin()等于假裝什么都沒(méi)看見庫(kù)會(huì)認(rèn)為格式說(shuō)明里還有殘留字符最終照樣拋異常而且拋錯(cuò)的位置還不在你的代碼里排查起來(lái)非常費(fèi)勁。3.2 手動(dòng)解析一個(gè)完整例子為了看透 parse 的工作機(jī)制我寫一個(gè)帶自定義 type 和寬度的手動(dòng)解析版本。假設(shè) Point 支持p表示圓括號(hào)風(fēng)格、b表示方括號(hào)風(fēng)格并且只接受純數(shù)字寬度template struct std::formatterPoint { char style p; int width 0; constexpr auto parse(std::format_parse_context ctx) { auto it ctx.begin(); if (it ctx.end() || *it }) { return it; } if (*it p || *it b) { style *it; it; } if (it ctx.end() || *it }) { return it; } int w 0; while (it ! ctx.end() *it 0 *it 9) { w w * 10 (*it - 0); it; } if (it ! ctx.end() *it ! }) { throw std::format_error(Point 不支持該格式說(shuō)明); } width w; return it; } auto format(const Point p, std::format_context ctx) const { std::string body; if (style p) { body std::format(({}, {}), p.x, p.y); } else { body std::format([{}, {}], p.x, p.y); } if (width 0) { return std::format_to(ctx.out(), {}, body); } int pad width - static_castint(body.size()); if (pad 0) { return std::format_to(ctx.out(), {}, body); } return std::format_to(ctx.out(), {}{}, std::string(pad, ), body); } };parse 的消費(fèi)順序是先認(rèn) type 字符再認(rèn)寬度最后檢查是否已經(jīng)到了}。如果還有多余的字符直接拋 std::format_error。這個(gè)版本雖然簡(jiǎn)單但它是完整可編譯的能正確處理{:p10}這種說(shuō)明。注意我偷懶只處理了右對(duì)齊填充空格如果要做左對(duì)齊或居中對(duì)齊就得再解析 align 字符。我特別想提醒一件事手寫 parse 看起來(lái)并不難但它是一個(gè)典型的“邊界條件地獄”。你幾乎肯定會(huì)在某個(gè)細(xì)節(jié)上忘記處理比如 width 溢出、fill 后面沒(méi)有 align、出現(xiàn)在沒(méi)有 width 的位置等。標(biāo)準(zhǔn)庫(kù)給每個(gè)內(nèi)置類型都做了完整解析你沒(méi)必要為自定義類型再造一套輪子。這也是很多資深開發(fā)者最后都走向內(nèi)部復(fù)用標(biāo)準(zhǔn) formatter 的原因。3.3 復(fù)用標(biāo)準(zhǔn) formatter 的正確姿勢(shì)假設(shè)你有一個(gè) Person 類想讓它支持所有標(biāo)準(zhǔn)字符串格式化選項(xiàng)寬度、對(duì)齊、填充、截?cái)?。最聰明的辦法不是自己實(shí)現(xiàn)對(duì)齊邏輯而是讓 std::formatter std::string 替你干這些活template struct std::formatterPerson { std::formatterstd::string inner; constexpr auto parse(std::format_parse_context ctx) { return inner.parse(ctx); } auto format(const Person p, std::format_context ctx) const { return inner.format(p.name ( std::to_string(p.age) ), ctx); } };這個(gè)技巧是我在實(shí)際項(xiàng)目里反復(fù)用到的。它把一個(gè)自定義類型的格式化完全委托給字符串格式化器外部傳入的{:20}、{:.10}都會(huì)自動(dòng)生效而 inner 的 parse 已經(jīng)按照標(biāo)準(zhǔn)語(yǔ)法把所有邊界情況處理完了。你唯一要負(fù)責(zé)的就是決定這個(gè)對(duì)象變成什么樣的字符串文本。代價(jià)是很小的format 階段多一次字符串臨時(shí)對(duì)象的構(gòu)造和拷貝。對(duì)日志序列化這種場(chǎng)景來(lái)說(shuō)性能完全夠用。如果你對(duì)性能極端敏感非要避免臨時(shí)字符串那就只能手動(dòng)解析寬度和對(duì)齊并在 format 里直接用輸出迭代器寫字符比如用 format_to 把 x、分隔符、y 分段寫入。我個(gè)人的經(jīng)驗(yàn)是先寫清晰的委托版本性能分析真的指出熱點(diǎn)之后再把內(nèi)層替換成手寫路徑不要一開始就炫技。還有一個(gè)變體值得說(shuō)當(dāng)你想在同一類型里支持多種風(fēng)格說(shuō)明時(shí)可以繼續(xù)在這個(gè)內(nèi)部 formatter 之上加一個(gè)自己的 type 狀態(tài)。例如前面那個(gè) Point 的p/b風(fēng)格仍可以保留一個(gè) inner 來(lái)負(fù)責(zé)寬度對(duì)齊只額外解析一個(gè) type 字符。這樣 parse 的主邏輯是“先看一個(gè)字符是不是 p/b再把這個(gè) format 交給 inner 處理”代碼量比純手寫少很多也不會(huì)丟標(biāo)準(zhǔn)能力。4. 特化型擴(kuò)展點(diǎn)設(shè)計(jì)模式4.1 標(biāo)準(zhǔn)庫(kù)里的“特化即擴(kuò)展”家族std::formatter 并不是 C 標(biāo)準(zhǔn)庫(kù)里第一個(gè)使用模板特化做擴(kuò)展點(diǎn)的模板。前面還有 std::hash、std::char_traits、std::allocator、std::numeric_limits。它們共享一個(gè)核心思路主模板給出通用約定或留下未定義狀態(tài)用戶通過(guò)全特化或偏特化把自己的類型“注入”進(jìn)標(biāo)準(zhǔn)算法/容器/工具中。我對(duì)它們的理解是這類擴(kuò)展點(diǎn)的通配符就是“模板參數(shù)本身”。庫(kù)不需要知道你的類型長(zhǎng)什么樣它只知道存在一個(gè) formatter 于是它愿意在格式化流程中調(diào)用它它也不知道你的類型怎么算 hash但 std::unordered_map 會(huì)調(diào)用 std::hash 。類型成了庫(kù)和用戶之間的一枚鑰匙鑰匙齒形正確大門就自動(dòng)打開。這和定制點(diǎn)對(duì)象customization point object不一樣。定制點(diǎn)對(duì)象的核心是 ADL比如 std::ranges::begin 會(huì)在調(diào)用時(shí)去找用戶提供的成員 begin 或自由 begin 函數(shù)。formatter 不走 ADL它走“依賴類型參數(shù)的模板實(shí)例化”。兩種風(fēng)格各有用處但 formatter 用特化是更合適的原因在于格式化需要 parse 和 format 兩個(gè)階段共享狀態(tài)而不只是一個(gè)函數(shù)調(diào)用。4.2 特化比繼承和重載好在哪我見過(guò)不少庫(kù)喜歡給一組類型提供一個(gè)基類然后讓大家繼承并重寫虛函數(shù)來(lái)格式化。這在一個(gè)封閉的代碼庫(kù)里能跑通但一旦要接入第三方類型或者你的類型本來(lái)就沒(méi)有繼承關(guān)系的自由虛函數(shù)方案就直接卡殼。繼承還必然帶來(lái)動(dòng)態(tài)分派和堆分配對(duì) value semantics 極不友好。模板特化把這些麻煩全部繞過(guò)非侵入Point 完全可以是一個(gè)聚合類型連成員函數(shù)都不用加。值語(yǔ)義formatter 本身就是一個(gè)普通對(duì)象可以被拷貝、存放在任何容器里。編譯期可知std::format 可以推導(dǎo)出每個(gè)參數(shù)是否可格式化錯(cuò)誤在編譯期暴露。零繼承負(fù)擔(dān)沒(méi)有虛表沒(méi)有基類沒(méi)有運(yùn)行時(shí)類型信息。再用一個(gè)實(shí)際項(xiàng)目里的例子來(lái)說(shuō)我所在的團(tuán)隊(duì)維護(hù)著一個(gè)底層通訊庫(kù)里面有一堆消息結(jié)構(gòu)體每個(gè)結(jié)構(gòu)體都是純數(shù)據(jù)的聚合類型。我們不可能讓它們繼承某個(gè)公共格式化基類那會(huì)污染整個(gè)類設(shè)計(jì)。于是我們就在各自的消息類型旁邊放一個(gè) formatter 特化把協(xié)議字段的調(diào)試信息整理成可讀文本改動(dòng)面非常小也完全不碰消息類的內(nèi)部邏輯。4.3 與 concept 和定制點(diǎn)對(duì)象的配合C20 的 format 系列函數(shù)里對(duì)參數(shù)可格式化性的檢查并不是一個(gè)公開概念。到 C23標(biāo)準(zhǔn)給出了 std::formattable 概念它本質(zhì)上要求存在 std::formatterremove_cvref_t , CharT這個(gè) formatter 滿足 semiregular它能解析格式說(shuō)明它能格式化 T 的對(duì)象。換句話說(shuō)formattable 就是把“你有沒(méi)有特化過(guò) formatter”這個(gè)事實(shí)翻譯成一個(gè)可被約束檢查的表達(dá)式。你寫的特化只要滿足接口要求就會(huì)被自動(dòng)納入這套概念體系。如果想在自定義泛型函數(shù)里約束“某類型可被格式化”可以這樣做template typename T concept MyFormattable requires(const T v, std::format_context ctx) { typename std::formatterstd::remove_cvref_tT; std::formatterstd::remove_cvref_tT{}.format(v, ctx); };有了概念之后你可以在自己的代碼里寫出“只有可格式化的類型才能進(jìn)入日志系統(tǒng)”這樣的泛型約束。這是模板特化擴(kuò)展點(diǎn)和現(xiàn)代約束機(jī)制結(jié)合得很自然的地方特化是“提供實(shí)現(xiàn)”概念是“檢查是否提供實(shí)現(xiàn)”。我給一個(gè)我對(duì)這套模式的體感總結(jié)formatter 的擴(kuò)展點(diǎn)是“被動(dòng)型”的它不像 Python 那種鴨子類型運(yùn)行時(shí)詢問(wèn)“你行不行”而是在編譯期就把這件事釘死。你能從一個(gè)類型有沒(méi)有可用的 formatter 特化直接推斷它能不能被 {} 消費(fèi)這種確定性是運(yùn)行時(shí)分派給不了的。5. 實(shí)戰(zhàn)業(yè)務(wù)結(jié)構(gòu)體的多風(fēng)格格式化5.1 需求讓一個(gè)訂單結(jié)構(gòu)出現(xiàn)在日志里之前一個(gè)模擬項(xiàng)目里我需要把一個(gè)訂單結(jié)構(gòu)體打印到日志、調(diào)試輸出和導(dǎo)出文件里。三種場(chǎng)景想看到的內(nèi)容不太一樣日志里希望簡(jiǎn)潔A1001 | 199.00 | paid調(diào)試輸出希望路徑可讀比如包含字段名idA1001, amount199.00, statuspaid導(dǎo)出文件需要 CSVA1001,199.00,paid如果給 operator 實(shí)現(xiàn)你要不是寫三個(gè)重載要不就得靠調(diào)用方臨時(shí)改變流狀態(tài)。而用 formatter 特化我可以讓格式說(shuō)明符里的 type 字符來(lái)決定輸出風(fēng)格。5.2 實(shí)現(xiàn)一個(gè)帶格式“模式”的 Order formatter先定義簡(jiǎn)單結(jié)構(gòu)struct Order { std::string id; double amount; bool paid; };然后特化 formattertemplate struct std::formatterOrder { char mode 0; constexpr auto parse(std::format_parse_context ctx) { auto it ctx.begin(); if (it ctx.end() || *it }) { return it; } if (*it d || *it v || *it c) { mode *it; it; } if (it ! ctx.end() *it ! }) { throw std::format_error(Order 僅支持 d/v/c 格式模式); } return it; } auto format(const Order o, std::format_context ctx) const { std::string status o.paid ? paid : unpaid; switch (mode) { case d: return std::format_to(ctx.out(), {} | {:.2f} | {}, o.id, o.amount, status); case v: return std::format_to(ctx.out(), id{}, amount{:.2f}, status{}, o.id, o.amount, status); case c: return std::format_to(ctx.out(), {},{:.2f},{}, o.id, o.amount, status); default: return std::format_to(ctx.out(), {} | {:.2f} | {}, o.id, o.amount, status); } } };這樣調(diào)用起來(lái)非常直觀std::format({:d}, order); // A1001 | 199.00 | paid std::format({:v}, order); // idA1001, amount199.00, statuspaid std::format({:c}, order); // A1001,199.00,paid std::format({}, order); // 默認(rèn)走 d 風(fēng)格parse 里我消費(fèi)了 type 字符 d/v/c也檢查了后續(xù)直到}之間沒(méi)有多余內(nèi)容。這個(gè)實(shí)現(xiàn)不處理寬度、對(duì)齊等標(biāo)準(zhǔn)說(shuō)明符。如果實(shí)際項(xiàng)目需要日志列對(duì)齊我更傾向在上面 3.3 節(jié)說(shuō)的內(nèi)部 formatter 基礎(chǔ)上再加 mode也就是先解析 mode再把剩余說(shuō)明符委托給 std::formatter std::string 。這個(gè)設(shè)計(jì)讓“格式化”和“業(yè)務(wù)對(duì)象的序列化”保持在同一個(gè)位置而不是散落在各個(gè)調(diào)用點(diǎn)。團(tuán)隊(duì)里其他人只需要看這個(gè)特化就能知道 Order 能支持哪些輸出模式。5.3 嵌套 variant 和編譯期分派業(yè)務(wù)數(shù)據(jù)里經(jīng)常出現(xiàn)字段是可變的類型比如一個(gè)配置值可能是整數(shù)、浮點(diǎn)、字符串或者空。C 里最干凈的表達(dá)是 std::variant。如果直接在 formatter 里寫分支往往就會(huì)用到 std::visit 配合 if constexpr 做編譯期分派struct Value { std::variantstd::monostate, int, double, std::string v; }; template struct std::formatterValue { constexpr auto parse(std::format_parse_context ctx) { return ctx.begin(); } auto format(const Value val, std::format_context ctx) const { return std::visit([](const auto x) - std::format_context::iterator { using T std::remove_cvref_tdecltype(x); if constexpr (std::is_same_vT, std::monostate) { return std::format_to(ctx.out(), null); } else if constexpr (std::is_same_vT, int) { return std::format_to(ctx.out(), {}, x); } else if constexpr (std::is_same_vT, double) { return std::format_to(ctx.out(), {:.2f}, x); } else { return std::format_to(ctx.out(), \{}\, x); } }, val.v); } };這里 std::visit 是運(yùn)行時(shí)的變體分派而 if constexpr 是編譯期的類型條件。兩者疊加起來(lái)每個(gè) variant 可能攜帶的類型都在編譯期被展開成一段專門的格式化代碼。輸出效果類似 JSON 風(fēng)格的null、42、3.14、hello。這種做法非常能體現(xiàn) formatter 作為擴(kuò)展點(diǎn)的組合能力你不需要讓 variant 內(nèi)部元素各自實(shí)現(xiàn)什么接口只要它們本身是可格式化的外面套一層編譯期分派就能繼續(xù)遞歸工作。6. 常見問(wèn)題與編譯報(bào)錯(cuò)實(shí)錄6.1 特化放錯(cuò)命名空間寫自定義 formatter 最容易犯的第一個(gè)錯(cuò)誤是忘記把模板特化放進(jìn) std 命名空間。如果你在全局命名空間這樣寫template struct std::formatterPoint { ... };這其實(shí)是合法的前提是你顯式用了std::修飾。但如果你圖省事在全局命名空間寫template struct formatterPoint { ... };編譯器會(huì)把 formatter 當(dāng)成全局的自定義模板和標(biāo)準(zhǔn)庫(kù)的 formatter 沒(méi)有任何關(guān)系。std::format 在實(shí)例化時(shí)尋找的是 std::formatter 自然找不到。報(bào)錯(cuò)通常是一長(zhǎng)串“no type named formatter in std”或者類似的信息。我建議在代碼里寫成template struct std::formatterPoint { ... };幾乎所有主流實(shí)現(xiàn)都接受這種寫法語(yǔ)義清晰。有些老一點(diǎn)的編譯器或者特殊環(huán)境也可能要求你把它包裹在namespace std { ... }里那種寫法也完全沒(méi)問(wèn)題。6.2 parse 消費(fèi)了格式說(shuō)明卻仍報(bào)錯(cuò)第二個(gè)高頻坑是你在 parse 里明明處理了格式說(shuō)明但運(yùn)行程序時(shí) std::format 依然拋 std::format_error。這個(gè)問(wèn)題的根源往往是返回值沒(méi)有停在}之前。舉個(gè)例子你為了解析 type 字符做了it但沒(méi)有檢查此時(shí) it 是否已經(jīng)指向}然后直接返回 it。如果用戶寫的是{:p}且你只消費(fèi)了 p此時(shí) it 指向}那沒(méi)問(wèn)題但如果你把}也當(dāng)成可消費(fèi)字符往前挪了一步返回的迭代器位置就不對(duì)了。判斷標(biāo)準(zhǔn)很簡(jiǎn)單parse 返回的迭代器必須指向}或者指向格式字符串的末尾空說(shuō)明符的情況。一旦返回位置停在不該停的地方上層格式化函數(shù)就會(huì)認(rèn)為有未識(shí)別的說(shuō)明符于是拋異常。排查時(shí)我習(xí)慣在 parse 里故意打印或斷點(diǎn)觀察 it 的值一眼就能看出是不是消費(fèi)過(guò)頭了。另一個(gè)相關(guān)坑parse 里檢查了某種情況并拋 std::format_error但異常被某個(gè)更外層的字符串格式化邏輯僥幸吞掉了導(dǎo)致你看到的行為很奇怪。這種情況通常出現(xiàn)在嵌套格式化內(nèi)部比如你在一個(gè) formatter 的 format 里又調(diào)用 std::format 格式化一個(gè)內(nèi)部類型內(nèi)部類型拋出的異常需要被異常處理邏輯捕獲。避免的辦法是不要在任何 format 階段去捕獲解析階段的異常讓異常自然向上傳播。6.3 輸出迭代器與臨時(shí)緩沖區(qū)的坑format 返回的是輸出迭代器正常使用時(shí)我們幾乎從不檢查它。但如果你在 formatter 的 format 內(nèi)部維護(hù)了一個(gè)臨時(shí) buffer就可能出現(xiàn)迭代器失效問(wèn)題。就拿 3.3 那節(jié)委托給 std::formatter std::string 的例子來(lái)說(shuō)inner.format 接收的 std::string 是我們臨時(shí)拼出來(lái)的它在函數(shù)返回后就銷毀了但返回的迭代器已經(jīng)被妥善寫入了 ctx.out()所以問(wèn)題不大。真正要小心的是你自己保存 ctx.out() 的迭代器然后在循環(huán)里反復(fù)寫。某些輸出迭代器是單遍的拷貝之后再寫入行為未必符合直覺。我用過(guò)幾條實(shí)用規(guī)則每條路徑只調(diào)用一次 ctx.out()然后一路用完。不要在多個(gè)分支里分別拿 ctx.out() 并交叉使用。如果確實(shí)需要先構(gòu)造完整字符串再統(tǒng)一寫出去那就一次 format_to 搞定不要分多次寫。6.4 和 operator 共存不少代碼庫(kù)既有 operator又要接入 std::format。最直接的做法是在 operator 里調(diào)用 std::formatstd::ostream operator(std::ostream os, const Order o) { return os std::format({}, o); }這樣二者輸出的效果完全一致還避免了重復(fù)實(shí)現(xiàn)。但要注意一個(gè)問(wèn)題包含 的編譯單元會(huì)顯著增加編譯時(shí)間。如果 operator 所在的頭文件被大量 include整個(gè)項(xiàng)目的編譯成本容易上升。我的做法是把 operator 的實(shí)現(xiàn)放 .cpp 文件或者單獨(dú)用一個(gè)頭文件存放所有自定義 formatter 特化只在需要格式化的地方 include。還有一個(gè)關(guān)于可見性的問(wèn)題formatter 特化和 operator 一樣必須在“調(diào)用 std::format 的那個(gè)翻譯單元”可見。如果你把特化放在某個(gè)靜態(tài)庫(kù)的 .cpp 內(nèi)部調(diào)用方看不到特化編譯器就會(huì)認(rèn)為類型不可格式化。解決方案很簡(jiǎn)單把特化放到一個(gè)頭文件里跟類型聲明放一起保證任何看到類型的地方都能看到特化。最后分享兩個(gè)實(shí)操細(xì)節(jié)在收尾之前我還想講兩個(gè)從實(shí)際項(xiàng)目里悟到的細(xì)節(jié)。第一個(gè)是關(guān)于“不要在 format 里過(guò)度拼接中間字符串”。我見過(guò)有人把 formatter 的 format 寫成auto format(const Order o, std::format_context ctx) const { std::string tmp o.id | std::to_string(o.amount) | std::to_string(o.paid); return std::format_to(ctx.out(), {}, tmp); }這當(dāng)然能跑但對(duì)性能不友好。如果這個(gè) formatter 用在每秒鐘上萬(wàn)條的日志路徑上建議改成直接 std::format_to(ctx.out(), {} | {:.2f} | {}, ...)讓數(shù)據(jù)直接流向輸出迭代器省掉中間字符串。先寫清晰版本熱點(diǎn)明確后性能優(yōu)化通常只需要改 formatter 內(nèi)部對(duì)外調(diào)用方完全無(wú)感這本身就是這套擴(kuò)展點(diǎn)設(shè)計(jì)給維護(hù)者留下的余地。第二個(gè)細(xì)節(jié)是當(dāng)你想讓自定義類型支持{:?}這種格式類型時(shí)不要害怕在 parse 里拋 std::format_error。有些人過(guò)度擔(dān)心異常會(huì)破壞格式化的優(yōu)雅性但 std::format 明確用異常來(lái)表示格式字符串非法這是接口約定的一部分。你認(rèn)真拋異常用戶才能第一時(shí)間看到錯(cuò)誤說(shuō)明這比返回一個(gè)錯(cuò)位的迭代器讓庫(kù)拋出含糊錯(cuò)誤要友好得多。C 的 std::format 這套擴(kuò)展點(diǎn)表面上是幾個(gè)成員函數(shù)的組合骨子里卻是“模板特化即開放接口”的現(xiàn)代 C 設(shè)計(jì)思路。你一旦習(xí)慣了用 formatter 去表達(dá)一個(gè)類型的多個(gè)輸出視圖會(huì)發(fā)現(xiàn)它能替代掉不少過(guò)去靠流操縱符和序列化函數(shù)拼接才能做到的事。這篇文章寫到的代碼都來(lái)自我用過(guò)的真實(shí)場(chǎng)景至少在我的項(xiàng)目里它們已經(jīng)穩(wěn)定跑了好一陣。如果你也正在給某個(gè)自定義類型接 std::format希望讀完這篇能少走幾步彎路直接寫出自己真正需要的特化。