关于接口可维护性的一些建议

京东技术

发布于 2023-08-22 15:35:14

2300

发布于 2023-08-22 15:35:14

文章被收录于专栏：京东技术

Tech 导读在软件开发中，维护周期占据整个生命周期的绝大多数。在用户剧增的互联网时代，作为主流架构的微服务架构，经常需要面对数据众多的系统，软件维护成本更是日趋陡增。本文结合实际工作体验，从可维护性的角度，提出了几个非常切实可行且行之有效的技巧和建议，涉及了文档、接口、字段、常量，还有日志等几个方面，覆盖了从开发到维护的主要流程。

前言

在今年的敏捷团队建设中，我通过Suite执行器实现了一键自动化单元测试。Juint除了Suite执行器还有哪些执行器呢？由此我的Runner探索之旅开始了！

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

在接口注释中加入接口文档链接
将调用接口处写上被调用接口文档链接
将接口源代码发布到私服仓库
对于状态值常量，优先在接口参数类或者返回值类中定义
如果使用 Map 对象作为传输载体，要提供 Key 值定义常量
针对 Map 返回值，可以考虑使用将 Map 转化成对象
尽可能简化接口依赖
只传递必要字段，尽量避免大而全的接口
将接口的参数和返回值原始数据打印到日志中
将 RPC 接口的类名及方法打印到日志中
核心思想：以人为本，就近原则，触手可及

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

详细说明

理解，首先 MCube 会依据模板缓存状态判断是否需要网络获取最新模板，当获取到模板后进行模板加载，加载阶段会将产物转换为视图树的结构，转换完成后将通过表达式引擎解析表达式并取得正确的值，通过事件解析引擎解析用户自定义事件并完成事件的绑定，完成解析赋值以及事件绑定后进行视图的渲染，最终将目标页面展示到屏幕。

2.1 在接口注释中加入文档链接

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

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

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

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

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

经过最近一段时间的实践情况来看，这个处理非常方便，是一个非常值得推广的实践。再插一句，也可以像一条建议一样，可以在维护代码时，不断把已接入的接口文档加入到调用接口的地方，循序渐进，方便后续人维护升级。

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

接口文档链接在注释中，在构建结果中就不复存在了。所以，为了方便接口使用方可以在接口中查询到对应的接口文档，就需要把源码也发布到私服仓库中。

这里只说明一下 Java 的相关处理办法。如果使用 Maven 作为构建工具的话，默认是不会将源代码发布到私服仓库中的。关于如何将源代码发布到，在《升级 Maven 插件：将源码发布到私服仓库》（https://www.diguage.com/post/upgrade-maven-plugins/#src-to-repo）中已经做过相关介绍，这里就不再赘述。

除了将源码发布到私服仓库，另外，还建议编译构建时，保持方法的原始参数命名。这个也可以通过配置 Maven 插件来完成，具体配置见：《升级 Maven 插件：字节码文件包含原始参数名称》（https://www.diguage.com/post/upgrade-maven-plugins/#compile-with-parameters）。

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

‍‍

‍‍在做接口开发时，很多数据都有一个状态值，比如订单状态，再比如接口状态等等。目前的一个情况时，这些状态值大部分书写在文档中，在接入接口时，需要接入方自定义这些状态值。这就有些繁琐了，而且状态定义也不明确，甚至有可能遗漏一些重要的状态值。有些懒省事，直接在代码中硬编码一个魔法值，后续维护的跟还需要根据上下文反推这个值的含义，非常不利于维护。

有两个处理办法：

如果状态值不是很多，优先在接口参数类或者返回值类中定义。
如果状态值很多，可以考虑单独抽取成一个常量类或者枚举类。

这样使用的时候，触手可及。不需要到处去找。

‍

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

有些系统可能考虑方便增加字段，选择使用 Map 作为数据载体。自己开发的时候很爽，但是给接口接入却非常不友好。接入方从 Map 中获取数据时，要么自己定义 Key 值；要么直接使用魔法值硬编码在代码中。使用前者方案，就需要在各个接入方都需要自定义一套；使用后者，初期是省事了，后来维护的人员就懵逼了。这都无形中增加了很多维护成本。

有一个方案更优，那就是直接由接口提供方来定义这些可以取值的 Key 值常量。这样，任何接入方都可以直接使用这些常量。

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

针对 Map 的处理，即使按照《如果使用 Map 对象作为传输载体，要提供 Key 值定义常量》（https://www.diguage.com/post/tips-for-interface-maintainability/#key-for-map）推荐的做法，定义了相关的 Key，在取值时，也略有麻烦，需要不断的 map.get(KEY)。一个更简单的方法是自定义一个类型，使用工具将 Map 对象转化成自定义类型的对象。这样就可以直接使用方法调用来取值。

在 Java 中，可以直接使用 Jackson 来完成这个转换工作。工具类代码如下：

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.collections.CollectionUtils;

import java.util.*;java

/**
 * Map 工具类
 *
 * @author D瓜哥 · https://www.diguage.com
 */
@Slf4j
public class MapUtils {
    private static final ObjectMapper MAPPER = new ObjectMapper();

    static {
        MAPPER.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
    }

    /**
     * 将 Map 转换成指定类型的对象
     *
     * @author D瓜哥 · https://www.diguage.com
     */
    public static <T> T convertToObject(Map<String, Object> data, Class<T> clazz) {
        try {
            T result = MAPPER.convertValue(data, MAPPER.getTypeFactory().constructType(clazz));
            if (log.isInfoEnabled()) {
                log.info("converted {} to a {} object: {}",
                        JsonUtils.toJson(data), clazz.getSimpleName(), JsonUtils.toJson(result));
            }
            return result;
        } catch (Exception e) {
            log.error("converting failed! data: {}, class: {}",
                    JsonUtils.toJson(data), clazz.getSimpleName(), e);
        }
        return null;
    }

    /**
     * 将 Map 转换成指定类型的对象
     *
     * @author D瓜哥 · https://www.diguage.com
     */
    public static <T> List<T> convertToObjects(List<Map<String, Object>> datas, Class<T> clazz) {
        if (CollectionUtils.isEmpty(datas) || Objects.isNull(clazz)) {
            return Collections.emptyList();
        }
        List<T> result = new ArrayList<>(datas.size());
        if (CollectionUtils.isNotEmpty(datas)) {
            for (Map<String, Object> data : datas) {
                T t = convertToObject(data, clazz);
                result.add(t);
            }
        }
        return result;
    }
}

2.7 尽可能简化接口依赖

现在，很多对外暴露接口的定义是，接口定义放在一个模块中；模型定义在一个模块中；有些工具类又定义在一个模块中。接口依赖模型模块；模型模块又依赖工具类模块；而工具类依赖了一大堆外部依赖。个人觉得这是一个非常不好的实践。会导致很多不必要的依赖被间接引入到了接口使用方的系统中，无形中增加很多维护成本。

推荐的一个实践是：将接口和模型定义放在一个模块中，对外暴露也只需要这一个模块即可。接口使用方只需要引入这一个依赖。避免引入很多无用的其他外部依赖。如果模型需要依赖一些公共的父类，可以考虑将这些单独定义在一个模块中，这个模块只保存多个系统依赖的公共类，并且剔除掉一些工具类的定义，这样就可以保证接口依赖的纯净性。如果其他系统需要工具类，让其明确去引入，而不是被动依赖。

对于前面《对于状态值常量，优先在接口参数类或者返回值类中定义》（https://www.diguage.com/post/tips-for-interface-maintainability/#constant-definition）中提到了“如果状态值很多，可以考虑单独抽取成一个常量类或者枚举类。” 这里存在一种情况需要特别说明，状态值的定义需要在本系统的业务模块的代码中使用，可以将接口的依赖加入到改业务模块的依赖中，而不是反过来。为什么会这样的操作？一个核心思想是保持对外暴露接口的纯净性。这样既可以减少状态定义的重复性，又可以减少接口的外部依赖。

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

‍‍

‍‍观察很多系统，尤其是一些以业务为核心的系统的对外暴露接口，很多接口是大而全的接口，一个接口就可以把指定数据的所有信息全部返回出去。这样，很多字段需要去识别，也要在众多字段中区筛选出来符合自己要求的数据，无形中浪费了很多心智，不利于维护。

在做接口开发时，一定要做一个“吝啬的守财奴”。把数据当做财富一样守护，对外只提供必要的数据，做到“够用就行”。

这一点不仅仅是维护上的考虑，还有数据传输效率的点。在其他条件相同的情况下，更小的数据，无论是机器处理效率，还是传输效率，都会更快更高。

关于传输效率上的一些思考，结合《Hessian、Msgpack 和 JSON 实例对比》（https://www.diguage.com/post/hessian-vs-msgpack-vs-json/）以及 “Hessian 协议解释与实战” 等文章来看，有几个原则值得重视的：

优先使用 boolean 型；
boolean 型满足不了，次优选择 int 整型数据；再次可以考虑 long 型；
日期优先使用内置的日期类型（含 Java Time API 类型），而不是格式化成字符串。
对于以上类型不满足，则选择使用字符串。
集合类型，链表优先使用 ArrayList，也可以考虑使用 Iterator；哈希优先使用 HashMap；
以上情况都不符合要求才选择自定义对象。

‍

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

据观察，一些开发人员没有将接口，尤其是 RPC 接口的参数及返回值打印到日志中。这对定位问题非常不利。说的更直白一点，非常不利于甩锅。当出了问题，不能第一时间就凭借参数及返回值顺利甩锅。可能导致自己花很多时间去排查问题，最后发现是自己依赖的其他系统的问题。

所以，一定要谨记，将接口的参数和返回值原始数据打印到日志中。凭借这个实践，在一些客诉及反馈中，顺利脱身，实现完美甩锅。

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

最近也在尝试一个实践：将 RPC 接口的类名和方法，再加上参数或者返回结果，同时打印到日志中。

这里为什么和上面的《将接口的参数和返回值原始数据打印到日志中》（https://www.diguage.com/post/tips-for-interface-maintainability/#log-param-and-result）单独列出来？因为，在这个实践中，强调的是 “RPC 接口”。相对来说， RPC 接口存在更多容易出错的问题，经常需要脱离系统去单独测试 RPC 接口的可用性。把类名就方法名可以更方便在出现问题时，就可以及时根据日志中的信息，去单独测试 RPC 的可用性。