API 的承诺跨出了仓库
前面讨论重构时,我们假设能够更新仓库中的已知调用者。公开 API 则多了一层约束:调用者可能从未见过,也无法同步修改。即使自己的测试全部通过,改名或交换参数后,别人的程序仍可能已经无法运行。
API 的表面包括签名、行为、错误和数据格式。边界后面的存储和算法可以替换,边界上的承诺则需要谨慎演进。应明确公开范围,避免辅助接口意外成为长期承诺。
以 REST 风格 HTTP API 为例,资源路径、HTTP 方法、JSON 结构与状态码共同构成边界。GET 读取、POST 创建等约定帮助调用者理解行为,每次请求也要携带令牌等所需信息。API 不只供人阅读,代码生成工具与 Agent 还会直接根据文档、类型和例子编写客户端。
课件用 make 的制表符历史说明:哪怕最初只有少量用户,一个偶然选择也可能变成难以移除的兼容要求。因此要显式标记公开导出与内部接口;多暴露一个辅助函数,就可能多出一批无法同步更新的调用者。
让正确调用成为自然选择
一致的命名、默认值和示例帮助人和 Agent 推断用法。重复概念采用不同动词、单位不明确的数值,以及能交换顺序的同类型参数,都可能诱发错误。
课件中的 book(a, b, c, d, flag) 改为接收 BookingRequest,包含用户标识、会议室标识和经过验证的时间区间。类型与构造入口可以排除一部分非法状态,网络输入仍需要在边界验证。

补充说明:TypeScript 中两个普通 string 别名仍然可以互换,需要品牌类型或包装对象等方式建立区分;一个 TimeRange 也需要保护构造和可变状态,才能持续保持区间有效。课件表达的是约束方向,具体语言实现仍需核实。
错误同样属于契约。状态码、失败形式和检查顺序变化,都可能破坏调用者的分支。文档示例也会被直接复制,应像代码一样检查。让一个只有文档上下文的 Agent 编写客户端,可以帮助发现 API 的歧义。
课件中的 Java 例子展示了“能编译”与“含义正确”的距离:Calendar.set(2026, 10, 5) 中月份从零开始,List<Integer>.remove(1) 按位置删除,而传入 Integer.valueOf(1) 才按值删除;Thread.interrupted() 查询后还会清除标志。调用者靠名称猜中一个真实方法,也可能得到错误行为。
明确类型可以提前消除一部分错误。例如用 Duration 表示时间单位,用枚举代替任意整数颜色,用受保护的构造入口建立有效区间。需要注意,readonly Date 也不使 Date 对象本身不可变;如果外部仍能修改对象内容,构造时通过的约束以后仍可能失效。这是对课件区间示例的实现层补充。
文档同样在传递默认用法。示例一旦被复制,里面的安全缺陷也会被复制。有效错误消息应说明期望格式与实际输入,例如日期单位不匹配,而不是一律返回“无效输入”。
小接口与行为替换
接口隔离原则(ISP)要求调用者不依赖自己不用的方法。只需要查询的候补模块,可以依赖 BookingReader,无需同时承担写入接口的变化。
里氏替换原则(LSP)则要求实现满足其声称的行为。一个实现了 BookingStore、但 save() 总抛出“不支持”的只读存储,虽然可以编译,仍违反写入承诺。契约测试应对每个实现执行相同检查。
演进需要考虑隐含依赖
Hyrum’s Law 提醒我们,用户可能依赖所有可观察行为,包括未明确承诺的顺序、错误文本和字段。使用者越多,接口越难修改。
新增周期预约时,把 book() 返回值从单个预约改成数组,会破坏原调用者。增加独立操作通常更容易保留原有语义。新增字段是否兼容,也取决于读取者能否容忍未知字段,不能只看“增加”两个字。
废弃接口需要替代方案、并行运行、迁移步骤和明确时间。迁移脚本、兼容说明及端到端验证,可以降低调用者成本。
契约测试只观察实现是否兑现承诺,因此可以跨越重构与重生成。真实数据库的约束、权限和供应商错误,不宜完全依靠自写替身模拟;外部邮件、付款等副作用则适合替换,并检查替身自身是否遵守契约。
兼容性还要看变化的语义。新增可选字段只有在读取者容忍未知字段时才安全;新增错误子类也要看原调用者如何捕获。语义版本号表达发布者的意图,却不能代替实际客户端检查。
本讲的取消练习更容易暴露这个问题。旧客户端调用 cancel(id),没有异常就显示“已取消”;新要求增加原因和取消费,且付款前预约仍有效。若继续返回 void 却悄悄改成等待付款,旧客户端仍能运行,却会给出错误提示。需要设计能够表达新状态的操作或结果,并明确旧操作的兼容安排。
对无法控制的调用者,可以先公布替代入口与移除日期,让新旧接口并存,提供机械迁移脚本或清楚步骤。消费者驱动契约则把下游团队的真实期待变成测试。无论重构还是重新生成,边界检查都应继续运行。
审查 API 时,课件建议按名称、类型、错误、扩展空间与客户端代码依次检查。让一个新上下文只读文档编写调用代码,可以暴露隐藏假设,但生成的客户端仍需核对,不能把它的成功编译当成契约完备。
库与框架改变控制权

库是应用主动调用的工具,框架则安排结构和调用时机,让应用在扩展点提供代码。浏览器事件、Express 路由和测试生命周期都体现了这种控制反转。框架提供约定,也使代码更难迁移出去。
Template Method 用基类固定导入流程,由子类实现解析步骤;Strategy 用组合替换解析器。前者适合步骤由框架确定的情境,后者便于独立测试、运行时替换和组合。
Adapter 则包装无法修改的外部 SDK,把供应商调用转换为自己的端口。它隔离技术细节,但自己的接口没有表达的供应商能力,也不会自动暴露出来。
导入流程可以具体读成 parse → validate → store。Template Method 让基类固定顺序,子类提供 CSV 或 JSON 解析步骤;Strategy 则把解析器作为协作者传入。前者与基类协议绑定,后者可独立替换与测试。框架可能分别采用继承式扩展与接口委派式扩展,区别在于应用怎样嵌入它已经决定的控制流程。
Adapter 也不是完整复制供应商 API。Notifier.send(to, message) 可以隐藏 Mailgun 的 payload 构造,但若自己的端口没有调度发送能力,就不能自动使用供应商的预约投递。隔离细节的同时,也选择了对业务公开哪些能力。
复用与生成都需要负责
成熟依赖能够复用标准与边界经验,也会带来权限、更新和传递依赖成本。自写一个简单每周预约规则可能很短,支持完整日历标准、时区和夏令时则是更大的问题。
因此要判断实际需要多少语义、谁维护、错误会影响什么。Agent 既可能重复实现项目已有能力,也可能为单一函数引入庞大依赖。依赖变更应回到这些具体问题上评审。
课件用“每周二 10:00—11:00,持续到指定日期并跳过某一天”比较日历库与自写规则。只支持当前每周规则,与支持任意 iCalendar 导出规则,是不同规模的问题;夏令时与时区在两条路线中都需要处理。包体积、发布频率等课件数字反映当时版本,选型时还需重新检查。
标准库、已选择的框架和用途明确的成熟依赖,通常无需逐项写长篇论证;安全、计费、时间语义,以及只用一个函数却引入庞大依赖的情况,更值得保留选择与重新考虑条件。我们审查的是得到多少能力、承担什么维护责任,而不是一概偏向复用或生成。
