前言「API 设计」听起来像是架构师才需要操心的事但落到 C 代码里它其实就是一连串具体的、有对错的技术决定这个函数该按值传还是按引用传返回const std::string还是std::string这个类要不要写析构函数错误怎么报这些决定每一条都能用编译器检查出来而不是靠评审时互相劝说。一个常见的误解是把「API 设计」等同于「命名好听、注释写全」。命名当然重要但 C API 的失败大多是类型层面的失败——调用点看不出true是什么意思、拿到的引用在下一行就悬垂了、基类少了个virtual析构导致delete时只析构一半、第三方的库升级一个次版本号就 ABI 断裂需要全量重编。这些问题注释救不了类型和头文件布局才能救。本文不讲抽象的「设计原则」只讲四件可以直接写进代码的事把所有权和 const 写进签名、把参数和返回值设计成不会误用、用 PIMPL 把实现的二进制接口钉死、以及错误处理策略怎么选。所有示例以 C17 为基准逐行推演过类型匹配与 const 正确性涉及 C23 的设施会明确标注并给出 C17 的替代写法。一、把所有权与 const 写进签名API 契约里最容易含糊的两件事是「这个对象归谁」和「这个函数会不会改我传进去的东西」。含糊的结果就是调用方凭猜测写代码而猜测总有猜错的那一半。先看值语义value semantics与引用语义reference semantics的表达。C 里最省心的做法是参数用const表示只读借用返回值用值表示「给你一份新的」用const返回成员只在调用方确实需要零拷贝、且对象生命周期明显长于引用时使用。#include string #include utility class Config { public: Config(std::string name, int threads) : name_(std::move(name)), threads_(threads) {} // 只读借用调用方不能改也不会得到一份拷贝 const std::string name() const noexcept { return name_; } int threads() const noexcept { return threads_; } // 需要修改时给一个明确的 setter而不是返回非 const 引用 void set_threads(int n) noexcept { threads_ n; } private: std::string name_; int threads_; };这里每一个决定都是有后果的name()返回const std::string而不是std::string避免了每次调用都拷贝一次字符串代价是调用方不能把这个引用存到Config对象销毁之后threads()返回int而不是const int因为返回引用反而更慢也更容易出问题set_threads用noexcept标注因为它是纯赋值这给调用方以及标准容器提供了额外信息。所有权方面把「谁负责 delete」直接编码进返回类型返回值写法表达的所有权语义适用场景T调用方拿到独立副本全权负责小对象、值语义const T借用生命周期绑在源对象上成员访问、大对象只读std::unique_ptrT独占所有权被移交调用方必须接管工厂函数std::shared_ptrT共享所有权最后一个引用负责释放确实需要共享生命周期时T*不表达任何所有权借用或未定只在参数位置、且有文档约定时一个完整可编译的小例子演示所有权如何影响调用点#include iostream #include memory #include string class Logger { public: explicit Logger(std::string tag) : tag_(std::move(tag)) {} void log(const std::string msg) const { std::cout [ tag_ ] msg \n; } private: std::string tag_; }; // 返回 unique_ptr语义清晰调用方接管 std::unique_ptrLogger make_logger(std::string tag) { return std::unique_ptrLogger(new Logger(std::move(tag))); } int main() { std::unique_ptrLogger lp make_logger(net); lp-log(connected); // 可以用 - // Logger* raw lp.get(); // 借用可以但不要 delete raw return 0; }注意make_logger里写的是std::unique_ptrLogger(new Logger(...))而不是std::make_uniqueLogger(...)两者都能编过后者更好异常安全、少一次显式new。本文之所以偶尔写展开形式是为了让你看清所有权是从哪里转手的。二、参数与返回值让误用编不过2.1 布尔参数是 API 里的定时炸弹// ❌ 调用点Connect(host, 443, true, false) —— true 和 false 是什么 void Connect(const std::string host, int port, bool use_tls, bool blocking);调用点看不出实参含义而且一旦以后要加第三种模式这个签名就没法演进了。用强类型strong typedef / 枚举替换#include string enum class Tls { kDisabled, kEnabled }; enum class Mode { kBlocking, kNonBlocking }; void Connect(const std::string host, int port, Tls tls, Mode mode); int main() { Connect(example.com, 443, Tls::kEnabled, Mode::kBlocking); return 0; }enum class不会隐式转换到int两个枚举之间也不会互相转换所以Connect(h, 443, Mode::kBlocking, Tls::kEnabled)会直接编译报错——这正是我们想要的。2.2 输入参数优先用std::string_viewC17 起只读字符串参数应该用std::string_view需要 C17用 C11/14 时退回const std::string。它既能接收std::string也能接收const char*和字面量且不拷贝#include string_view // 需要 C17 bool StartsWith(std::string_view s, std::string_view prefix) { return s.size() prefix.size() s.compare(0, prefix.size(), prefix) 0; }std::string_view的危险在于它不拥有数据。下面这种写法会悬垂// ❌ 临时 std::string 在整条声明语句结束时就被销毁sv 从此悬垂 std::string_view sv std::string(hello); // ✅ 先有命名的 owner再取 view std::string owned hello; std::string_view ok owned;悬垂之后任何对sv的读取都是未定义行为UB标准不保证任何结果它可能「看起来正常」也可能崩取决于栈上残留内容。2.3 返回值用std::optional/std::variant表达「可能没有」C23 有std::expected是表达「值或错误」最直接的类型但我们以 C17 为基准用std::variant能达到同样效果只是写起来啰嗦一点#include string #include string_view #include variant #include iostream enum class ParseError { kEmpty, kBadChar, kOverflow }; std::variantint, ParseError ParseInt(std::string_view s) { if (s.empty()) { return ParseError::kEmpty; } int value 0; for (char c : s) { if (c 0 || c 9) { return ParseError::kBadChar; } value value * 10 (c - 0); } return value; } int main() { std::variantint, ParseError r ParseInt(42); if (auto* p std::get_ifint(r)) { // 命中第一个分支 std::cout value *p \n; } else { switch (std::getParseError(r)) { case ParseError::kEmpty: std::cout empty\n; break; case ParseError::kBadChar: std::cout bad char\n; break; case ParseError::kOverflow: std::cout overflow\n; break; } } return 0; }std::get_ifint(r)接收的是variant的指针返回int*没有命中时返回空指针这是不抛异常的分支写法std::getParseError(r)在类型不匹配时会抛std::bad_variant_access所以它只能放在已经确定类型的分支里。三、PIMPL把 ABI 钉在头文件之外只要库的头文件里出现了成员变量你的 ABIapplication binary interface二进制接口就被钉死了改一个成员的类型、加一个成员、甚至调换两个成员的顺序都会改变对象大小和布局所有已经编译好的调用方代码都必须重编。PIMPLpointer to implementation也叫 opaque pointer把实现挪到.cpp里头文件只剩下一个指针。// widget.h #pragma once #include memory #include string class Widget { public: explicit Widget(std::string title); ~Widget(); // 必须声明并在 .cpp 里定义 Widget(Widget) noexcept; // 移动操作同样要 out-of-line Widget operator(Widget) noexcept; Widget(const Widget); // 需要拷贝语义时自己定义 Widget operator(const Widget); void SetTitle(std::string title); const std::string Title() const; private: struct Impl; // 只声明不定义 std::unique_ptrImpl impl_; };// widget.cpp #include widget.h #include utility struct Widget::Impl { std::string title; }; Widget::Widget(std::string title) : impl_(new Impl{std::move(title)}) {} Widget::~Widget() default; // Impl 在这里才是完整的 Widget::Widget(Widget) noexcept default; Widget Widget::operator(Widget) noexcept default; Widget::Widget(const Widget other) : impl_(new Impl{*other.impl_}) {} Widget Widget::operator(const Widget other) { if (this ! other) { impl_.reset(new Impl{*other.impl_}); } return *this; } void Widget::SetTitle(std::string title) { impl_-title std::move(title); } const std::string Widget::Title() const { return impl_-title; }这里的析构函数不能在头文件里写 default也不能省略std::unique_ptr的析构会实例化std::default_deleteImpl::operator()那一刻Impl必须是完整类型而头文件里它只是个前置声明。这是 PIMPL 最经典的一处编译错误也是绝大多数人第一次写 PIMPL 会撞上的墙。代价是多了一次指针间接寻址和一次堆分配换回来的是「改实现不用重新编译调用方」。四、错误处理与 API 演进错误处理策略必须在 API 定义的第一天就定下来因为改它等于改所有调用点。三条路线策略表达方式优点代价异常抛出自定义异常类型不污染返回值无法被忽略需要异常安全保证有的项目禁用异常返回值编码std::optional/std::variant显式、无异常开销每个调用点都得处理容易漏错误码输出参数ErrorCode* out兼容 C 风格调用点容易传nullptr忽略选哪一种都可以但不能混着来也不能让「错误」悄无声息地退化成某个哨兵值比如返回-1表示失败因为哨兵值一定会被漏判。演进方面有两条几乎不会出错的规则。第一给函数加参数时用新名字而不是新默认参数默认参数是接口的一部分改默认值会静默改变所有没显式传参的调用点的行为。第二重载要出于语义不要出于便利Draw(int)和Draw(const char*)这种「参数类型不同、语义也不同」的重载会让Draw(0)调用到指针版本——因为0是空指针常量。用nullptr和强类型可以避免这类歧义。#include string struct Shape { virtual ~Shape() default; // 基类必须有虚析构 virtual void Draw() const 0; }; struct Circle : Shape { void Draw() const override { /* ... */ } };virtual ~Shape() default;是这条 API 的硬性契约少了它通过Shape*删除Circle对象就是未定义行为标准不保证Circle的析构函数被调用。常见坑点1. 虚函数的默认参数按静态类型绑定struct Base { virtual void f(int x 1) { /* ... */ } }; struct Derived : Base { void f(int x 2) override { /* ... */ } }; // ❌ 通过 Base* 调用用的是 Base 里写的默认值 1而不是 Derived 的 2 Base* p new Derived; p-f(); // 实参是 1进入 Derived::f(1) // ✅ 虚函数不要带默认参数或者额外提供无参重载默认参数是编译期在调用点替换的虚函数分派是运行期的两者不在一个时间轴上。2. 返回成员的引用然后返回给了临时对象// ❌ 拿到引用后源对象先一步销毁引用悬垂之后读取是 UB const std::string ref make_config().name(); // make_config 返回的临时对象已析构 // ✅ 跨语句保存时按值取回一份 std::string copy make_config().name();3. 非 explicit 的单参构造函数吃掉隐式转换// ❌ 任何 int 都能悄悄变成 Meters包括函数重载解析里 struct Meters { Meters(double v); double v; }; void Move(Meters m); // Move(42); // 44 行以外看不出这里发生了类型转换 // ✅ struct Meters { explicit Meters(double v) : v(v) {} double v; }; // Move(42); // 现在编不过必须 Move(Meters{42}) Move(Meters{42});4. PIMPL 里忘了 out-of-line 析构// ❌ 头文件里直接写Impl 此时不完整 → 编译错误 class Widget { ~Widget() default; struct Impl; std::unique_ptrImpl impl_; }; // ✅ 头文件只声明.cpp 里定义 Widget::~Widget() default;5.std::string_view绑定了临时对象// ❌ 整条声明语句结束后临时 std::string 销毁view 悬垂后续读取是 UB std::string_view sv std::string(tmp); // ✅ std::string owner tmp; std::string_view sv owner;6. 给std::vector之类的容器按值返回对象时误以为返回引用更快// ❌ 返回引用指向局部变量悬垂UB const std::vectorint Make() { std::vectorint v{1,2,3}; return v; } // ✅ 按值返回靠 NRVO/移动语义不额外拷贝 std::vectorint Make() { std::vectorint v{1,2,3}; return v; }7. 头文件里放using namespace std;// ❌ 污染所有包含它的翻译单元可能让别人的 std::size 之类的名字与自己的重载冲突 using namespace std; // ✅ 头文件里全部写全名或用窄作用域 using using std::string; // 放在 .cpp 里8. 重载出于「便利」而非「语义」// ❌ Draw(0) 会调用指针版本因为 0 是空指针常量 void Draw(int x); void Draw(const char* s); // ✅ 用 nullptr 和强类型别让字面量 0 有歧义 void Draw(Index i); void Draw(const char* name);总结设计点不要这样应该这样只读参数std::string s按值传std::string_view或const std::string只读成员访问返回std::string拷贝返回const std::string并约定生命周期布尔/模式参数bool use_tlsenum class Tls工厂函数返回裸指针返回std::unique_ptr「可能失败」返回-1哨兵std::optional/std::variantC23 用std::expected类布局稳定性成员直接写在头文件PIMPL out-of-line 析构基类无虚析构virtual ~Base() default;