主题 12：实践案例集锦之接口设计

1. 引言

API 是模块或者子系统之间交互的桥梁，好的系统架构离不开好的 API 设计。在《主题 1：如何设计一个好的 API》一文中，笔者解读了什么样的 API 设计是好的设计，本文作为 API 设计话题的延续，将介绍如何在设计中实践之前介绍的设计方法论。

成功的系统不是有一些特别闪光的地方，而是设计时点点滴滴的努力积累起来的。

API 设计面临的挑战千差万别，没有一种普适性的原则可以适用于所有场景，因此，即便是久经考验的设计原则和最佳实践，本身也一定有适应的场景和不适应的场景。鉴于此，笔者在介绍一些设计原则的同时也会分析这些原则在什么场景下适用，以便读者在实践中可以有针对性地采取例外的策略。

2. 设计 API 的基本原则

2.1 思维模型清晰

很多工程师有一个误解——API 设计的关键在于让客户端与服务端进行良好地交互。这种认识忽略了一个重要的因素——人（包括 API 的设计者、维护者、使用者），事实上，API 设计的关键应是让 API 相关的工程师群体在 API 生命周期内良好地进行互动。一个 API 如何被使用，以及 API 本身如何被维护，依赖于维护者和使用者对该 API 有清晰的、一致的认识，而要达到这一目标，就需要设计者提供一个清晰的、易于理解的模型。

如下图所示，从 API 设计者的角度，他设计了一个模型 A；而从使用者的角度，他看到和理解的模型可能会退化成模型 B，如果这个模型比较复杂，在实际使用过程中可能进一步退化成 C；对于维护者来说，也存在相似的问题。