API设计原则

Authors
  • avatar
    Name
    小明&小艺
    Twitter

一个组件或者模块，对于使用者而言，最核心的是易用性。至于正确性和可靠性，这是设计者的核心之一，使用者要考虑的。易用性最直接的体现是 API。所以 API 的设计至关重要。

  • 好的 API，是从用户的角度设计的, 用户只要花 20%的功夫就能掌握其 80%的功能。
  • 好的 API，当用户从经验出发，需要那种功能的 API，能恰好找到，并且函数名，参数，返回值恰好与设想的一致。
  • 好的 API，有自己的风格，并且有非常好的一致性，相似的功能 API 基本一致，使用流程基本一致。能使用户触类旁通
  • 好的 API, 能引导员工写出可读的,符合直觉代码。能去规划用户代码流程，避免用户错误的使用，并且有足够的容错以及错误反馈能力
  • 好的 API, 是高效的,可量化的，用户可以容易的感知其使用所需的成本，包括，内存，cpu，系统资源的使用等等。 同时会，尽可能少的，明确的，最好是不会对用户系统产生哪些副作用。
  • 好的 API，能非常容易的升级和优化，并且不会或者尽可能少的给用户代码造成影响。
  • 好的 API，便于内部测试和用户的测试，并且有一套完整的测试用例

好 API 的 6 个特质： 极简且完备、语义清晰简单、符合直觉、易于记忆和引导 API 使用者写出可读代码。

API 语义和文档

比如传值 -1 的含义是什么？如果 API 文档不像 http status codes 一样健全，建议通过枚举的方式增加可读性。

例如：Vue-router 里面的 mode，枚举了 history/hash;

命名的艺术

不要使用缩写，保持一致性。类命名以功能分组作为后缀，比零散命名更易懂。

函数命名要体现出是否包含副作用，参数过多时以对象作为传参，布尔参数改为枚举类型，或者分解为两个语义化 API。

例如：qiankun 框架里的：registerMicroApps、start、runAfterFirstMounted

单一职责

接口设计尽量要做到 单一职责,最细粒度化; 可以使用组合的方式把多个解耦的单个接口组合在一起作为一个大的功能项接口; 接口设计的单一职责，也更方便多人协作时候的扩展和组合;

例如：React 的 React.Component、React.PureComponent

面向未来的多态

对于接口参数的扩展，我们要做到面向扩展开放，面向修改关闭; 升级做到要兼容，否则会导致大批量的下游不可用。

同时也要避免过度设计，当抽象功能只有一处使用时，尽量不要过早抽象。

例如：