HackerHow To Design A Good API and Why it Matters
Google TechTalksYouTube ↗
延伸阅读 2
字幕解读
Joshua Bloch 将 API 视为长期资产，强调设计者要通过用例和一页规格先想清楚概念，再尽早让真实用户写代码验证。API 应保持小而清晰，隐藏实现细节，命名一致并提供准确文档；拿不准的功能先省略，类型和参数次序要可预测。不可变性、失败快速暴露等选择需服务于调用者，而非仅方便实现者。
英文字幕轨道 · 引文按字幕原文展示，可点时间戳回看片段。
内容要点
- API 很难在发布后修正，因此先写用例和规格，并尽早用真实客户端代码检验。
- 小而一致的接口降低调用者的概念负担；隐藏实现细节并认真选择名称。
- 文档、参数精度、不可变性和最小化功能都影响长期可用性。
视频章节 6
- API 的长期价值
- 先写规格再编码
- 设计 SPI 与接口形状
- 文档和命名
- 继承与契约
- 错误信息与类型精度
具体观点与证据 5
API 尚未实现甚至规格尚未定稿时，就应编写真实调用代码，用用例发现接口缺陷，减少实现错误设计的浪费。
持续编写客户端示例，而非把完整实现当作早期验证前提。
you should start before you've
implemented the API公开接口一旦被依赖就难以删除，所以对可选能力应克制，优先保留未来添加空间。
稳定公共 API 的兼容性约束，不是禁止任何版本升级。
not be able to take it out once you put it into an API.模块能统一完成的工作不应要求每位调用者重复串联步骤；样板代码会复制错误并泄漏内部概念。
以输出 XML 的繁琐工厂与包装步骤为反例。
don't make the client do
anything the module could do.同时提供结构化数据访问，避免用户解析展示字符串，否则字符串格式会成为无法自由修改的事实接口。
以 Java 堆栈信息的字符串接口为例。
programmatic access to
all data that is also available in string form.看起来无状态的日期格式化器仍含内部可变状态，共享使用时会产生并发问题。
讲座所讨论的 Java 日期格式化 API。
feels like an immutable
object, except that it has state inside it.补充字幕原文 2
API 可成为组织的重要资产，设计错误会长期影响使用者。
APIs can be among a company's greatest assets拿不准某项功能是否必要时，倾向于不加入接口。
When it doubt, leave it out.解读边界
演讲提供的是通用 API 设计经验，具体取舍仍受语言、兼容承诺和调用场景影响；“三种实现”针对 SPI 设计，不能机械套用到所有 API。