关于接口可维护性的一些建议 | 京东云技术团队

作者：D瓜哥

在做新需求开发或者相关系统的维护更新时，尤其是涉及到不同系统的接口调用时，在可维护性方面，总感觉有很多地方差强人意。一些零星思考，抛砖引玉，希望引发更多的思考和讨论。总结了大概有如下几条建议：

1. 在接口注释中加入接口文档链接

2. 将调用接口处写上被调用接口文档链接

3. 将接口源代码发布到私服仓库

4. 对于状态值常量，优先在接口参数类或者返回值类中定义

5. 如果使用 Map 对象作为传输载体，要提供 Key 值定义常量

6. 针对 Map 返回值，可以考虑使用将 Map 转化成对象

7. 尽可能简化接口依赖

8. 只传递必要字段，尽量避免大而全的接口

9. 将接口的参数和返回值原始数据打印到日志中

10. 将 RPC 接口的类名及方法打印到日志中

11. 核心思想：以人为本，就近原则，触手可及

下面，D瓜哥对每一条建议做一个详细说明。

1. 在接口注释中加入接口文档链接

在做接口开发时，无论是对自有接口的升级改造，还是针对外部接口的从头接入，都涉及到接口文档。不同之处是，前者的工作重点是书写或者更新接口文档；而后者是根据接口文档开发合适的接入代码。但是，经常遇到的一个麻烦是，找不到接口文档。在组内需要找老同事询问；如果是跨部门，还需要两层甚至三层的进行转接，非常麻烦。

D瓜哥认为，在这种情况下，为了方便大家维护，最好的办法就是将接口文档链接直接放在代码注释中，这样后续维护的人员，直接就可以点击链接直达接口文档，简单方便高效。如果是新建的接口，就可以先创建一个空文档，把链接放在注释中，后续再书写文档内容。如果是维护已有接口，可以在维护时，将缺失的链接加入到注释中，自己方便，也方便其他人进行后续的维护更新。这样，在循序渐进的过程中，逐步就可以把文档链接补充到代码中，方便维护代码，也同步更新文档。

2. 将调用接口处写上被调用接口文档链接

在调用其他系统的接口时，没有接口文档，几乎寸步难行。在第一次接入接口时，绝大多数情况下，都是参考着接口文档做接入工作。但是，目前的情况时，接入时参考文档，参考完就随手把文档给“扔了”。后续如果还需要做进一步升级维护，还需要到处找接口文档；另外，交互的系统难免有一些 Bug，在和其他系统维护人员对接处理 Bug 时，只有接口没有文档，对方可能也需要去找文档链接。无形中，很多时间都浪费在了找文档的过程中。

D瓜哥最近尝试了一个实践，就是在接口调用的地方，把接口文档链接当做注释加入到代码中。这样，无论是后续维护升级，还是沟通协调处理问题，都非常方便。别人问接口是什么，连接口+文档都可以一把复制就搞定。

经过最近一段时间的实践情况来看，这个处理非常方便，是一个非常值得推广的实践。再插一句