作者：D瓜哥

在做新需求開發或者相關係統的維護更新時，尤其是涉及到不同系統的接口調用時，在可維護性方面，總感覺有很多地方差強人意。一些零星思考，拋磚引玉，希望引發更多的思考和討論。總結了大概有如下幾條建議：

1. 在接口註釋中加入接口文檔鏈接
2. 將調用接口處寫上被調用接口文檔鏈接
3. 將接口源代碼發佈到私服倉庫
4. 對於狀態值常量，優先在接口參數類或者返回值類中定義
5. 如果使用 Map 對象作為傳輸載體，要提供 Key 值定義常量
6. 針對 Map 返回值，可以考慮使用將 Map 轉化成對象
7. 儘可能簡化接口依賴
8. 只傳遞必要字段，儘量避免大而全的接口
9. 將接口的參數和返回值原始數據打印到日誌中
10. 將 RPC 接口的類名及方法打印到日誌中
11. 核心思想：以人為本，就近原則，觸手可及

下面，D瓜哥對每一條建議做一個詳細説明。

1. 在接口註釋中加入接口文檔鏈接

在做接口開發時，無論是對自有接口的升級改造，還是針對外部接口的從頭接入，都涉及到接口文檔。不同之處是，前者的工作重點是書寫或者更新接口文檔；而後者是根據接口文檔開發合適的接入代碼。但是，經常遇到的一個麻煩是，找不到接口文檔。在組內需要找老同事詢問；如果是跨部門，還需要兩層甚至三層的進行轉接，非常麻煩。

D瓜哥認為，在這種情況下，為了方便大家維護，最好的辦法就是將接口文檔鏈接直接放在代碼註釋中，這樣後續維護的人員，直接就可以點擊鏈接直達接口文檔，簡單方便高效。如果是新建的接口，就可以先創建一個空文檔，把鏈接放在註釋中，後續再書寫文檔內容。如果是維護已有接口，可以在維護時，將缺失的鏈接加入到註釋中，自己方便，也方便其他人進行後續的維護更新。這樣，在循序漸進的過程中，逐步就可以把文檔鏈接補充到代碼中，方便維護代碼，也同步更新文檔。

2. 將調用接口處寫上被調用接口文檔鏈接

在調用其他系統的接口時，沒有接口文檔，幾乎寸步難行。在第一次接入接口時，絕大多數情況下，都是參考着接口文檔做接入工作。但是，目前的情況時，接入時參考文檔，參考完就隨手把文檔給“扔了”。後續如果還需要做進一步升級維護，還需要到處找接口文檔；另外，交互的系統難免有一些 Bug，在和其他系統維護人員對接處理 Bug 時，只有接口沒有文檔，對方可能也需要去找文檔鏈接。無形中，很多時間都浪費在了找文檔的過程中。

D瓜哥最近嘗試了一個實踐，就是在接口調用的地方，把接口文檔鏈接當做註釋加入到代碼中。這樣，無論是後續維護升級，還是溝通協調處理問題，都非常方便。別人問接口是什麼，連接口+文檔都可以一把複製就搞定。

經過最近一段時間的實踐情況來看，這個處理非常方便，是一個非常值得推廣的實踐。再插一句，也可以像一條建議一樣，可以在維護代碼時，不斷把已接入的接口文檔加入到調用接口的地方，循序漸進，方便後續人維護升級。

3. 將接口源代碼發佈到私服倉庫

接口文檔鏈接在註釋中，在構建結果中就不復存在了。所以，為了方便接口使用方可以在接口中查詢到對應的接口文檔，就需要把源碼也發佈到私服倉庫中。

這裏只説明一下 Java 的相關處理辦法。如果使用 Maven 作為構建工具的話，默認是不會將源代碼發佈到私服倉庫中的。關於如何將源代碼發佈到，在 升級 Maven 插件：將源碼發佈到私服倉庫 中已經做過相關介紹，這裏就不再贅述。

除了將源碼發佈到私服倉庫，另外，還建議編譯構建時，保持方法的原始參數命名。這個也可以通過配置 Maven 插件來完成，具體配置見： 升級 Maven 插件：字節碼文件包含原始參數名稱。

4. 對於狀態值常量，優先在接口參數類或者返回值類中定義

在做接口開發時，很多數據都有一個狀態值，比如訂單狀態，再比如接口狀態等等。目前的一個情況時，這些狀態值大部分書寫在文檔中，在接入接口時，需要接入方自定義這些狀態值。這就有些繁瑣了，而且狀態定義也不明確，甚至有可能遺漏一些重要的狀態值。有些懶省事，直接在代碼中硬編碼一個魔法值，後續維護的跟還需要根據上下文反推這個值的含義，非常不利於維護。

D瓜哥個人覺得，有兩個處理辦法：

1. 如果狀態值不是很多，優先在接口參數類或者返回值類中定義。
2. 如果狀態值很多，可以考慮單獨抽取成一個常量類或者枚舉類。

這樣使用的時候，觸手可及。不需要到處去找。

5. 如果使用 Map 對象作為傳輸載體，要提供 Key 值定義常量

有些系統可能考慮方便增加字段，選擇使用 Map 作為數據載體。自己開發的時候很爽，但是給接口接入卻非常不友好。接入方從 Map 中獲取數據時，要麼自己定義 Key 值；要麼直接使用魔法值硬編碼在代碼中。使用前者方案，就需要在各個接入方都需要自定義一套；使用後者，初期是省事了，後來維護的人員就懵逼了。這都無形中增加了很多維護成本。

D瓜哥覺得一個方案更優，那就是直接由接口提供方來定義這些可以取值的 Key 值常量。這樣，任何接入方都可以直接使用這些常量。

6. 針對 Map 返回值，可以考慮使用將 Map 轉化成對象

針對 Map 的處理，即使按照 如果使用 Map 對象作為傳輸載體，要提供 Key 值定義常量 推薦的做法，定義了相關的 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;
    }
}

7. 儘可能簡化接口依賴

現在，很多對外暴露接口的定義是，接口定義放在一個模塊中；模型定義在一個模塊中；有些工具類又定義在一個模塊中。接口依賴模型模塊；模型模塊又依賴工具類模塊；而工具類依賴了一大堆外部依賴。個人覺得這是一個非常不好的實踐。會導致很多不必要的依賴被間接引入到了接口使用方的系統中，無形中增加很多維護成本。

D瓜哥推薦的一個實踐是：將接口和模型定義放在一個模塊中，對外暴露也只需要這一個模塊即可。接口使用方只需要引入這一個依賴。避免引入很多無用的其他外部依賴。如果模型需要依賴一些公共的父類，可以考慮將這些單獨定義在一個模塊中，這個模塊只保存多個系統依賴的公共類，並且剔除掉一些工具類的定義，這樣就可以保證接口依賴的純淨性。如果其他系統需要工具類，讓其明確去引入，而不是被動依賴。

對於前面 對於狀態值常量，優先在接口參數類或者返回值類中定義 中提到了“如果狀態值很多，可以考慮單獨抽取成一個常量類或者枚舉類。” 這裏存在一種情況需要特別説明，狀態值的定義需要在本系統的業務模塊的代碼中使用，可以將接口的依賴加入到改業務模塊的依賴中，而不是反過來。為什麼會這樣的操作？一個核心思想是保持對外暴露接口的純淨性。這樣既可以減少狀態定義的重複性，又可以減少接口的外部依賴。

8. 只傳遞必要字段，儘量避免大而全的接口

觀察很多系統，尤其是一些以業務為核心的系統的對外暴露接口，很多接口是大而全的接口，一個接口就可以把指定數據的所有信息全部返回出去。這樣，很多字段需要去識別，也要在眾多字段中區篩選出來符合自己要求的數據，無形中浪費了很多心智，不利於維護。

D瓜哥認為，在做接口開發時，一定要做一個“吝嗇的守財奴”。把數據當做財富一樣守護，對外只提供必要的數據，做到“夠用就行”。

這一點不僅僅是維護上的考慮，還有數據傳輸效率的點。在其他條件相同的情況下，更小的數據，無論是機器處理效率，還是傳輸效率，都會更快更高。

關於傳輸效率上的一些思考，結合 Hessian、Msgpack 和 JSON 實例對比 以及 “Hessian 協議解釋與實戰” 等文章來看，有幾個原則值得重視的：

1. 優先使用 boolean 型；
2. boolean 型滿足不了，次優選擇 int 整型數據；再次可以考慮 long 型；
3. 日期優先使用內置的日期類型（含 Java Time API 類型），而不是格式化成字符串。
4. 對於以上類型不滿足，則選擇使用字符串。
5. 集合類型，鏈表優先使用 ArrayList，也可以考慮使用 Iterator；哈希優先使用 HashMap；
6. 以上情況都不符合要求才選擇自定義對象。

9. 將接口的參數和返回值原始數據打印到日誌中

據觀察，一些開發人員沒有將接口，尤其是 RPC 接口的參數及返回值打印到日誌中。這對定位問題非常不利。説的更直白一點，非常不利於甩鍋。當出了問題，不能第一時間就憑藉參數及返回值順利甩鍋。可能導致自己花很多時間去排查問題，最後發現是自己依賴的其他系統的問題。

所以，一定要謹記，將接口的參數和返回值原始數據打印到日誌中。D瓜哥憑藉這個實踐，在一些客訴及反饋中，順利脱身，實現完美甩鍋。

10. 將 RPC 接口的類名及方法打印到日誌中

D瓜哥也在嘗試一個實踐：將 RPC 接口的類名和方法，再加上參數或者返回結果，同時打印到日誌中。

這裏為什麼和上面的 將接口的參數和返回值原始數據打印到日誌中 單獨列出來？因為，在這個實踐中，強調的是 “RPC 接口”。相對來説， RPC 接口存在更多容易出錯的問題，經常需要脱離系統去單獨測試 RPC 接口的可用性。把類名就方法名可以更方便在出現問題時，就可以及時根據日誌中的信息，去單獨測試 RPC 的可用性。

11. 核心思想：以人為本，就近原則，觸手可及

洋洋灑灑總結了這麼幾條建議。這裏做一個總結。

對於可維護性建議的一個核心思想就是：以人為本，就近原則，觸手可及。通常來説，人都是有一定的惰性的。如果把飯端到眼前，相信任何正常人無法抗拒美食的誘惑。而這裏提到的一些可維護性的點，就是儘可能照顧人“懶”的特性，在第一次時，就把該做的工作做到位，減少後續人員不必要的麻煩，讓人可以“合法偷懶”。

加油！爭取讓更多人可以更好地偷懶。💪🏻💪🏻💪🏻