接口设计的五点建议！

最新推荐文章于 2023-06-27 17:12:13 发布

chenqun3823

最新推荐文章于 2023-06-27 17:12:13 发布

阅读量230

点赞数

原文链接：https://my.oschina.net/u/1462914/blog/3101751

版权

本文首发于个人微信公众号《andyqian》，关注即可内推 BAT

前言

接口是目前：前后端交互(Rest)，系统交互(RPC)最普遍的一种方式。一个好的接口，应该清晰易懂，职责明确，易于维护。反之，则会造成很多困扰。特别是Open API，谁做谁知道。基于这样的前提以及自己之前踩过的坑，就成了这篇文章的由来。

编写文档

文档与程序员之间有着一种非常奇妙的关系。一句话概括就是：”写之，痛之。用之，悔之”。怎么解释呢？就是：写的时候觉得很痛苦，不愿意写！用的时候呢，又后悔当初没有留下文档！ 可见文档是多么重要。以Rest接口为例，文档需要详细的记录请求参数，返回参数，每个字段的意思，是否必填，请求方法等。随着代码的更新，文档也应该及时更新。在很多开发者眼里(包括我自己)，觉得写文档是一件浪费时间的事情，写代码才是正经事。随着工作经验的积累，愈发觉得文档的重要性，不但没浪费时间，反而还在节省时间。

符合最小原则

这个原则其实是有点像设计模式中的迪米特法则(也称为：最小知识原则)，不过我认为这其中包含了两层意思：

其一：在接口设计中，请求参数在保证功能的前提下：尽可能的减少参数，更不允许添加无用的参数。以Rest接口为例：一旦添加了无用的参数，在后续迭代过程中，就会遇到：弃之可惜，留之无用 的尴尬局面。对于 Client 端也会造成困扰，还会浪费带宽。

其二：接口粒度应该尽量小且保持单一职责，不要写大而全的接口。单一职责的好处不必多说，是一个老生常谈的问题。

新老兼容

在接口设计中，新老接口的兼容是必须要考虑的，堪称事故多发地。

常见事故如下所示：

v1 版本 API 上线发布后。随着需求变化，需要在v2 接口版本中新增几个字段。上线后，发现使用v1 版本的客户端业务中断。(v1版本没有兼容V2版本(新字段)导致)。
v1 版本 API 上线发布后。随着需求变化，需要删除某个接口。系统上线后，造成低版本客户端业务中断 (没有兼容老的Client Version 导致)。

…

对于 Rest 接口，在这方面需要特别注意。因为客户端更新的周期是漫长的，以微信Android客户端为例。目前最新版本是：V7.0.6，但事实上：并不是每一个Android客户端的版本都是最新的V7.0.6，有可能是：V6.7.2，也有可能更低。对于微信这类国民软件而言，每一个版本影响的用户数都是极大的。如果不兼容，造成影响是巨大的。

对于这种情况，API接口的更新：一般会采用新老版本并行使用进行过渡，并在大版本中进行逐步更新，直至没有Client Version进行使用时，API接口才能进行下线。

同样的道理，放在内部的 RPC 接口也适用。前一段时间还犯了一个这样的错，事情是这样的：在更新一个必须强制更新RPC接口时，采用了同步发布法。当时以为全部理清楚所有调用端，上线后，依然造成了生产事故，因为还有一个调用端没有在计划内。这样做的弊端包括但不限于以下几点：

涉及应用多，(如果该接口为底层服务，那调用的上层应用都需要同步修改，一旦缺少一个，则会发布失败)。
发布时间长

…

事实上：我们应该尽量避免这种”同步发布法”，这也是阿里研究员谷朴老师在《API 设计最佳实践的思考》中特别提到的一点。

及时移除不要的代码

这个确实是一个容易忽略的细节。我自己也有过这样的经历，特别是一些策略性的代码及产品代码中，非常容易出现这样的现象。例如：某段代码一开始是有的，后面因为优化也好，因为调整也好，要去掉。但 “ 自认为 “ 后面还是会使用，则将其注释之。时而久之，这段注释的灰代码就此扎根，谁也不敢修改。代码中的坏味道就此慢慢的发酵，直至变臭。因此：无论从扩展方面，还是可维护方面考虑，都建议及时清除不必要的代码。