如何设计一个良好的API接口？( 二 ) _API接口

而message字段用来表示错误的摘要信息，它的作用是让开发人员能快速识别错误。

server_time字段，用来记录发送错误时的服务器时间，他可以明确的告诉开发人员发生错误时的具体时间，便于在日志系统中根据时间范围来快速定位错误信息。

文章插图

此外，不常用字段会根据不同的情况做出有不同的响应。
如果是单条数据，则返回一个对象的json字符串；如果是列表数据，则返回一个封装的结构体，其中涵盖count字段和item字段。

文章插图

count字段表示返回数据的总数据量。需要注意的是，如果接口没有分页的需求，尽量不要返回这个count字段，因为查询总数据量是耗性能的操作。
此外，item字段表示返回数据列表，他是一个json字符串的数组。
5、小结
总结一下，怎么来理解规范呢？可以说他就是大家约定俗成的标准，如果都遵守这套标准，自然沟通成本也就大大降低了。
兼容性接着我们再来探讨一下API接口的兼容性。由于我们参与的业务是不断演进的，设计一个有兼容性的API就显得尤为重要了。如果接口不能够向下兼容，业务就会受到很大影响。
例如：

我们的产品是涵盖Android、IOS、pc端的，都运行在用户的机器上，这种情况下，用户必须升级产品到最新的版本才能够更好的使用。
同时，我们还可能遇到服务端不停机升级，由于API不兼容而遇到短暂的服务故障。

为了实现API的兼容性，我们引入了版本的概念，前面的案例URI中通过保留版本号实现了兼容多个版本。

文章插图

举个例子，针对要查看用户编码是1001的用户信息，可以分别定义V1和V2两个版本的API接口，然后分别让他们对应两套不完全兼容的业务逻辑特性。
抽象性通常情况下，我们的接口抽象都是基于业务需求的，因此我们一方面要定义出清晰的业务问题域模型，例如数据模型和领域模型等，并建立起某个问题的现实映射，这样有利于不同的角色对API设计认知的统一。
另一方面，API设计如果可以实现抽象，就可以很好的屏蔽具体的业务实现细节，为我们提供更好的可扩展性。
简单性简单性的主要宗旨是遵守最少的知识原则。
怎么来理解呢？其实就是客户端不需要知道那么多服务的API接口，以及这些API接口的调用细节，比如设计模式的外观模式和中介者模式都是它的应用案例。

文章插图

如图所示，外观接口将多个服务进行业务封装与整合，并提供了一个简单的API调用给客户端使用，这样设计的好处是什么呢？就在于客户端只需要调用这个外观接口就行了，省去了一些繁杂的步骤。
性能同时，我们还需要关注性能，就比如说外观接口，虽然保证了简单性，但是增加了服务端的业务复杂度，同时，由于多服务之间的聚合，导致他们的接口性能也不是太好。
此外，我们还需要考虑字段的各种组合会不会导致数据库的性能问题。有时，我们可能暴露了太多字段给外部使用，导致数据库没有相应的索引而发生全表扫描。这种情况在查询的场景下非常常见，因此我们可以只提供存在索引的字段组合给外部调用。
Result<Void> agree(Long taskId，Long caseId，Configger configger)
在上面这个代码案例中，要求调用方必填taskId和caseId来保证数据库索引的使用，以进一步保证服务提供方的服务性能。
总结今天给大家侧重探讨的是如何设计一个良好的API接口。
好的API设计需要我们同时考虑到标准化、兼容性、抽象性、简单性和高性能。
其中，标准化的关键在于尽可能少的创建自定义规范和机制，而是共同遵守业内标准，例如HTTP规范和Restful API规范。
通常情况下，我们会采取版本号来解决多版本的兼容性的问题。
抽象性需要确保能够定义出清晰的问题域模型，尽可能屏蔽具体的业务实现细节。
简单性是相对的，需要遵守最少知识原则，让调用方尽可能少的知道内部的调用细节，性能注意的细节就多了，这里主要强调了业务组合和参数组合场景。