如何设计好API接口

1.png

如图所示，我们从这五件事情上来完成一个好的API接口设置

1. 标准化

对于web API标准化而言， 非常好的案例就是RESTful API ,目前业界的Open API 多数是基于RESTfun API 规范设计的，而RESTful API 已经具有成熟度的模型，如下

2.png

其中Level 0 就是普通的请求响应模式，Level 1引入了资源的概念，可以单独创建URI，与Level0相比，通过资源的分而治之的方法来处理复杂的问题，Level 2引入了一套标准的HTTP协议，通过遵守HTTP协议定义的动词（GET,POST,PUT,DELETE,PATCH），并配合HTTP响应状态码来规范化Web API的标准，Level 3中使用超媒体，可以使协议拥有自我描述的能力。通常情况下，level等级达到2级就已经非常好了。在RESTful API中，每个URI代表一种资源，URI就是每个唯一的资源定位符，因为RESTful API 可以通过GET ,POST,PUT,PATCH,DELETE等方式对服务端资源进行操作，所以在定义接口的是，通常需要制定 请求方式/版本号/资源名称/资源ID

3.png

比如查看用户编号是1001的用户信息：

[GET] /v1/users/1001

当一个资源变化难以用RESTful API命名的时候，可以考虑特殊的action命名，比如修改密码

[PUT] /v1/users/1001/password/actions/modify

另外 不要创建自己的错误码，和返回错误机制 , 很多时候我们觉得提供更多的自定义错误码有助于传递信息，但其实如果只是传递信息的话，错误信息字段可以达到同样的效果，此外对于客户端来说，很难关注到过多的错误细节，这样的设计就会让API的处理更加复杂，难于理解。因此，建议是遵守RESTful API 规范，使用HTTP协议规范的错误码。比如，200表示请求成功，404表示无法找到，400表示错误请求，403表示无权，500表示服务内部错误等等。当响应的是非200的HTTP错误码响应时，可以采用全局的异常结构响应信息

响应的异常结构中，响应信息中每个字段的含义

4.png

2. 兼容性

接口需要向下兼容，以前的业务不能受到影响。例如接口提供给了PC,Android，IOS不同端服务调用，在业务逻辑上处理会有些许的不同，如果不做兼容处理，则客户端必须升级到最新的版本，用户显然是无法接受这样的请求，所以就引入了版本的概念，来实现API的兼容

3.抽象性

通常情况下，我们的接口抽象都是基于业务需求的，因此一方面需要定义出清晰的业务问题域模型，例如数据模型和领域模型，并建立起某个问题的现实映射，实现抽象就能很好地屏蔽具体的业务实现细节，为我们提供更好的可扩展性

4. 简单性

就是遵守最少知识原则，就是客户端不需要知道那么多服务的API接口，以及这些API接口的调用细节，比如设计模型的外观模式和中介则模式。一个接口对多个服务的调用封装在一起，客户端只需要调用这一个接口即可，不需要知道具体的内部实现逻辑

5.高性能

外观接口虽然保证了简单性，但是增加了服务器的业务复杂度，多个服务之间的聚合，也会导致接口的性能下降，所以在入参字段的组合上，我们需要考虑到数据库的性能问题，很多时候我们会暴露太多的字段给外部使用，在字段要求上没有做处理，导致在查询数据库的时候没有命中索引或者本身就没有对应的索引，导致全表扫描，性能急速下降。因此我们可以提供只存在索引的字段组合，给外部调用