![[C++20/API设计] 告别“接口防呆手册”！用这5个现代C++特性，打造“绝不误用”的黄金 API](images/news1.jpg)
[!NOTE]导读摘要在 C 开发中接口的误用是导致 Bug 的重灾区。与其编写冗长且无人阅读的“接口防呆说明书”不如利用编译器为我们站岗。本文以 CppCon 2022 上 Jason Turner 的演讲《C API Design》为基础深度剖析如何通过explicit构造函数、[[nodiscard]]属性、noexcept语义、强类型枚举及智能指针让接口在编译期就具备强大的“自我防错”能力。此外本文还将专家级地延伸探讨 C20 条件 explicit、C23 单子式错误处理类型std::expected以及强类型包装Strong Typedefs帮助读者设计出兼具极致性能与安全性的现代 C API。作为 C 程序员我们每天都在跟各种 API 打交道。但你是否遇到过下面这种让人哭笑不得的代码// 程序员 A 写的接口voidconfigureSystem(boolenableCache,boolreadOnly,booldebugMode);// 程序员 B 的调用方式configureSystem(true,false,true);// 谁能一眼看出这三个 bool 分别代表啥或者这种由于隐式转换引发的隐蔽 BugclassTimer{public:Timer(intseconds);// 单参数构造函数未加 explicit};voidrunTask(Timer t);// 某天一个粗心的同事敲下了这行代码runTask(42);// 编译器极其聪明地把 42 隐式转换成了 Timer 对象这真的符合预期吗Scott Meyers 曾在《Effective C》中提出过 API 设计的至高准则“Make APIs easy to use correctly and hard to use incorrectly.”让 API 易于正确使用难于错误使用。在 CppCon 2022 的“Back to Basics: C API Design”演讲中Jason Turner 为我们系统性地梳理了如何用现代 C 特性将这句名言付诸实践。今天我们就来深度聊聊如何利用 C 的类型系统打造一个**“想写错都难”**的黄金 API。1.explicit斩断隐式转换的“越界之手”在 C 中如果一个类拥有一个单参数构造函数或者除了第一个参数外其他参数都有默认值那么这个构造函数默认就成为了一个隐式转换运算符。 隐式转换的灾难#includeiostream#includestringclassUser{std::string name_;public:User(std::string name):name_(move(name)){}// 隐式转换构造函数};voidregisterUser(constUseruser){// 注册逻辑...}intmain(){// 糟糕由于隐式转换传入一个字符串字面量竟然可以通过编译registerUser(Alice);// 默默创建了一个临时的 User 对象增加了心智负担}在上面的代码中registerUser(Alice)能够编译通过是因为编译器在背后做了一次“二段跳”的隐式转换const char*-std::string-User。这虽然看起来很方便但在大型工程中会带来大量的临时对象创建和意料之外的类型混淆。解决方案强制显式调用通过将构造函数标记为explicit我们可以彻底杜绝这种隐式转换classUser{std::string name_;public:// 使用 explicit 修饰不再允许隐式转换explicitUser(std::string name):name_(std::move(name)){}};// registerUser(Alice); // 编译报错registerUser(User(Alice));// 正确必须显式构造意图非常清晰[!TIP]最佳实践除非你非常确定需要隐式转换例如std::string_view的构造函数否则请将所有的构造函数和类型转换运算符Conversion Operators默认声明为explicit。⭐ 专家扩展C20explicit(bool)条件显式在 C20 中引入了explicit(bool)语法。这让我们可以根据模板参数的特征动态地决定一个构造函数是explicit还是隐式转换的。这在编写高度泛型的包装器类如std::optional、std::pair时极为有用#includetype_traitstemplatetypenameTstructWrapper{T value;// 当 T 是可隐式转换为其他类型时Wrapper 也是隐式的// 当 T 必须显式转换时Wrapper 也是 explicit 的templatetypenameUexplicit(!std::is_convertible_vU,T)Wrapper(Uval):value(std::forwardU(val)){}};2.[[nodiscard]]逼着用户正视你的返回值有时候我们调用一个函数只是为了获取它的结果。如果用户忽略了这个结果程序就会发生逻辑错误甚至资源泄漏。 被遗忘的返回值classResource{public:[[nodiscard]]int*release(){// 释放所有权并返回原始指针int*tempptr_;ptr_nullptr;returntemp;}private:int*ptr_newint(10);};voidprocess(){Resource res;res.release();// 编译警告返回值被丢弃了导致内存泄漏} C20 增强带理由说明的[[nodiscard]]从 C20 开始[[nodiscard]]属性可以添加字符串解释并且可以用于修饰构造函数和整个类型。// 1. 修饰类任何返回该类对象的函数其返回值都不能被丢弃struct[[nodiscard(必须处理 ErrorCode 以防止静默失败)]]ErrorCode{intcode;};ErrorCodedoSomething(){returnErrorCode{404};}// 2. 修饰构造函数防止临时对象的创建后立刻被析构如 lock_guard 误用struct[[nodiscard(请将锁对象绑定到命名变量否则临时锁会立刻释放)]]ScopedLock{ScopedLock(){/* 加锁 */}~ScopedLock(){/* 解锁 */}};voidtest(){doSomething();// 编译期警告必须处理 ErrorCode 以防止静默失败ScopedLock();// 编译期警告请将锁对象绑定到命名变量否则临时锁会立刻释放}3.noexcept告诉编译器和调用者你有多“靠谱”noexcept不仅仅是一个“不抛异常”的声明它更是一份强有力的性能与安全契约。 为什么noexcept对 API 性能至关重要在 C 中像std::vector这样的容器在进行扩容Resize时会申请一块新的内存并把老内存中的元素搬运过去。如果你的类的移动构造函数没有声明为noexceptstd::vector为了保证在搬运过程中一旦发生异常能够回滚强异常安全保证就会放弃移动转而采用拷贝构造函数。如果你的移动构造函数是noexcept的它就会使用极快的移动语义从而带来巨大的性能提升classMyData{public:MyData()default;// 必须加上 noexcept否则容器扩容时会退化为拷贝极大地拖累 API 的性能MyData(MyDataother)noexcept{// 移动逻辑...}};4. 砸碎“布尔旗帜汤”利用enum class实现自解释回到文章开头的痛点configureSystem(true, false, true);这种带有多个bool标志位的 API在编写时可能很爽但对于阅读代码的人来说是一场灾难。他们不得不频繁跳转到函数声明去确认参数顺序。重构为强类型枚举// 糟糕的设计// void configureSystem(bool enableCache, bool readOnly, bool debugMode);// 优雅的现代 C 设计enumclassCachePolicy{Enable,Disable};enumclassAccessMode{ReadWrite,ReadOnly};enumclassExecutionMode{Normal,Debug};voidconfigureSystem(CachePolicy cache,AccessMode access,ExecutionMode exec);// 调用端彻底自解释且编译器会在类型不匹配时直接报错configureSystem(CachePolicy::Enable,AccessMode::ReadOnly,ExecutionMode::Debug);[!TIP]黄金法则任何时候只要一个函数的形参列表中连续出现了两个及以上的bool参数或者某个bool参数决定了该函数的核心行为就应当立即重构为enum class。⭐ 专家扩展强类型包装Strong Typedefs防传错有时候我们会遇到多个相同基础类型如double的参数voidsetWindowSize(doublewidth,doubleheight);setWindowSize(1080.0,1920.0);// 一不小心就传反了且编译器无法察觉我们可以利用一个简单的结构体模板来定义强类型包装器从编译期杜绝这种参数传反的逻辑 BugtemplatetypenameT,typenameTagstructStrongType{T value;explicitStrongType(T val):value(val){}};// 使用独特的 Tag 来区分类型structWidthTag{};structHeightTag{};usingWidthStrongTypedouble,WidthTag;usingHeightStrongTypedouble,HeightTag;voidsetWindowSize(Width w,Height h){// 使用 w.value 和 h.value}intmain(){// setWindowSize(Height(1920.0), Width(1080.0)); // 编译报错类型不匹配setWindowSize(Width(1080.0),Height(1920.0));// 正确}5. 告别裸指针的纠缠用类型说明所有权在 C 中裸指针T*包含了太多模糊的信息它指向单个对象还是一个数组它是非空的还是可以为nullptr最致命的谁负责释放它调用者释放还是库释放应该用delete还是free在现代 C API 设计中永远不要在公共接口中使用裸指针来表达所有权关系。所有权传递的现代设计公式是独占共享否, 仅观察允许不允许接口资源传递设计需要所有权转移吗?独占所有权吗?std::unique_ptrstd::shared_ptr允许为空吗?非占有裸指针 T* / std::weak_ptr引用 T独占所有权传递返回或接收std::unique_ptrT。这非常清晰地表达了所有权的“交接棒”。共享所有权传递返回或接收std::shared_ptrT。非占有、只读、不能为空使用引用const T。非占有、只读、可能为空使用指针const T*并在内部做好nullptr检查。6. C23std::expectedMonadic 错误处理的降维打击当 API 发生错误时传统的做法有抛出异常适合无法轻易忽略的灾难性错误但性能开销大在异常路径上且在某些嵌入式或金融场景中被禁用。返回std::optionalT虽然能表达成功与否但一旦失败用户无法得知具体的错误原因。返回全局错误码如GetLastError()多线程不安全极易被忽略。C23 引入了std::expected它就像一个“要么装金子要么装账单”的盒子强制用户必须在编译期或逻辑上安全地拆包。 现代 API 错误处理实战#includeiostream#includestring#includeexpected// C23 引入// 定义错误枚举enumclassParseError{EmptyString,InvalidChar,Overflow};// 接口返回一个 std::expected。要么是解析成功的 int要么是 ParseError[[nodiscard]]std::expectedint,ParseErrorparseNumber(std::string_view str){if(str.empty()){returnstd::unexpected(ParseError::EmptyString);}// 模拟解析逻辑...if(str[0]0||str[0]9){returnstd::unexpected(ParseError::InvalidChar);}return42;// 返回成功值}intmain(){autoresultparseNumber(abc);if(result.has_value()){std::cout解析成功结果是: result.value()\n;}else{// 强制处理错误原因switch(result.error()){caseParseError::EmptyString:std::cout错误: 空字符串\n;break;caseParseError::InvalidChar:std::cout错误: 无效字符\n;break;caseParseError::Overflow:std::cout错误: 数值溢出\n;break;}}}[!IMPORTANT]std::expected的引入使得 C API 的错误处理迈向了函数式Monadic时代通过与[[nodiscard]]配合彻底避免了“忘记检查错误就直接使用脏数据”的经典 Bug。9. 总结优质 API 避坑检查表在提交你的 C 接口代码前不妨拿下面这张清单对照一下防无脑构造所有的单参数构造函数都加上explicit了吗防静默丢弃所有 Getter 函数、资源获取函数、错误码类型都加上[[nodiscard]]了吗防容器拖累类的移动构造函数和移动赋值运算符标记为noexcept了吗防布尔旗帜汤接口参数中是否存在连续的bool能否重构为enum class防指针所有权混淆接口中是否存在可能引起所有权混淆的裸指针T*能否用智能指针或引用代替防错误漏检无法抛异常的接口是否采用了std::expected明确返回成功与错误分支设计优秀的 API 并非一日之功但充分利用 C 的类型系统把规则在编译期锁死是每一位标准 C 专家的必修课。把错误拦在编译阶段你就能给用户也包括未来的你自己送去一份最好的礼物。 长尾关键词布局长尾关键词C API 设计准则、C explicit 显式构造函数、[[nodiscard]] 属性作用、C noexcept 优化原理、C20 条件 explicit、C23 std::expected 错误处理、C 强类型枚举 enum class 最佳实践。
[C++20/API设计] 告别“接口防呆手册”！用这5个现代C++特性，打造“绝不误用”的黄金 API
[!NOTE]导读摘要在 C 开发中接口的误用是导致 Bug 的重灾区。与其编写冗长且无人阅读的“接口防呆说明书”不如利用编译器为我们站岗。本文以 CppCon 2022 上 Jason Turner 的演讲《C API Design》为基础深度剖析如何通过explicit构造函数、[[nodiscard]]属性、noexcept语义、强类型枚举及智能指针让接口在编译期就具备强大的“自我防错”能力。此外本文还将专家级地延伸探讨 C20 条件 explicit、C23 单子式错误处理类型std::expected以及强类型包装Strong Typedefs帮助读者设计出兼具极致性能与安全性的现代 C API。作为 C 程序员我们每天都在跟各种 API 打交道。但你是否遇到过下面这种让人哭笑不得的代码// 程序员 A 写的接口voidconfigureSystem(boolenableCache,boolreadOnly,booldebugMode);// 程序员 B 的调用方式configureSystem(true,false,true);// 谁能一眼看出这三个 bool 分别代表啥或者这种由于隐式转换引发的隐蔽 BugclassTimer{public:Timer(intseconds);// 单参数构造函数未加 explicit};voidrunTask(Timer t);// 某天一个粗心的同事敲下了这行代码runTask(42);// 编译器极其聪明地把 42 隐式转换成了 Timer 对象这真的符合预期吗Scott Meyers 曾在《Effective C》中提出过 API 设计的至高准则“Make APIs easy to use correctly and hard to use incorrectly.”让 API 易于正确使用难于错误使用。在 CppCon 2022 的“Back to Basics: C API Design”演讲中Jason Turner 为我们系统性地梳理了如何用现代 C 特性将这句名言付诸实践。今天我们就来深度聊聊如何利用 C 的类型系统打造一个**“想写错都难”**的黄金 API。1.explicit斩断隐式转换的“越界之手”在 C 中如果一个类拥有一个单参数构造函数或者除了第一个参数外其他参数都有默认值那么这个构造函数默认就成为了一个隐式转换运算符。 隐式转换的灾难#includeiostream#includestringclassUser{std::string name_;public:User(std::string name):name_(move(name)){}// 隐式转换构造函数};voidregisterUser(constUseruser){// 注册逻辑...}intmain(){// 糟糕由于隐式转换传入一个字符串字面量竟然可以通过编译registerUser(Alice);// 默默创建了一个临时的 User 对象增加了心智负担}在上面的代码中registerUser(Alice)能够编译通过是因为编译器在背后做了一次“二段跳”的隐式转换const char*-std::string-User。这虽然看起来很方便但在大型工程中会带来大量的临时对象创建和意料之外的类型混淆。解决方案强制显式调用通过将构造函数标记为explicit我们可以彻底杜绝这种隐式转换classUser{std::string name_;public:// 使用 explicit 修饰不再允许隐式转换explicitUser(std::string name):name_(std::move(name)){}};// registerUser(Alice); // 编译报错registerUser(User(Alice));// 正确必须显式构造意图非常清晰[!TIP]最佳实践除非你非常确定需要隐式转换例如std::string_view的构造函数否则请将所有的构造函数和类型转换运算符Conversion Operators默认声明为explicit。⭐ 专家扩展C20explicit(bool)条件显式在 C20 中引入了explicit(bool)语法。这让我们可以根据模板参数的特征动态地决定一个构造函数是explicit还是隐式转换的。这在编写高度泛型的包装器类如std::optional、std::pair时极为有用#includetype_traitstemplatetypenameTstructWrapper{T value;// 当 T 是可隐式转换为其他类型时Wrapper 也是隐式的// 当 T 必须显式转换时Wrapper 也是 explicit 的templatetypenameUexplicit(!std::is_convertible_vU,T)Wrapper(Uval):value(std::forwardU(val)){}};2.[[nodiscard]]逼着用户正视你的返回值有时候我们调用一个函数只是为了获取它的结果。如果用户忽略了这个结果程序就会发生逻辑错误甚至资源泄漏。 被遗忘的返回值classResource{public:[[nodiscard]]int*release(){// 释放所有权并返回原始指针int*tempptr_;ptr_nullptr;returntemp;}private:int*ptr_newint(10);};voidprocess(){Resource res;res.release();// 编译警告返回值被丢弃了导致内存泄漏} C20 增强带理由说明的[[nodiscard]]从 C20 开始[[nodiscard]]属性可以添加字符串解释并且可以用于修饰构造函数和整个类型。// 1. 修饰类任何返回该类对象的函数其返回值都不能被丢弃struct[[nodiscard(必须处理 ErrorCode 以防止静默失败)]]ErrorCode{intcode;};ErrorCodedoSomething(){returnErrorCode{404};}// 2. 修饰构造函数防止临时对象的创建后立刻被析构如 lock_guard 误用struct[[nodiscard(请将锁对象绑定到命名变量否则临时锁会立刻释放)]]ScopedLock{ScopedLock(){/* 加锁 */}~ScopedLock(){/* 解锁 */}};voidtest(){doSomething();// 编译期警告必须处理 ErrorCode 以防止静默失败ScopedLock();// 编译期警告请将锁对象绑定到命名变量否则临时锁会立刻释放}3.noexcept告诉编译器和调用者你有多“靠谱”noexcept不仅仅是一个“不抛异常”的声明它更是一份强有力的性能与安全契约。 为什么noexcept对 API 性能至关重要在 C 中像std::vector这样的容器在进行扩容Resize时会申请一块新的内存并把老内存中的元素搬运过去。如果你的类的移动构造函数没有声明为noexceptstd::vector为了保证在搬运过程中一旦发生异常能够回滚强异常安全保证就会放弃移动转而采用拷贝构造函数。如果你的移动构造函数是noexcept的它就会使用极快的移动语义从而带来巨大的性能提升classMyData{public:MyData()default;// 必须加上 noexcept否则容器扩容时会退化为拷贝极大地拖累 API 的性能MyData(MyDataother)noexcept{// 移动逻辑...}};4. 砸碎“布尔旗帜汤”利用enum class实现自解释回到文章开头的痛点configureSystem(true, false, true);这种带有多个bool标志位的 API在编写时可能很爽但对于阅读代码的人来说是一场灾难。他们不得不频繁跳转到函数声明去确认参数顺序。重构为强类型枚举// 糟糕的设计// void configureSystem(bool enableCache, bool readOnly, bool debugMode);// 优雅的现代 C 设计enumclassCachePolicy{Enable,Disable};enumclassAccessMode{ReadWrite,ReadOnly};enumclassExecutionMode{Normal,Debug};voidconfigureSystem(CachePolicy cache,AccessMode access,ExecutionMode exec);// 调用端彻底自解释且编译器会在类型不匹配时直接报错configureSystem(CachePolicy::Enable,AccessMode::ReadOnly,ExecutionMode::Debug);[!TIP]黄金法则任何时候只要一个函数的形参列表中连续出现了两个及以上的bool参数或者某个bool参数决定了该函数的核心行为就应当立即重构为enum class。⭐ 专家扩展强类型包装Strong Typedefs防传错有时候我们会遇到多个相同基础类型如double的参数voidsetWindowSize(doublewidth,doubleheight);setWindowSize(1080.0,1920.0);// 一不小心就传反了且编译器无法察觉我们可以利用一个简单的结构体模板来定义强类型包装器从编译期杜绝这种参数传反的逻辑 BugtemplatetypenameT,typenameTagstructStrongType{T value;explicitStrongType(T val):value(val){}};// 使用独特的 Tag 来区分类型structWidthTag{};structHeightTag{};usingWidthStrongTypedouble,WidthTag;usingHeightStrongTypedouble,HeightTag;voidsetWindowSize(Width w,Height h){// 使用 w.value 和 h.value}intmain(){// setWindowSize(Height(1920.0), Width(1080.0)); // 编译报错类型不匹配setWindowSize(Width(1080.0),Height(1920.0));// 正确}5. 告别裸指针的纠缠用类型说明所有权在 C 中裸指针T*包含了太多模糊的信息它指向单个对象还是一个数组它是非空的还是可以为nullptr最致命的谁负责释放它调用者释放还是库释放应该用delete还是free在现代 C API 设计中永远不要在公共接口中使用裸指针来表达所有权关系。所有权传递的现代设计公式是独占共享否, 仅观察允许不允许接口资源传递设计需要所有权转移吗?独占所有权吗?std::unique_ptrstd::shared_ptr允许为空吗?非占有裸指针 T* / std::weak_ptr引用 T独占所有权传递返回或接收std::unique_ptrT。这非常清晰地表达了所有权的“交接棒”。共享所有权传递返回或接收std::shared_ptrT。非占有、只读、不能为空使用引用const T。非占有、只读、可能为空使用指针const T*并在内部做好nullptr检查。6. C23std::expectedMonadic 错误处理的降维打击当 API 发生错误时传统的做法有抛出异常适合无法轻易忽略的灾难性错误但性能开销大在异常路径上且在某些嵌入式或金融场景中被禁用。返回std::optionalT虽然能表达成功与否但一旦失败用户无法得知具体的错误原因。返回全局错误码如GetLastError()多线程不安全极易被忽略。C23 引入了std::expected它就像一个“要么装金子要么装账单”的盒子强制用户必须在编译期或逻辑上安全地拆包。 现代 API 错误处理实战#includeiostream#includestring#includeexpected// C23 引入// 定义错误枚举enumclassParseError{EmptyString,InvalidChar,Overflow};// 接口返回一个 std::expected。要么是解析成功的 int要么是 ParseError[[nodiscard]]std::expectedint,ParseErrorparseNumber(std::string_view str){if(str.empty()){returnstd::unexpected(ParseError::EmptyString);}// 模拟解析逻辑...if(str[0]0||str[0]9){returnstd::unexpected(ParseError::InvalidChar);}return42;// 返回成功值}intmain(){autoresultparseNumber(abc);if(result.has_value()){std::cout解析成功结果是: result.value()\n;}else{// 强制处理错误原因switch(result.error()){caseParseError::EmptyString:std::cout错误: 空字符串\n;break;caseParseError::InvalidChar:std::cout错误: 无效字符\n;break;caseParseError::Overflow:std::cout错误: 数值溢出\n;break;}}}[!IMPORTANT]std::expected的引入使得 C API 的错误处理迈向了函数式Monadic时代通过与[[nodiscard]]配合彻底避免了“忘记检查错误就直接使用脏数据”的经典 Bug。9. 总结优质 API 避坑检查表在提交你的 C 接口代码前不妨拿下面这张清单对照一下防无脑构造所有的单参数构造函数都加上explicit了吗防静默丢弃所有 Getter 函数、资源获取函数、错误码类型都加上[[nodiscard]]了吗防容器拖累类的移动构造函数和移动赋值运算符标记为noexcept了吗防布尔旗帜汤接口参数中是否存在连续的bool能否重构为enum class防指针所有权混淆接口中是否存在可能引起所有权混淆的裸指针T*能否用智能指针或引用代替防错误漏检无法抛异常的接口是否采用了std::expected明确返回成功与错误分支设计优秀的 API 并非一日之功但充分利用 C 的类型系统把规则在编译期锁死是每一位标准 C 专家的必修课。把错误拦在编译阶段你就能给用户也包括未来的你自己送去一份最好的礼物。 长尾关键词布局长尾关键词C API 设计准则、C explicit 显式构造函数、[[nodiscard]] 属性作用、C noexcept 优化原理、C20 条件 explicit、C23 std::expected 错误处理、C 强类型枚举 enum class 最佳实践。
