设计良好的C++ API应通过强类型、explicit构造、enum class等机制阻止错误，确保接口行为符合预期，命名清晰，避免隐式转换和副作用，保持接口一致并利用RAII、默认参数和工厂函数降低使用难度，最终实现易于正确使用且难以误用的目标。
设计良好的C++ API 不仅要功能正确，更要让调用者用得顺手、不易出错。关键在于降低认知负担，提高接口的自解释性，并通过语言机制限制错误使用。以下是构建易于使用、难以误用接口的核心实践。
1. 让合法用法容易，非法用法难以编译
好的API应通过类型系统和编译时检查阻止常见错误。
建议：- 使用强类型代替原始类型。例如，用
struct UserId { int id; };替代int，避免参数位置错乱。 - 利用
explicit防止隐式转换，尤其是单参数构造函数。 - 删除或禁用不支持的操作，如禁止拷贝时使用
= delete。 - 用
enum class替代 C 风格枚举，防止作用域污染和意外比较。
2. 接口行为应符合最小惊讶原则
用户应能根据函数名和参数推测其行为，避免隐藏副作用。
建议：- 命名清晰明确。例如，
open()应打开资源，而不是同时读取数据。 - const 成员函数不应修改对象 observable 状态。
- 避免重载语义差异大的函数。比如一个
add()既可添加数字又可连接字符串，容易混淆。 - 输入输出参数通过引用传递时，使用指针或带
out前缀的命名（如getUsername(std::string* out_name)）表明意图。
3. 提供一致且有限的接口
一致性减少记忆成本，接口精简降低出错概率。
立即学习“C++免费学习笔记（深入）”；
建议：- 同类操作使用统一命名模式，如
begin()/end()、empty()、size()。 - 优先返回值语义或智能指针，避免让用户手动释放资源。
- 提供 RAII 封装，如文件句柄、锁等，确保资源自动管理。
- 公开接口尽量只暴露必要成员，隐藏实现细节。
4. 利用编译器帮助用户写对代码
静态断言、概念（C++20）和默认参数能引导正确使用。
建议：- 在模板中使用
static_assert检查类型约束。 - 为常用场景提供默认参数，减少调用负担。
- C++20 起可用
concepts明确模板参数要求，提升错误信息可读性。 - 提供工厂函数替代复杂构造，隐藏内部构造逻辑。
基本上就这些。关键是站在调用者角度思考：他们怎么最容易理解？什么最容易搞错？然后用类型、语法和设计去预防。C++ 的强大机制不只是为了灵活，更是为了写出“安全”的接口。
