【故障現(xiàn)場】將變更收斂在一處，避免散彈式更新

作者：geekhalo 2023-12-28 10:37:16

深入思考，該問題的本質(zhì)就是：對(duì)信息沒有進(jìn)行統(tǒng)一維護(hù)，導(dǎo)致同一份數(shù)據(jù)在多個(gè)地方進(jìn)行管理，當(dāng)發(fā)生變化時(shí)只要有一處未及時(shí)更新便會(huì)出現(xiàn)問題。

1. 問題&分析

使用 code 真香，終于不用擔(dān)心枚舉重構(gòu)了，但還是高興的太早了，一個(gè)線上bug正在路上….

1.1. 案例

經(jīng)過連續(xù)多天奮戰(zhàn)，系統(tǒng)終于上線了訂單手工取消功能，剛剛上線便收到客服部門的反饋：訂單列表中訂單狀態(tài)出現(xiàn)問題，顯示未 undefine。小艾趕緊查看后端日志，沒有發(fā)現(xiàn)任何異常，并緊急給前端負(fù)責(zé)人虎哥掛了個(gè)電話，很快虎哥便定位原因并進(jìn)行緊急修復(fù)。

事后復(fù)盤，原因是這樣的：

在訂單列表接口中，后端只返回了枚舉的 name
前端維護(hù)了一個(gè)配置文件，key 是 name，value 是顯示名稱，從接口獲取 name 后會(huì)基于配置文件進(jìn)行轉(zhuǎn)換，最終展示為描述信息
本次修改，只改了主站的 js 配置，遺漏了客服系統(tǒng)。所以，主站沒有問題，而客服系統(tǒng)由于找不到新加的name，所以展示為 undefine

后端返回結(jié)果如下圖所示：

圖片

默認(rèn)情況下，枚舉只會(huì)返回 Name，非常不利于展示，所以在前端會(huì)進(jìn)行一次翻譯，將 Name 翻譯成展示文案。

在這個(gè)接口的基礎(chǔ)上引起的問題如下圖所示：

圖片

由于業(yè)務(wù)發(fā)展，OrderStatus 的枚舉值發(fā)生了變化，但只對(duì)主站頁面進(jìn)行調(diào)整，而客服系統(tǒng)被遺漏。所以：

主站頁面有最新的全量配置，信息展示準(zhǔn)確沒有任何問題
客服系統(tǒng)由于被遺忘使用的還是之前的配置，導(dǎo)致后端返回的 Name 和配置信息不一致，由于找不到 Name 而出現(xiàn) undefine 錯(cuò)誤

1.2. 問題分析

那解法也就很簡單了，將信息收口到后端進(jìn)行統(tǒng)一管理！

除這個(gè)問題外，還有一個(gè)非常類似的問題：前端下拉列表，也需要和后端定義保持一致，一般情況下：

前端單獨(dú)維護(hù)，寫死在頁面，當(dāng)后端發(fā)生變化后，前端跟著一起調(diào)整。這個(gè)方案就會(huì)出現(xiàn)兩者不一致的問題，不鼓勵(lì)使用；
后端提供一個(gè)接口用于獲取數(shù)據(jù)，然后在渲染到前端組件。這個(gè)是鼓勵(lì)的方案，但每個(gè)枚舉都需要提供一個(gè)接口，增加了后端的開發(fā)負(fù)擔(dān)；

2. 解決方案

和 code 方案一致，可以使用接口對(duì)枚舉進(jìn)行約束。

2.1. 構(gòu)建統(tǒng)一接口

首先，定義統(tǒng)一的接口，用于提供描述信息：

public interface SelfDescribedEnum {
    default String getName(){
        return name();
    }

    String name();
    /**
    * 獲取描述信息
    */
    String getDescription();
}

2.2. 枚舉實(shí)現(xiàn)接口

然后，讓我們的枚舉實(shí)現(xiàn) SelfDescribedEnum 接口，具體如下：

public enum SelfDescribedEnumBasedOrderStatus implements SelfDescribedEnum {
    CREATED("待支付"),
    TIMEOUT_CANCELLED("超時(shí)取消"),
    MANUAL_CANCELLED("手工取消"),
    PAID("支付成功"),
    FINISHED("已完成");
    private final String description;

    SelfDescribedEnumBasedOrderStatus(String description) {
        this.description = description;
    }

    @Override
    public String getDescription() {
        return description;
    }
}

2.3. 集成 Spring MVC 返回結(jié)果

在完成上述工作后，我們將 OrderVO 中的 status 屬性類型更新為 SelfDescribedEnumBasedOrderStatus，具體如下：

@Data
public class OrderVO {
    private Long id;
    private SelfDescribedEnumBasedOrderStatus status;
}

最后一步也是最關(guān)鍵的一步便是，對(duì) Jackson 序列化器進(jìn)行定制，核心代碼如下：

@Configuration
public class SelfDescribedEnumJacksonCustomizer {

    @Bean
    public Jackson2ObjectMapperBuilderCustomizer commonEnumBuilderCustomizer(){
        return builder ->{
            // 注冊(cè)自定義枚舉序列化器
            builder.serializerByType(SelfDescribedEnum.class, new SelfDescribedEnumJsonSerializer());
        };
    }

    static class SelfDescribedEnumJsonSerializer extends JsonSerializer {

        @Override
        public void serialize(Object o, JsonGenerator jsonGenerator, SerializerProvider serializerProvider) throws IOException {
            SelfDescribedEnum selfDescribedEnum = (SelfDescribedEnum) o;
            SelfDescribedEnumVO selfDescribedEnumVO = SelfDescribedEnumVO.from(selfDescribedEnum);
            jsonGenerator.writeObject(selfDescribedEnumVO);
        }
    }
}

// SelfDescribedEnumVO 為定義的一個(gè) VO，具體如下：
@Data
public class SelfDescribedEnumVO {
    @ApiModelProperty(notes = "Name")
    private final String name;

    @ApiModelProperty(notes = "描述")
    private final String desc;

    public static SelfDescribedEnumVO from(SelfDescribedEnum selfDescribedEnum){
        if (selfDescribedEnum == null){
            return null;
        }
        return new SelfDescribedEnumVO(selfDescribedEnum.getName(), selfDescribedEnum.getDescription());
    }

    public static List<SelfDescribedEnumVO> from(List<SelfDescribedEnum> commonEnums){
        if (CollectionUtils.isEmpty(commonEnums)){
            return Collections.emptyList();
        }
        return commonEnums.stream()
                .filter(Objects::nonNull)
                .map(SelfDescribedEnumVO::from)
                .filter(Objects::nonNull)
                .collect(Collectors.toList());
    }
}

最后，啟動(dòng)服務(wù)查看新返回值，具體如下：

圖片

可以看，status 字段原本只返回了 name，現(xiàn)在返回的是一個(gè)包括 name 和 desc 的對(duì)象。前端無需進(jìn)行轉(zhuǎn)換，只需直接讀取 status.desc 信息即可。

2.4. 提供統(tǒng)一字典服務(wù)

對(duì)于下來列表、選擇框的場景，最優(yōu)方案是為前端提供一個(gè)統(tǒng)一的字典接口，由該接口來返回所有字典信息。

核心代碼如下：

public class EnumDictController {
    private Map<String, List<SelfDescribedEnum>> enumDict = new HashMap<String, List<SelfDescribedEnum>>();

    public EnumDictController(){
        add("OrderStatus", SelfDescribedEnumBasedOrderStatus.values());
    }

    private void add(String type, SelfDescribedEnumBasedOrderStatus[] values) {
        this.enumDict.put(type, Arrays.asList(values));
    }

    /**
     * 獲取所有字典信息
     * @return
     */
    @GetMapping("all")
    public RestResult<Map<String, List<SelfDescribedEnumVO>>> allEnums(){
        Map<String, List<SelfDescribedEnumVO>> dictVo = Maps.newHashMapWithExpectedSize(enumDict.size());
        for (Map.Entry<String, List<SelfDescribedEnum>> entry : enumDict.entrySet()){
            dictVo.put(entry.getKey(), SelfDescribedEnumVO.from(entry.getValue()));
        }
        return RestResult.success(dictVo);
    }

    /**
     * 獲取支持的全部字典類型
     * @return
     */
    @GetMapping("types")
    public RestResult<List<String>> enumTypes(){
        return RestResult.success(Lists.newArrayList(enumDict.keySet()));
    }

    /**
     * 獲取指定字典的全部值
     * @param type
     * @return
     */
    @GetMapping("/{type}")
    public RestResult<List<SelfDescribedEnumVO>> dictByType(@PathVariable("type") String type){
        List<SelfDescribedEnum> enums = enumDict.get(type);

        return RestResult.success(SelfDescribedEnumVO.from(enums));
    }
}

啟動(dòng)服務(wù)，驗(yàn)證字典接口。

獲取全部字典信息，返回結(jié)果如下：

圖片