说真的我第一次在代码里用上 std::format 的时候脑子里冒出来的想法不是“语法真漂亮”而是“早该有了”。printf 的年代我还没怎么受折磨倒是 operator 那套流式格式化陪了我好多年。直到我真正想给一个自定义的业务结构体加格式化输出才发现 std::format 的文档里其实藏着一条暗线你想让某个类型被 {} 格式化不是靠继承也不是靠写虚函数而是去特化 std::formatter。这条路如果没摸熟很容易在一串莫名其妙的编译错误里打转。这篇文章就围绕 formatter 特化这件事展开把 parse 和 format 两个接口的来龙去脉讲清楚也会聊聊这种“特化即扩展点”的设计模式在标准库里到底是怎么运作的。如果你在写业务代码看完可以直接把自定义的枚举、结构体、嵌套对象接到 std::format 上如果你对库设计也有兴趣能从这套机制里看到现代 C 扩展点的一种典型形态。目标读者是已经写过一点 C20、被 std::format 便利性吸引过、但没仔细研究过自定义格式化器的人。1. 为什么 std::format 需要自定义格式化器1.1 printf 与 iostream 的旧账C 语言留下的 printf 家族在 C20 之前几乎是唯一的“格式化”心智模型。可它有两个硬伤类型不安全以及不可扩展。类型不安全不用多说int 和 double 写错转换符是编译器完全不管的事不可扩展更难受你想让一个自定义的订单结构体出现在日志里printf 根本给不出一个干净的方案。你只能先把它拼成一个字符串再 %s 打进去等于手动造序列化。后来大家转向 iostream用 operator 重载来定义输出。这确实解决了类型安全和基本扩展问题但代价是格式状态是全局的格式化参数混在流里比如 std::setw、std::setprecision一旦忘了恢复就到处传染。最要命的是性能一条日志输出可能要多次函数调用和缓冲操作。std::format 的价值就在于格式说明集中在一个字符串里参数类型编译期检查输出目标是输出迭代器整个过程既兼顾了 printf 的紧凑又吸收了类型系统的安全性。1.2 自定义类型格式化的旧方案与新契约先看一个非常常见的数据结构struct Point { int x; int y; };在 iostream 时代你要么给 Point 写 operator要么写一个 to_string 方法。两者都不是坏方案但问题是它们和“格式化”本身是割裂的。比如调用方想控制宽度和对齐operator 就得声明一堆流操纵符或者靠调用方自己拼。到 std::format 这边事情变成了另一套契约库提供一个主模板 std::formatterT, CharT默认没有实现。用户为自己的类型特化这个模板提供两个成员函数parse 和 format。当 std::format({}, p) 被实例化时编译器自动查找 std::formatter 。这套契约最大的好处是格式化能力不再依赖继承体系也不依赖某个命名约定模板特化本身就变成了扩展点。你不需要修改 Point 的内部也不需要 Point 继承某个 FormatterBase只要在 std 命名空间里给出合法的特化这个类型就“自动”获得了格式化能力。2. 认识扩展点std::formatter 特化的基本骨架2.1 formatter 最简单的特化给 Point 写一个最简特化长这样#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)。我把完整代码写出来的时候大部分人会觉得就这对就这。但不要急着往下跳parse 这里直接返回 ctx.begin() 只是最省事的写法它对“没有任何格式说明符”的情况有效可一旦用户写出{:10}这种说明符问题就来了。这个特化的关键点在于模板参数是 Point而不是const Point或者Point。标准库在查找格式化器时会对类型做 remove_cvref 处理所以特化 formatter 就够用了。format 方法的第一个参数虽然是 const Point但这个 const 是成员函数约定的一部分特化目标类型仍然写成非 const 的 Point。很多初学者在这里会把两个 const 概念搞混。2.2 parse 和 format 的调用时机与职责划分有必要把这两个阶段的职责彻底理清因为这是整个扩展点最容易出错的地方。parse 负责“解释格式说明符”。当 std::format 遇到{:10}时它会先把格式说明符字符串抽出来构造一个 parse context然后调用 formatter 的 parse。parse 的输入迭代器指向格式说明符的第一个字符它需要消费掉自己认识的字符返回指向第一个不认识的字符的迭代器。库会检查这个返回值如果它没有指向}就认定格式说明非法抛 std::format_error。format 负责“真正把对象写到输出迭代器”。它在 parse 之后被调用此时 formatter 内部已经保存了解析出来的各种配置比如宽度、对齐方式、自定义模式等。format 要做的事情很简单根据这些配置把 T 的内容格式化输出到 ctx.out()。我把这个过程类比成一个小的状态机某个人先给你一段说明你把关键信息记在心里然后对象递到你面前你按照记住的说明把它写在纸上。parse 是“读说明”format 是“写对象”。两者通过 formatter 对象的成员变量共享状态所以 parse 必须保证所有被支持的格式说明都要被正确处理否则 format 阶段拿到的状态就是残缺的。还有一个细节是 parse 最好写成 constexpr。标准库实现里对格式字符串的编译期检查往往就是在常量表达式环境中调用 parse 来做到的。虽然写不写 constexpr 在很多场景下都能编译通过但主流实现都倾向于要求它可被常量求值所以新手直接加上 constexpr 是稳妥习惯。2.3 宽字符形式的扩展点std::format 有两套基本格式字符串char 和 wchar_t。对应地formatter 的第二个模板参数 CharT 默认是 char。如果你希望定义的类型能被std::format(L{}, p)支持就需要再特化一个 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); } };我实际遇到的业务场景里窄字符格式基本够用但有几次要给 Windows 下的日志接口喂宽字符字符串补特化就不可避免。如果只有 char 特化编译器会给出一个特别长的报错核心意思是“formatterPoint, wchar_t 不完整”。这时候别慌照着窄字符的版本补一个就完事。要注意的是wformat_parse_context 和 wformat_context 的别名都要从 wchar_t 版本拿别混着用。3. 让格式化器读懂格式说明parse 的实现细节3.1 格式说明符到底包含什么标准格式说明符的完整语法是[[fill]align][sign][#][0][width][.precision][type]fill 是任意字符align 是、、^sign 是、-、空格width 是一串数字precision 是小数点加数字type 是字母。对自定义类型来说标准允许你定义自己的一组 type 字符其他部分如果能解析则通常意味着你需要支持它们。这带来一个很微妙的点如果你的 parse 只认识 type 字符c而用户写了{:c10}即宽度 10、左对齐、类型字符 c那么你要么完整消费掉这些标准语法要么明确抛异常。直接return ctx.begin()等于假装什么都没看见库会认为格式说明里还有残留字符最终照样抛异常而且抛错的位置还不在你的代码里排查起来非常费劲。3.2 手动解析一个完整例子为了看透 parse 的工作机制我写一个带自定义 type 和宽度的手动解析版本。假设 Point 支持p表示圆括号风格、b表示方括号风格并且只接受纯数字宽度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 不支持该格式说明); } 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 的消费顺序是先认 type 字符再认宽度最后检查是否已经到了}。如果还有多余的字符直接抛 std::format_error。这个版本虽然简单但它是完整可编译的能正确处理{:p10}这种说明。注意我偷懒只处理了右对齐填充空格如果要做左对齐或居中对齐就得再解析 align 字符。我特别想提醒一件事手写 parse 看起来并不难但它是一个典型的“边界条件地狱”。你几乎肯定会在某个细节上忘记处理比如 width 溢出、fill 后面没有 align、出现在没有 width 的位置等。标准库给每个内置类型都做了完整解析你没必要为自定义类型再造一套轮子。这也是很多资深开发者最后都走向内部复用标准 formatter 的原因。3.3 复用标准 formatter 的正确姿势假设你有一个 Person 类想让它支持所有标准字符串格式化选项宽度、对齐、填充、截断。最聪明的办法不是自己实现对齐逻辑而是让 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); } };这个技巧是我在实际项目里反复用到的。它把一个自定义类型的格式化完全委托给字符串格式化器外部传入的{:20}、{:.10}都会自动生效而 inner 的 parse 已经按照标准语法把所有边界情况处理完了。你唯一要负责的就是决定这个对象变成什么样的字符串文本。代价是很小的format 阶段多一次字符串临时对象的构造和拷贝。对日志序列化这种场景来说性能完全够用。如果你对性能极端敏感非要避免临时字符串那就只能手动解析宽度和对齐并在 format 里直接用输出迭代器写字符比如用 format_to 把 x、分隔符、y 分段写入。我个人的经验是先写清晰的委托版本性能分析真的指出热点之后再把内层替换成手写路径不要一开始就炫技。还有一个变体值得说当你想在同一类型里支持多种风格说明时可以继续在这个内部 formatter 之上加一个自己的 type 状态。例如前面那个 Point 的p/b风格仍可以保留一个 inner 来负责宽度对齐只额外解析一个 type 字符。这样 parse 的主逻辑是“先看一个字符是不是 p/b再把这个 format 交给 inner 处理”代码量比纯手写少很多也不会丢标准能力。4. 特化型扩展点设计模式4.1 标准库里的“特化即扩展”家族std::formatter 并不是 C 标准库里第一个使用模板特化做扩展点的模板。前面还有 std::hash、std::char_traits、std::allocator、std::numeric_limits。它们共享一个核心思路主模板给出通用约定或留下未定义状态用户通过全特化或偏特化把自己的类型“注入”进标准算法/容器/工具中。我对它们的理解是这类扩展点的通配符就是“模板参数本身”。库不需要知道你的类型长什么样它只知道存在一个 formatter 于是它愿意在格式化流程中调用它它也不知道你的类型怎么算 hash但 std::unordered_map 会调用 std::hash 。类型成了库和用户之间的一枚钥匙钥匙齿形正确大门就自动打开。这和定制点对象customization point object不一样。定制点对象的核心是 ADL比如 std::ranges::begin 会在调用时去找用户提供的成员 begin 或自由 begin 函数。formatter 不走 ADL它走“依赖类型参数的模板实例化”。两种风格各有用处但 formatter 用特化是更合适的原因在于格式化需要 parse 和 format 两个阶段共享状态而不只是一个函数调用。4.2 特化比继承和重载好在哪我见过不少库喜欢给一组类型提供一个基类然后让大家继承并重写虚函数来格式化。这在一个封闭的代码库里能跑通但一旦要接入第三方类型或者你的类型本来就没有继承关系的自由虚函数方案就直接卡壳。继承还必然带来动态分派和堆分配对 value semantics 极不友好。模板特化把这些麻烦全部绕过非侵入Point 完全可以是一个聚合类型连成员函数都不用加。值语义formatter 本身就是一个普通对象可以被拷贝、存放在任何容器里。编译期可知std::format 可以推导出每个参数是否可格式化错误在编译期暴露。零继承负担没有虚表没有基类没有运行时类型信息。再用一个实际项目里的例子来说我所在的团队维护着一个底层通讯库里面有一堆消息结构体每个结构体都是纯数据的聚合类型。我们不可能让它们继承某个公共格式化基类那会污染整个类设计。于是我们就在各自的消息类型旁边放一个 formatter 特化把协议字段的调试信息整理成可读文本改动面非常小也完全不碰消息类的内部逻辑。4.3 与 concept 和定制点对象的配合C20 的 format 系列函数里对参数可格式化性的检查并不是一个公开概念。到 C23标准给出了 std::formattable 概念它本质上要求存在 std::formatterremove_cvref_t , CharT这个 formatter 满足 semiregular它能解析格式说明它能格式化 T 的对象。换句话说formattable 就是把“你有没有特化过 formatter”这个事实翻译成一个可被约束检查的表达式。你写的特化只要满足接口要求就会被自动纳入这套概念体系。如果想在自定义泛型函数里约束“某类型可被格式化”可以这样做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); };有了概念之后你可以在自己的代码里写出“只有可格式化的类型才能进入日志系统”这样的泛型约束。这是模板特化扩展点和现代约束机制结合得很自然的地方特化是“提供实现”概念是“检查是否提供实现”。我给一个我对这套模式的体感总结formatter 的扩展点是“被动型”的它不像 Python 那种鸭子类型运行时询问“你行不行”而是在编译期就把这件事钉死。你能从一个类型有没有可用的 formatter 特化直接推断它能不能被 {} 消费这种确定性是运行时分派给不了的。5. 实战业务结构体的多风格格式化5.1 需求让一个订单结构出现在日志里之前一个模拟项目里我需要把一个订单结构体打印到日志、调试输出和导出文件里。三种场景想看到的内容不太一样日志里希望简洁A1001 | 199.00 | paid调试输出希望路径可读比如包含字段名idA1001, amount199.00, statuspaid导出文件需要 CSVA1001,199.00,paid如果给 operator 实现你要不是写三个重载要不就得靠调用方临时改变流状态。而用 formatter 特化我可以让格式说明符里的 type 字符来决定输出风格。5.2 实现一个带格式“模式”的 Order formatter先定义简单结构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); } } };这样调用起来非常直观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); // 默认走 d 风格parse 里我消费了 type 字符 d/v/c也检查了后续直到}之间没有多余内容。这个实现不处理宽度、对齐等标准说明符。如果实际项目需要日志列对齐我更倾向在上面 3.3 节说的内部 formatter 基础上再加 mode也就是先解析 mode再把剩余说明符委托给 std::formatter std::string 。这个设计让“格式化”和“业务对象的序列化”保持在同一个位置而不是散落在各个调用点。团队里其他人只需要看这个特化就能知道 Order 能支持哪些输出模式。5.3 嵌套 variant 和编译期分派业务数据里经常出现字段是可变的类型比如一个配置值可能是整数、浮点、字符串或者空。C 里最干净的表达是 std::variant。如果直接在 formatter 里写分支往往就会用到 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 是运行时的变体分派而 if constexpr 是编译期的类型条件。两者叠加起来每个 variant 可能携带的类型都在编译期被展开成一段专门的格式化代码。输出效果类似 JSON 风格的null、42、3.14、hello。这种做法非常能体现 formatter 作为扩展点的组合能力你不需要让 variant 内部元素各自实现什么接口只要它们本身是可格式化的外面套一层编译期分派就能继续递归工作。6. 常见问题与编译报错实录6.1 特化放错命名空间写自定义 formatter 最容易犯的第一个错误是忘记把模板特化放进 std 命名空间。如果你在全局命名空间这样写template struct std::formatterPoint { ... };这其实是合法的前提是你显式用了std::修饰。但如果你图省事在全局命名空间写template struct formatterPoint { ... };编译器会把 formatter 当成全局的自定义模板和标准库的 formatter 没有任何关系。std::format 在实例化时寻找的是 std::formatter 自然找不到。报错通常是一长串“no type named formatter in std”或者类似的信息。我建议在代码里写成template struct std::formatterPoint { ... };几乎所有主流实现都接受这种写法语义清晰。有些老一点的编译器或者特殊环境也可能要求你把它包裹在namespace std { ... }里那种写法也完全没问题。6.2 parse 消费了格式说明却仍报错第二个高频坑是你在 parse 里明明处理了格式说明但运行程序时 std::format 依然抛 std::format_error。这个问题的根源往往是返回值没有停在}之前。举个例子你为了解析 type 字符做了it但没有检查此时 it 是否已经指向}然后直接返回 it。如果用户写的是{:p}且你只消费了 p此时 it 指向}那没问题但如果你把}也当成可消费字符往前挪了一步返回的迭代器位置就不对了。判断标准很简单parse 返回的迭代器必须指向}或者指向格式字符串的末尾空说明符的情况。一旦返回位置停在不该停的地方上层格式化函数就会认为有未识别的说明符于是抛异常。排查时我习惯在 parse 里故意打印或断点观察 it 的值一眼就能看出是不是消费过头了。另一个相关坑parse 里检查了某种情况并抛 std::format_error但异常被某个更外层的字符串格式化逻辑侥幸吞掉了导致你看到的行为很奇怪。这种情况通常出现在嵌套格式化内部比如你在一个 formatter 的 format 里又调用 std::format 格式化一个内部类型内部类型抛出的异常需要被异常处理逻辑捕获。避免的办法是不要在任何 format 阶段去捕获解析阶段的异常让异常自然向上传播。6.3 输出迭代器与临时缓冲区的坑format 返回的是输出迭代器正常使用时我们几乎从不检查它。但如果你在 formatter 的 format 内部维护了一个临时 buffer就可能出现迭代器失效问题。就拿 3.3 那节委托给 std::formatter std::string 的例子来说inner.format 接收的 std::string 是我们临时拼出来的它在函数返回后就销毁了但返回的迭代器已经被妥善写入了 ctx.out()所以问题不大。真正要小心的是你自己保存 ctx.out() 的迭代器然后在循环里反复写。某些输出迭代器是单遍的拷贝之后再写入行为未必符合直觉。我用过几条实用规则每条路径只调用一次 ctx.out()然后一路用完。不要在多个分支里分别拿 ctx.out() 并交叉使用。如果确实需要先构造完整字符串再统一写出去那就一次 format_to 搞定不要分多次写。6.4 和 operator 共存不少代码库既有 operator又要接入 std::format。最直接的做法是在 operator 里调用 std::formatstd::ostream operator(std::ostream os, const Order o) { return os std::format({}, o); }这样二者输出的效果完全一致还避免了重复实现。但要注意一个问题包含 的编译单元会显著增加编译时间。如果 operator 所在的头文件被大量 include整个项目的编译成本容易上升。我的做法是把 operator 的实现放 .cpp 文件或者单独用一个头文件存放所有自定义 formatter 特化只在需要格式化的地方 include。还有一个关于可见性的问题formatter 特化和 operator 一样必须在“调用 std::format 的那个翻译单元”可见。如果你把特化放在某个静态库的 .cpp 内部调用方看不到特化编译器就会认为类型不可格式化。解决方案很简单把特化放到一个头文件里跟类型声明放一起保证任何看到类型的地方都能看到特化。最后分享两个实操细节在收尾之前我还想讲两个从实际项目里悟到的细节。第一个是关于“不要在 format 里过度拼接中间字符串”。我见过有人把 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); }这当然能跑但对性能不友好。如果这个 formatter 用在每秒钟上万条的日志路径上建议改成直接 std::format_to(ctx.out(), {} | {:.2f} | {}, ...)让数据直接流向输出迭代器省掉中间字符串。先写清晰版本热点明确后性能优化通常只需要改 formatter 内部对外调用方完全无感这本身就是这套扩展点设计给维护者留下的余地。第二个细节是当你想让自定义类型支持{:?}这种格式类型时不要害怕在 parse 里抛 std::format_error。有些人过度担心异常会破坏格式化的优雅性但 std::format 明确用异常来表示格式字符串非法这是接口约定的一部分。你认真抛异常用户才能第一时间看到错误说明这比返回一个错位的迭代器让库抛出含糊错误要友好得多。C 的 std::format 这套扩展点表面上是几个成员函数的组合骨子里却是“模板特化即开放接口”的现代 C 设计思路。你一旦习惯了用 formatter 去表达一个类型的多个输出视图会发现它能替代掉不少过去靠流操纵符和序列化函数拼接才能做到的事。这篇文章写到的代码都来自我用过的真实场景至少在我的项目里它们已经稳定跑了好一阵。如果你也正在给某个自定义类型接 std::format希望读完这篇能少走几步弯路直接写出自己真正需要的特化。
