从 Java 大神 Joshua Bloch 提炼 API 设计的三个核心原则

关注

翻译 2024-03-13 11:38:11 588 阅读 AI 写同款· GEO 优化 ›

Java设计模式实战：7种核心模式解析与工程应用指南设计模式是软件工程中解决常见设计问题的经典方案，其核心在于通过封装变化、降低耦合来提升代码的可维护性与扩展性。从原理层面看，设计模式基于面向对象的基本原则，如开闭原则、依赖倒置等，通过定义清晰的接口与抽象来隔离变化点。其技术价值在于为复杂软件系统的架构提供了经过验证的蓝图，能有效应对需求变更与系统演进，避免代码腐化为难以维护的“大泥球”。在应用场景上，无论是管理全局资源的单例模式、封装对象创建的工厂模式，还是实现算法灵活切换的策略模式，都广泛应用于框架设计（如Spring）、中间件及业务系统开发中。本文聚焦阅读详情

一个 API 应该容易学习和使用，且不易被误用。它还应该随着时间而发展，优秀的设计需要预见并适应这种变化。

file

Joshua Bloch 曾在 Sun 担任杰出工程师，之后加入谷歌成为首席 Java 架构师。他主导了 Java 平台上的很多功能，包括 Java Collections 框架，java.math 包，assert 机制等。他也是 Effective Java 的作者。

在谷歌 2007 年的一场重要演讲中，软件工程师兼技术作家 Joshua Bloch 强调了 API 是一种极其重要的商业资产。他指出，这主要是因为如果 API 对外开放，客户可能会选择在上面进行大量投资，从而很难改变使用习惯。

Bloch 还警告说，设计糟糕的 API 可能会导致无休止的客户支持电话，极大地阻碍公司的发展。

Bloch 进一步指出，以 API 设计为思考核心，能显著提高编写程序的质量。

即使你作为一个程序员并不直接参与面向公众的 API 开发，实际上你也在持续地创建 API。优秀的编程应该是模块化的，模块间的边界自就是 API。同样，如果你参与的是一个现代化的、分布式的、基于微服务架构的系统，那么服务间的边界也构成了 API，只是架构有所不同。

尽管如此，API 设计仍然是许多程序员面临的一个挑战。那么，一个好的 API 有哪些特点呢？

名字至关重要

从宏观角度来看，API 应该易于学习和使用，同时难以被误用。它还需要随着时间的发展而进化，而一个优秀的设计会将此考虑在内。

命名的方式极其重要，因为 API 在实质上是一种需要用户学习的简约语言。

「真正合适的命名可以解决问题并避免误解，因为恰当的命名能够非常明确地表明事物的本质。」SoftIron 首席科学家 Harry Richardson 在接受 The New Stack 采访时表示。

Richardson 特别指出，对于开发者来说，命名塑造了我们的思维模型。

「改变一个已经形成的思维模型是相当困难的工作，这不一定是在代码方面，而是关于我们思考问题方式的方面。」

因此，投入时间去精心挑选一个能够精确描述 API 功能的名称是非常值得的。

作为一个作家的基本工具 —— 字典和词典 —— 在 API 命名过程中也能提供帮助。如果你发现某个名字特别难以确定，这可能意味着它尝试同时承担太多的职责。就像需要将过于复杂的句子分割成更简单的句子一样，当一个模块过于复杂时，也应该考虑将其拆分。

要避免使用让人费解的缩写，并且注意保持命名的一致性。比如，不应该同时使用 getBasicSalary() 和 getBaseSalary() 这样意义相同但命名不一的方法 —— 如果你的 API 中既有 remove() 又有 delete() 方法，使用者能够清楚地知道它们之间的区别吗？

使用的语言需要与组织或供应商公开的其他 API 保持一致性。这种对一致性的追求意味着，实施一定程度的集中化管理会很有帮助。

比如，一些大型企业会把高级技术写作人员的职责扩展到帮助工程团队统一命名方法、属性和字段。

如果你正在开发 REST 风格的系统，独立咨询师兼《掌握 API 架构》一书的合作者 Daniel Bryant 建议参考已有的 API 指南集，这有助于在 API 的行为上实现一致性。对于基于 HTTP 的 API，他推荐考虑使用 OpenAPI，还有其他包括 Atlassian、Google 和 Microsoft 在内的指南。

同时，虽然所有 API 都需要恰当的命名，但这些命名本身是特定于领域的；比如，为量化分析师编写的 API 与为零售商编写的 API 使用的语言会有很大不同。理想情况下，选用的术语应与企业已经使用并至少理解的术语匹配。

为此，Bryant 在对 The New Stack 的讲述中提到，最佳做法是进行用户研究，确保覆盖所有潜在的 API 使用群体。

「QA 团队成员与开发者对于你的 API 应如何运作会有不同的看法，」他说。「我经常见到开发者在没有询问谁会使用它的情况下设计 API，结果暴露了内部的领域模型。」

他推荐从「待完成的工作」（Jobs-to-be-Done）的角度来考虑，比如：你的关键任务是什么？你的工作流是怎样的？你是如何处理它的？你希望如何处理它？最后一个问题至关重要，因为围绕已建立的流程可能会形成惯性。

「如果你能简化复杂事物，你就有可能颠覆人们的世界观，随着系统的演进，通常会出现很好的机会」Bryant说。