接口设计的五点建议！

时间 2019-11-10

标签接口设计五点 5点建议繁體版

原文原文链接

本文首发于我的微信公众号《andyqian》，关注便可内推 BAT程序员

前言

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

编写文档

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

符合最小原则

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

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

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

新老兼容

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

常见事故以下所示：spa

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 设计最佳实践的思考》中特别提到的一点。

及时移除不要的代码

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