Item 18：让接口容易被正确使用，不易被误用

从调用者的失败开始设计

接口设计不能只问“实现者能否完成工作”，还要问“调用者最自然写出的代码是否正确”。下面的构造器可以编译，却把三种不同概念都压成了 int：

class Date {
public:
    Date(int month, int day, int year);
};
 
Date release(30, 2, 2026); // 次序和取值都错，但类型系统沉默

参数名只对阅读声明的人有帮助，调用点只剩三个整数。注释、文档和 code review 可以降低概率，却不能封闭错误路径。

Item 18 的原始原则是：Make interfaces easy to use correctly and hard to use incorrectly（让接口容易被正确使用，不易被误用）。目标不是让所有错误不可能发生，而是让正确路径阻力最小，让高频误用尽早失败。

先预测：如果把参数、合法值和释放责任都留给调用者记忆，哪一种错误会最晚才暴露？用下面三步把“自然写错的调用”推到更早的边界。

把不同概念变成不同类型

month、day、year 都能用整数存储，不代表它们应该共享同一个接口类型。

class Day {
public:
    explicit Day(unsigned value);
    unsigned value() const noexcept;
private:
    unsigned value_;
};
 
class Year {
public:
    explicit Year(int value) : value_(value) {}
private:
    int value_;
};
 
class Date {
public:
    Date(Month month, Day day, Year year);
};

现在 Date{Day{30}, Month::Feb(), Year{2026}} 因参数类型错位不能编译。strong types（强类型）把“记住参数顺序”改造成 compiler obligation。

强类型应保持轻量：值语义、明确构造、便宜复制，并只暴露领域需要的操作。若类型只是给 int 换名字但仍允许任意隐式转换，防线并未建立。

让无效值难以构造

类型不同只解决参数互换，Month{37} 仍可能制造无效状态。接口还应控制合法值的产生方式。

class Month {
public:
    static Month Jan() noexcept { return Month{1}; }
    static Month Feb() noexcept { return Month{2}; }
    static std::optional<Month> fromInt(unsigned value) noexcept;
 
    unsigned value() const noexcept { return value_; }
 
private:
    explicit Month(unsigned value) : value_(value) {}
    unsigned value_;
};

固定集合可使用 named factory 或 enum class；外部输入走 fromInt，失败以 optional、expected 或项目统一错误类型表达。成功得到 Month 后，内部函数不应反复检查 1 到 12。

日期还存在“二月没有 30 日”这种跨字段约束。可以让 Date::create 集中验证，而不是让每个业务函数猜测对象是否合法。

正确路径必须比逃生口更顺手

如果安全 API 需要五步配置，而危险 API 只需一行，调用者迟早会选危险入口。安全路径应成为默认、简短且可发现的入口。

auto request = Request::json(endpoint, payload)
                   .withTimeout(Seconds{2});
 
client.send(request); // request 已满足发送不变量

高级逃生口可以存在，但应在名称和类型上明确，例如 unsafeFromUncheckedBytes，并限制到基础设施层。不要让普通调用和绕过验证共享同名重载。

一致性减少接口猜测

原书强调 consistency（一致性）。用户已经熟悉标准库和项目中的既有习惯，新的接口应复用这些习惯，而不是创造局部方言。

若容器普遍使用 size()、empty() 和半开区间，新容器就不要改叫 count()、isEmpty() 并使用闭区间。若项目 factory 统一返回 typed owner，新 factory 就不要返回 raw pointer。差异必须来自语义差异，而不是作者偏好。

for (auto it = values.begin(); it != values.end(); ++it) {
    consume(*it);
}
 
if (!values.empty()) {
    reserve(values.size());
}

一致性不是机械模仿。若操作可能失败，不能为了看起来像 vector::operator[] 而隐藏错误；应选择符合真实语义且全项目统一的错误模型。

返回类型要携带下一步责任

函数返回值不只传数据，也应表达调用者必须做什么。返回 raw pointer 会同时留下多个问题：能否为空、谁拥有、如何释放、能否跨模块删除。

std::unique_ptr<Document> openDocument(Path path);
std::optional<UserId> findUser(Name name);
Result<Config, ParseError> parseConfig(TextView text);

unique_ptr 表示单一 ownership；optional 表示“无结果不是错误”；Result 区分成功值与失败原因。调用者不需要另查文档判断返回值责任。

返回类型还应阻止忽略关键结果。可用 [[nodiscard]] 标记错误或事务提交结果，但它只是提醒，不能替代清晰的类型和生命周期模型。

防止裸资源协议泄漏到业务层

外部 API 常给出 acquire/release、open/close 或 handle。包装层应一次完成配对，业务层只看到 owner 与 borrow。

struct FileCloser {
    void operator()(std::FILE* file) const noexcept {
        if (file) std::fclose(file);
    }
};
 
using FileOwner = std::unique_ptr<std::FILE, FileCloser>;
 
FileOwner openFile(const char* path) {
    FileOwner file{std::fopen(path, "rb")};
    if (!file) throw FileOpenError{path};
    return file;
}

调用者不能把 FileOwner 误传给普通 delete，也无需记住 fclose。这正是“接口不易被误用”：把协议放进类型，而不是散落在调用点。

跨 DLL 的 new/delete 边界

跨 DLL new delete（cross-dll new delete）尤其危险。动态库和应用可能使用不同 CRT、allocator、编译选项或 class-specific delete。对象在库内 new，却在应用侧直接 delete，可能造成 heap corruption，即使类型声明完全一致。

库应同时导出 create/destroy，并把 destroy 固化进 owner：

// library API
extern "C" ApiObject* create_api_object();
extern "C" void destroy_api_object(ApiObject*) noexcept;
 
struct ApiDeleter {
    void operator()(ApiObject* object) const noexcept {
        destroy_api_object(object);
    }
};
 
using ApiOwner = std::unique_ptr<ApiObject, ApiDeleter>;
 
ApiOwner makeApiObject() {
    return ApiOwner{create_api_object()};
}

更稳定的 ABI 可以导出 opaque handle 和 C 函数，而不让 C++ class layout、异常或 STL 类型穿过模块边界。关键不是选哪种语法，而是应用永远没有“直接 delete 库对象”这条自然路径。

错误模型也属于接口一致性

同一层 API 不应有的函数抛异常、有的返回 bool、有的写 thread-local error。混合模型迫使调用者为每个函数记忆特殊规则，最终出现漏检。

选择异常、Result 或 status code 要结合边界和性能，但需要统一：

• 构造成功即满足 invariant，失败不发布半成品对象。
• 可恢复失败携带可诊断信息，不以 magic value 混入正常值域。
• destructor、deleter 和 rollback 路径保持 noexcept。
• C ABI 边界拦截异常，转换为该边界约定的错误类型。

兼容旧接口时建立迁移通道

改善接口常遇到旧调用点。不要同时长期维护两套等价但语义不同的入口，否则一致性继续恶化。

[[deprecated("use Date::create(Month, Day, Year)")]]
Date legacyDate(int month, int day, int year);

迁移可以先让旧函数内部调用新实现，再批量改调用点；CI 把新增 deprecated 使用视为失败；到约定版本删除旧入口。adapter 只负责兼容，不应成为永久双轨设计。

用负例证明接口真的难以误用

普通单元测试只证明正确调用能工作，Item 18 还需要验证错误调用无法穿过边界。

先预测每个错误在哪一层失败，再建立测试矩阵：

• 编译期负例：Day 与 Month 交换、raw int 隐式转换、复制 unique owner。
• 边界值：Month 0/1/12/13，闰年日期，联合字段非法组合。
• ownership ledger：每次 create 都有且仅有一次 destroy，失败路径不发布 handle。
• DLL 集成：真实发布配置创建、移动 owner、借用、销毁，释放回调地址来自库模块。
• API consistency：静态检查命名、返回类型和 deprecated 新增使用。
• fuzz：随机 wire input 只能得到合法领域对象或明确错误，不能产生半有效状态。

测试目标不是覆盖实现行数，而是证明不变量从输入边界一直延续到释放边界。

小结

• Item 18 要求接口容易被正确使用、不易被误用，设计从调用者的自然路径出发
• strong types 阻止同表示不同语义的参数互换，validating factory 阻止无效值进入核心
• consistency 让标准库和项目经验可迁移，减少每个调用点的特殊记忆
• 返回类型应表达 ownership、可空性和错误，factory 在返回前完成资源绑定
• 跨 DLL 对象由创建模块提供 destroy，typed owner 携带 module-bound deleter
• misuse-oriented test 同时验证编译期负例、边界输入和 create/destroy 配对