文章提出了提高接口可维护性的十个关键实践，包括在接口注释中添加文档链接，调用接口处写入被调用接口文档，发布接口源代码到私服仓库，优先在接口类中定义状态值常量，提供Map键值的常量定义，考虑将Map转换为对象，简化接口依赖，只传递必要字段，打印接口参数和返回值日志，以及记录RPC接口的类名和方法。这些实践旨在方便后续维护，提高效率并减少错误。
目录
5. 如果使用 Map 对象作为传输载体，要提供 Key 值定义常量
6. 针对 Map 返回值，可以考虑使用将 Map 转化成对象
前言：
接口的可维护性是指在接口设计和开发过程中考虑到后续的维护和扩展需求，使得接口易于理解、修改和维护。
1. 在接口注释中加入接口文档链接
在做接口开发时，无论是对自有接口的升级改造，还是针对外部接口的从头接入，都涉及到接口文档。不同之处是，前者的工作重点是书写或者更新接口文档；而后者是根据接口文档开发合适的接入代码。但是，经常遇到的一个麻烦是，找不到接口文档。在组内需要找老同事询问；如果是跨部门，还需要两层甚至三层的进行转接，非常麻烦。
个人认为，在这种情况下，为了方便大家维护，最好的办法就是将接口文档链接直接放在代码注释中，这样后续维护的人员，直接就可以点击链接直达接口文档，简单方便高效。如果是新建的接口，就可以先创建一个空文档，把链接放在注释中，后续再书写文档内容。如果是维护已有接口，可以在维护时，将缺失的链接加入到注释中，自己方便，也方便其他人进行后续的维护更新。这样，在循序渐进的过程中，逐步就可以把文档链接补充到代码中，方便维护代码，也同步更新文档。
2. 将调用接口处写上被调用接口文档链接
在调用其他系统的接口时，没有接口文档，几乎寸步难行。在第一次接入接口时，绝大多数情况下，都是参考着接口文档做接入工作。但是，目前的情况时，接入时参考文档，参考完就随手把文档给 “扔了”。后续如果还需要做进一步升级维护，还需要到处找接口文档；另外，交互的系统难免有一些 Bug，在和其他系统维护人员对接处理 Bug 时，只有接口没有文档，对方可能也需要去找文档链接。无形中，很多时间都浪费在了找文档的过程中。
最近尝试了一个实践，就是在接口调用的地方，把接口文档链接当做注释加入到代码中。这样，无论是后续维护升级，还是沟通协调处理问题，都非常方便。别人问接口是什么，连接口 + 文档都可以一把复制就搞定。
经过最近一段时间的实践情况来看，这个处理非常方便，是一个非常值得推广的实践。再插一句，也可以像一条建议一样，可以在维护代码时，不断把已接入的接口文档加入到调用接口的地方，循序渐进，方便后续人维护升级。
3. 将接口源代码发布到私服仓库
接口文档链接在注释中，在构建结果中就不复存在了。所以，为了方便接口使用方可以在接口中查询到对应的接口文档，就需要把源码也发布到私服仓库中。
这里只说明一下 Java 的相关处理办法。如果使用 Maven 作为构建工具的话，默认是不会将源代码发布到私服仓库中的。
除了将源码发布到私服仓库，另外，还建议编译构建时，保持方法的原始参数命名。这个也可以通过配置 Maven 插件来完成。
4. 对于状态值常量，优先在接口参数类或者返回值类中定义
在做接口开发时，很多数据都有一个状态值，比如订单状态，再比如接口状态等等。目前的一个情况时，这些状态值大部分书写在文档中，在接入接口时，需要接入方自定义这些状态值。这就有些繁琐了，而且状态定义也不明确，甚至有可能遗漏一些重要的状态值。有些懒省事，直接在代码中硬编码一个魔法值，后续维护的跟还需要根据上下文反推这个值的含义，非常不利于维护。
个人觉得，有两个处理办法：
-
如果状态值不是很多，优先在接口参数类或者返回值类中定义。
-
如果状态值很多，可以考虑单独抽取成一个常量类或者枚举类。
这样使用的时候，触手可及。不需要到处去找。
5. 如果使用 Map 对象作为传输载体，要提供 Key 值定义常量
有些系统可能考虑方便增加字段，选择使用 Map 作为数据载体。自己开发的时候很爽，但是给接口接入却非常不友好。接入方从 Map 中获取数据时，要么自己定义 Key 值；要么直接使用魔法值硬编码在代码中。使用前者方案，就需要在各个接入方都需要自定义一套；
最低0.47元/天 解锁文章
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
