当文档注释不再可靠

几乎每个 C++ 项目都经历过这样的循环：函数文档里写着“参数 x 必须为正数”，但代码里最多只有一个assert，甚至完全依赖调用者的自律。Releases 版本把断言关闭，一旦有野生的非法参数闯入，程序就在静默中崩溃。C++26 终于给出了系统性的答案——契约（Contracts），它把“参数非空”“索引在范围内”“函数结束后不变式成立”这些写作文档里的约定，提升为可编译、可检查的结构化约束。

什么是契约编程

契约编程（Contract Programming / Design by Contract）并不是新概念，早在 Eiffel 语言中就已被充分实践。它的核心思想很朴素：一个函数是一份契约，调用方负责满足前置条件（precondition），实现方负责满足后置条件（postcondition），而类本身还要在所有时刻保持不变式（invariant）。

调用方承诺传入正确的参数；函数承诺返回正确的结果。
契约让双方的责任不再是注释中的“应该”，而是代码的一部分。

C++ 里此前并没有语言级的契约支持。我们只能用assert、throw或文档注释来表达这些约束，缺一不可：assert只在 debug 模式生效，异常会导致流程跳转且被某些项目禁用，而文档注释与代码实际行为完全可以脱节。C++26 契约设施要改变的，正是这种“写归写、跑归跑”的局面。

C++26 契约语法概览

C++26 的契约提案（P2900 系列）引入了三个核心关键字级别的属性：pre、post和contract_assert。它们直接写在函数声明或定义中，不依赖预处理器宏，也不改变函数签名。

• 前置条件：[[pre: 条件表达式]]写在函数参数之后、函数体之前。
• 后置条件：[[post: 条件表达式]]写在函数声明尾部。在条件表达式中可以使用特殊记号result来引用函数的返回值。
• 契约断言：contract_assert(条件);可以在函数体内任何位置使用，行为与assert类似，但遵守契约的构建模式。

int divide(int a, int b) [[pre: b != 0]] // 前置条件 [[pre: a >= 0 && b > 0]] // 可以多条 [[post: result >= 0]]; // 后置条件：返回值非负 int divide(int a, int b) { return a / b; }

上面的代码中，调用divide(10, 0)会触发前置条件违反，divide(-5, 3)也会被第二条pre捕获。而不论内部如何计算，后置条件都会在函数返回时被检查。

构建模式：不止一种检查策略

C++26 契约与assert最大的不同，在于它提供了可配置的构建模式（build mode）。编译器提供至少三种策略级别：

这种分级让团队可以对不同翻译单元设定不同的检查强度：核心数据层的契约可在 Release 中保留审计，而对性能极为敏感的热路径则在确认安全后关闭检查。

契约 vs 传统防御式编程

有人可能会问：这不就是更高级的assert吗？区别在于三个关键点：

• 结构化且可见：契约直接出现在声明中，成为接口的一部分，工具、IDE 和文档生成器可以提取并展示。
• 不依赖宏：assert的开关受NDEBUG影响，跨模块混合 Debug/Release 库时容易出错。契约的构建模式由编译器选项统一管理，层次更清晰。
• 优化假设：在契约关闭的模式下，编译器可以将前置条件作为“真理”进行优化，消除分支，这在传统assert关闭后是不可能的，因为assert移除后编译器会失去该信息。

因此，契约不仅是在运行期做检查，更是在编译期为优化器提供“承诺”。

实际应用：从数组访问到资源获取

契约可以显著简化接口设计。考虑一个安全的数组at操作：

template <typename T, std::size_t N> constexpr T& safe_at(std::array<T, N>& arr, std::size_t idx) [[pre: idx < N]] { return arr[idx]; }

在带审计检查的构建中，越界访问会被直接捕获；在关闭模式下，编译器可以假定idx < N成立并可能直接做无条件访问。再比如文件句柄类：

class file_handle { int fd; public: explicit file_handle(int raw_fd) [[pre: raw_fd >= 0]] : fd(raw_fd) {} int get() const [[post: result >= 0]] { return fd; } };

后置条件result >= 0表明无论内部如何维护，get()返回的句柄绝不会是负值。这让调用者不需要再反复检查返回值。

与文档的共生：从注释到源码真理

很多项目用 Doxygen、Sphinx 或标准注释来记录前置/后置条件。C++26 契约为这类文档提供了唯一的真相来源（Single Source of Truth）。未来工具可以直接从[[pre: ...]]和[[post: ...]]自动生成文档，不必担心注释过期或描述不准确。

例如，一个排序函数的契约：

void sort_range(std::vector<int>& v, std::size_t lo, std::size_t hi) [[pre: lo <= hi]] [[pre: hi <= v.size()]] [[post: std::ranges::is_sorted(v)]];

文档生成器可以直接提取“要求 lo <= hi 且 hi 不越界，保证排序后区间有序”。这比任何人工维护的 Doxygen 注释都更可靠。

注意事项与最佳实践

• 契约不是异常处理替代品：契约适用于可预见的逻辑错误（如越界、空指针），而不应用于运行时环境错误（如文件不存在、网络超时）。对于后者仍然应使用异常或std::expected。
• 保持条件纯且不含副作用：前置/后置条件应在多个构建模式中评估，不能依赖全局可变状态或带有副作用。例如[[pre: check_and_log()]]可能会在不同模式下产生不一致的行为。
• 避免在契约中做昂贵操作：后置条件如果要比较两个大容器排序结果，成本可能过高，应只用于可负担的检查。
• 逐步迁移：从核心数据结构和安全敏感接口开始引入契约，不要一次性全项目铺开。
• 结合静态分析：契约信息可被静态分析工具利用，甚至某些简单条件（如idx < N）在调用点处编译器已知的上下文中可以静态检查。

当前编译器支持与展望

截至 2026 年中，GCC 14/15 和 Clang 18/19 已在实验性分支中实现了契约的基本支持，MSVC 也在积极推进。虽然语法和语义在定稿过程中仍有微调，但核心方向已经确定。C++26 的发布将是 C++ 从“让程序员更自由”到“让意图更显式”的重要转折。

结语

契约编程正式入标，不是给 C++ 增加了一个花哨功能，而是纠正了长久以来“设计意图只能存在于文档”的错位。前置、后置条件和契约断言成为语言的一部分后，接口变得更加诚实，代码审查更聚焦，编译器优化更激进。对于长期与大型 C++ 代码库共存的团队来说，这可能是 C++26 里最值得立刻引入的特性。