Contents

1. 1. 设计API前读一读
   1. 1.1. 设计API应该达到的目标：
      1. 1.1.1. 易于学习，易于理解
      2. 1.1.2. 不容易引发歧义
      3. 1.1.3. 易于扩展
      4. 1.1.4. 满足用户需求
   2. 1.2. 如何实现一个好的API设计
      1. 1.2.1. 一个API的功能应该是单一的
      2. 1.2.2. 尽量少的外部依赖
      3. 1.2.3. 不要泄露内部实现细节
      4. 1.2.4. 良好的命名
      5. 1.2.5. 性能要好
      6. 1.2.6. 接口的设计上应该注意的细节
      7. 1.2.7. API和API，模块和模块之间的关系
      8. 1.2.8. 一个API应该包含的内容
         1. 1.2.8.1. 调用方式
         2. 1.2.8.2. 调用约定
         3. 1.2.8.3. 依赖关系
   3. 1.3. RESTful

设计API前读一读

设计API应该达到的目标：

易于学习，易于理解

应该具有足够的注释和文档进行解释说明，让其他调用者可以很快的上手使用你完成的接口。接口的意义不应该过于复杂，使人便于理解。

不容易引发歧义

避免模棱两可，使调用者清楚自己应该使用哪个接口，避免对于接口的错误使用。

易于扩展

对于工程的迭代时，应该可以最大限度的复用之前的接口而不破坏整个工程的架构。因此对于接口的设计应该是易于扩展的。

满足用户需求

• 完备性
  • 完备性是指接口的设计完全能够完成满足用户需求的目标
• 正交性
  • 数学上的正交大约体现为两个向量的乘积为0，两个向量的乘积被两个向量分别影响，因此乘积为0的情况说明这两个向量无法互相影响。
  • API设计中的正交性是在保证完备性的前提下另一个需要注意的点，即尽可能满足所有的API之间是正交的，并且使用户需求和具体实现是正交的。
  • API和API之间是正交的可以保证接口之间的重复功能最少，这样的接口构成的模块是具有高度稳定性的。
  • 即用户需求发生变化时，接口的具体实现不需要任何改动，只需要调用者改变调用方式即可满足。即用户需求和具体实现不产生任何的互相影响。

如何实现一个好的API设计

一个API的功能应该是单一的

所谓单一的功能，是为了一个API可以有更好的维护。一个API功能不单一的极端情况就是所谓的上帝类，上帝类的意思就是指一个类可以完成一个工程的所有需求，即所有的业务逻辑全部都放在一个类（API）中。

从现在来看，上帝类其实是一个反人类的存在，这大概很“上帝”了hhh。在软件工程刚刚出现的时候，并没有人考虑到后期维护的问题。所以大家的代码全部都写在一起，通过各种goto语句来链接所有的业务逻辑。

但是问题在于这样的实现将产品的具体需求和API的具体实现过于紧密的绑定在了一起：但凡产品的具体需求发生了改变，体量相当庞大的源代码就需要进行相应的维护和改变。慢慢的上帝类就变得极其臃肿，难以维护。

在功能上使每一个API都是一个最小的单元，这样便于在产品的需求发生改变时，能够对最少的源代码进行维护。

尽量少的外部依赖

接口调用者，可能是和你进行协作的前端工程师、安卓BoyOrGirl，也有可能是任何的开发者，甚至可能是在你之后继续进行开发工作的同事。因此在他们调用时最好可以很快的进行上手。

依赖的安装，或者叫环境的配置永远是程序员所头疼和厌恶的问题，因此API的实现应该使用尽可能少的外部依赖。

不要泄露内部实现细节

接口存在的意义，就是为了能够使项目的各个部分以模块化的方式进行协作和开发，接口的实现隐藏了一个模块的内部实现逻辑，而这些信息对于其他的模块来说是不必要的，首先暴露内部实现对于模块本身是不安全的，其次内部实现对于其他模块可能产生干扰。

因此接口的存在要整洁。不要有任何多余的冗余信息。

良好的命名

命名是任何程序员都会遇到的问题，对于程序的变量，函数名等等都需要注意，这里对于接口的名称，参数名称等等进行约束。

• 拼写准确
  • 写错字还挺丢人的
• 时态准确
  • 正确的时态能给调用者很好的引导
• 函数最好的动宾结构
• 属性最好是定语+名词
  • 定语可以很好的加深调用者对于参数的理解
• 不要用生僻单词
  • 不要在不必要的地方秀英语
• 不要自己创造缩写
  • 这方面的创造是不必要的
• 便于调用者理解
  • 任何关于接口的设计都应该坚持这一点

性能要好

事实上这一点才应该是实现接口的程序员最上心的一点。一个接口的性能是很重要的，这直接体现了一个程序员的水平。代码的行数并不重要，重要的是接口的性能。当然可以使用各种手段来让你的代码性能变高，但是同时也要注意之前提到的依赖问题。

接口的设计上应该注意的细节

• 写注释
• 方法的出现要成对
  • open-close add-remove
• 一套API应该具有相同的名词规范
• 使用的意义相同的变量名称应该相同
• 不要给已经有了约定俗成的语义的状态码新的语义
  • 比如 401Unauthorized
• 减少在API中的冗余信息
  • 比如path中仅出现一个ID时并不需要特殊命名。
• 不要让一个接口实现多个功能

API和API，模块和模块之间的关系

• 任何语言都不允许循环调用（循环继承，循环引入）。在实现模块的时候也应该遵循同样的原则：不要让API和API，模块和模块之间的依赖关系变得复杂，应该有明确的单向依赖关系。当底层接口过于多调用过于繁琐时应该在两层之间加一个胶水层（工具函数层）。

一个API应该包含的内容

以下内容基本都以文档的形式实现。

调用方式

即使用者应该如何调用。使用何种方式进行调用。

调用约定

各个部分的参数应该以怎样的约定进行传入，传出的数据又以怎样的形式进行组织等等。

依赖关系

调用的条件。

RESTful

RESTful API