# API如钻石：一堂Google神课深读 ## 一场十八年前的讲座，为什么今天还在被疯转 技术圈有个奇怪的现象：教你怎么写代码的课一抓一大把，教你**怎么设计接口**的却屈指可数。而YouTube上有一场2007年的老讲座，至今仍被程序员们反复翻出来当“必修课”看——Joshua Bloch在Google TechTalks上的《How to Design a Good API and Why It Matters》。 先说这个人的分量。Joshua Bloch在Sun Microsystems时主持设计了Java集合框架（`java.util.Collections`那一整套），后来去Google当了首席Java架构师，写的《Effective Java》常年霸占Java书架第一格，被称为“Java界的圣经”。也就是说，全球无数程序员每天调用的那些接口，有一批就是他亲手设计的。让他来讲“什么是好API”，相当于让米其林三星主厨讲“什么是好吃”。 这场一小时讲座的价值在于：它把API设计从“凭感觉”变成了**可操作的工程纪律**。而且放到2026年看反而更扎心了——现在人人都在给大模型写function calling的tool schema，本质上就是在做API设计，只不过调用你接口的从“活人程序员”变成了一个“按概率办事的系统”。十八年前的纪律，不但没过期，反而更生死攸关了。 ## 视频背景卡片 | 项目 | 内容 | |------|------| | 视频标题 | How to Design a Good API and Why It Matters | | 频道 | Google TechTalks | | 主讲人 | Joshua Bloch（《Effective Java》作者、Java集合框架设计者） | | 时长 | 约60分钟 | | 播放量 | 百万量级的常青经典场 | | 核心主题 | API设计的流程、原则与实现纪律 | ## 核心内容拆解 ### 1. 公开API如钻石，出手就是永远 这是整场讲座最有名的一句话：**公开API就像钻石，是永远的**（Public APIs, like diamonds, are forever，大意）。Bloch的逻辑很朴素：代码写坏了，你随时可以推翻重写，没人知道、没人受伤；但API一旦发布，无数客户端代码已经依赖它，你想改，就得让所有依赖方跟着你流血。对个人项目如此，对公司更是如此——客户的投资（购买、学习、集成的成本）都押在你的接口上，API返工等于没收他们的投资。 他还补了一句更狠的：API可能是公司**最大的资产**，也可能是**最大的负债**。设计得好，生态长在你身上；设计得烂，你得养一支团队永久性地给它擦屁股，还要在论坛上被用户鞭尸十年。 【延伸分析】这句话放在开源时代尤其刺眼。Python 2到3迁移拖了十几年、无数大厂至今养着“祖传接口兼容层”，本质上都是在为当年“出手太随便”还债。API的发布成本极低，收回成本却是指数级的。 ### 2. 好不好，用“功能密度”来称 什么算好API？Bloch给了一个非常工程化的定义，好API应该是：**易学、易用、难用错**（easy to learn, easy to use, hard to misuse），而且用它写出来的代码要**易读、易维护**。注意，他把“性能”排在了这些之后——接口先要对，再要快，因为一个快但容易用错的API，制造的事故成本远超它省下的毫秒。 然后他抛出了这场讲座的核心度量衡：**功能密度**（power-to-weight ratio）——同样的功能，暴露的表面积越小越好。组件一大，维护和文档成本全涨，用户学习成本也涨。他反复强调一个原则：**拿不准的时候，就砍掉它**（When in doubt, leave it out，大意）。因为对API来说：功能永远可以往后加，但几乎永远收不回。 【延伸分析】“难用错”这条特别值得展开。Java的老`Calendar`类月份从0开始计数，多少程序员的元旦bug就是它贡献的——这不是用户蠢，是接口把坑修在了路中间。好API的设计者要假设调用者永远在最疲惫的状态下写代码。 ### 3. 需求只是假设：先写一页纸规格 流程上，Bloch的第一条纪律是：**对需求保持健康的怀疑**。用户告诉你的往往不是需求本身，而是他自己想好的解决方案——你得往下多问几层，挖出他真正要解决的问题。需求是假设，不是事实。 然后：**动手写代码之前，先写API规格**。而且规格要短——短到一页纸放得下。如果一页纸写不下，说明这个API太大了，该砍。规格写成“示例代码优先”：与其描述接口长什么样，不如直接给出理想中的调用代码长什么样。调用方视角的一行代码，胜过设计者视角的十页文档。 【延伸分析】这其实是“以终为始”的接口版。很多人写库的顺序是反的：先把自己内部的实现堆完，再把公开方法一个个“拎出来”，最后接口长得像内部结构的X光片——实现一变，接口跟着抖。Bloch的顺序正好相反：先定对外契约，再让实现去服从契约。 ### 4. 代码最有发言权：先实现，再定稿 设计API最大的陷阱是“纸上谈兵”——在幻灯片上一切都很美。Bloch给出的解药是那句名言：**Code wins arguments**（代码最有发言权，大意）。设计争议吵不出结果时，别投票，写个原型跑一下，代码会替你做决定。 他要求更严格：**在API定稿之前，至少写出多个不同场景下的真实使用代码**。你自己写一份、让真实用户写几份，看看接口在各自手里是否别扭。因为一旦定稿，你就进入了“只能加、不能删”的终身制。他还补了一条管理哲学：**尽早失败，廉价失败**。原型阶段发现设计错误，代价是一天；发布之后发现，代价是几年加一场迁移灾难。 【延伸分析】这跟建筑行业的“足尺模型”是一个思路。也解释了为什么很多伟大的库第一版都“丑”——丑不是问题，丑但被真实代码锤炼过、然后小步进化，恰恰是最健康的成长路径。 ### 5. 只做一件事，别让客户端替你干活 原则部分，第一条就是那句老话：**Do one thing and do it well**——每个组件只做一件事，并且做好。如果一个组件的功能你没法用一句话讲清楚，它多半干了不止一件事。 配套的几条纪律非常具体： - **能替客户端做的事，绝不让客户端自己做**（Don't make the client do anything the module could do，大意）。模块内部能校验、能组装、能兜底的，就不要把这类杂活推给调用方——每一次“让用户自己多写三行胶水代码”，都是在给bug发开业优惠券。 - **最小可访问性**：一切成员、字段、类，能private就不要public。可见性像牙膏，挤出来就塞不回去。 - **跟随惯例，别搞发明**：能用业界熟悉的模式，就不要自创一套“更聪明”的写法。熟悉感本身就是可用性。 【延伸分析】“别让客户端干活”这条，是检验一切接口的照妖镜。反例遍地都是：要求调用方先按魔法顺序调三个初始化方法的SDK、要求用户自己拼JSON字符串的配置系统——它们都犯了同一种罪：把模块的责任转嫁成了用户的负担。 ### 6. 命名是语言设计，不是取名字 Bloch花了不成比例的时间讲命名，因为在他眼里，**设计API就是设计一门小语言**，而命名是这门语言的词汇表。他的标准：名字要自解释，让代码读起来像句子；并且**严格一致**——同一个词，在所有地方必须表达同一个含义；不同含义，就必须用不同的词。`get`和`fetch`混用这种事，在好的API里不该发生。 【延伸分析】程序员圈子里流传一句半玩笑：“计算机科学只有两大难题：缓存失效和命名。”（cache invalidation and naming things——这是社区俗语，并非出自本场讲座。）玩笑归玩笑，它说明命名之难是公认的。Bloch给出的解法不是天赋，而是纪律：建一份接口词汇表，写第一行代码前先定词。 ### 7. 文档不是附属品，文档就是契约本体 讲座里另一个被反复敲打的主题：**像宗教徒一样写文档**（document religiously，大意）。每个参数、每个返回值、每种异常情况、失败时的行为、线程安全性——凡是调用方可能依赖的行为，都必须白纸黑字写清楚。因为铁律是：**你没写明的行为，早晚有人依赖它**——到时候你既不能改，还得为这个“意外契约”永久负责。 他现场用的反面教材是老`java.util.Calendar`：可变状态、字段语义混乱、月份从0数起，调用方一个不留神就掉坑；正面教材则是他自己的`java.util.Collections`：用静态工厂方法把创建逻辑藏好，接口小而准，几乎没给别人留犯错的空间。 【延伸分析】这个剧本二十年后原样重演：JavaScript的`Date`臭名昭著，社区最终另起炉灶做了`Temporal`提案——再次证明，烂文档和烂语义欠的债，最后都要靠“推倒重来”来还，而接口的重来，代价最大。 ### 8. 从2007到2026：当调用方变成大模型 【延伸分析，视频未涉及】这场讲座最讽刺的现代注脚是：Bloch当年所有针对“人”的设计纪律，如今正在被原封不动地用在“给大模型写工具接口”上。function calling的schema设计，就是一个纯度极高的API设计问题——只是调用方从“会读文档的程序员”变成了“基于概率猜参数的模型”。 于是“难用错”三条标准全部升级：易学——对模型意味着描述清晰、无歧义；易用——参数少、类型简单、职责单一；难用错——枚举值别开放式、错误信息要能引导模型自我修正。Bloch说“拿不准就砍掉”，放到agent工具设计里就是铁律：给模型塞20个参数的工具，它一定给你猜错三五个。**接口的容错设计，从“防手滑”升级成了“防幻觉”。** ## 知识结构图 ```mermaid flowchart TD A["Bloch的API设计体系"] --> B["为什么重要"] A --> C["设计流程"] A --> D["设计原则"] A --> E["实现纪律"] B --> B1["公开API如钻石
出手就是永远"] B --> B2["易学易用难用错
功能密度是秤"] C --> C1["需求只是假设
多问几层"] C --> C2["先写一页纸规格
写不下就是太大"] C --> C3["代码最有发言权
原型先行"] C --> C4["尽早失败廉价失败"] D --> D1["只做一件事并做好"] D --> D2["能替客户端做的
别让客户端做"] D --> D3["命名一致
同名同义异名异义"] D --> D4["最小可访问性"] D --> D5["拿不准就砍掉
能加不能删"] E --> E1["文档就是契约
没写的会被依赖"] E --> E2["快速失败
错误尽早暴露"] E --> E3["正反教材
Collections与Calendar"] ``` ## 实战启示 看完这场讲座，最实在的收获是可以直接落地的四条动作： **第一，写库之前先写“调用示例”。** 下次你要抽公共组件、写内部SDK、甚至只是给团队写个工具函数时，强迫自己先写下“理想中的调用代码”——三五行，假装它已经存在。如果这三五行写不顺手，接口就是错的，改到顺为止再动实现。这一个习惯能替你省掉一半的返工。 **第二，给code review加一条“API视角”。** 评审别人的PR时，除了看逻辑对不对，多问一句：这个公开方法的命名，三个月后的新人能不能猜对？这个参数，能不能少一个？这个类，能不能再包一层private？拿不准的功能，直接引用Bloch的话：砍掉。 **第三，做AI应用的人，把tool schema当API设计对待。** 每个工具只干一件事、描述里写清“什么时候该用我/不该用我”、参数用枚举而不是自由字符串、错误返回要能引导模型重试。Bloch的“难用错”三字诀，在agent时代就是钱——每次调用失败都是真金白银的token。 **第四，接受“接口终身制”这个前提再做决定。** 发布任何接口前问自己：这个签名，我愿意维护十年吗？愿意写进文档并为之答辩吗？如果答案犹豫，那就还没到该发布的时候。慢一步定稿，好过快十步道歉。 ## 延伸学习路径 1. **《Effective Java》（第3版），Joshua Bloch著** — 本场讲座的“书籍完整版”，90个条目里大量内容是接口设计纪律的落地细则。 2. **Google的API设计规范 AIP（API Improvement Proposals）**，aip.dev — Google把内部API设计纪律开源后的成果，可以看作Bloch思想的现代工程化版本。 3. **Java官方文档中的`java.util.Collections`与`java.util.Calendar`**（docs.oracle.com）— 讲座中的正反教材原件，建议对照源码级文档读一遍，体会“小而准”和“大而乱”的差距。 4. **本场讲座的完整Q&A** — 结尾提问环节里，Bloch回答“什么时候可以破坏API兼容性”的一段非常精彩，值得单独二刷。 ## 一句话总结 **代码可以重写，API出手就是永远——所以接口的设计纪律，值得你用对待产品发布的态度来对待。** ## 参考来源 1. [How to Design a Good API and Why It Matters — Joshua Bloch, Google TechTalks](https://www.youtube.com/watch?v=aAb7hSCtvGw) — 本文分析的核心视频 2. [Java Collections Framework官方文档（docs.oracle.com）](https://docs.oracle.com/javase/8/docs/api/java/util/Collections.html) — 讲座正面教材 3. [Java Calendar类官方文档（docs.oracle.com）](https://docs.oracle.com/javase/8/docs/api/java/util/Calendar.html) — 讲座反面教材 4. [Joshua Bloch — Wikipedia](https://en.wikipedia.org/wiki/Joshua_Bloch) — 主讲人背景 5. [Google AIP — API Improvement Proposals](https://google.aip.dev) — 现代API设计规范延伸 --- > 本文由「51学通信」技术团队出品。51学通信由通信行业18年老兵**爱卫生**（微信ID: gprshome201101）维护，聚焦5G/6G核心网、3GPP标准解读、通信前沿技术深度分析。 > 出版作品有《5G核心网原理与实践》《IMS原理与实践》等4本通信专业书籍。知识星球「51学通信」提供深度技术答疑和行业洞察。 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。