1. 概览

枚举作为 Java 5 的重要特征，相信大家并不陌生，但在实际开发过程中，当 name 和 ordrial 发生变化时，如果处理不当非常容易引起系统bug。这种兼容性bug非常难以定位，需要从框架层次进行避免，而非仅靠开发人员的主观意识。

1.1. 背景

枚举很好用，特别是提供的 name 和 ordrial 特性，但这点对重构造成了一定影响，比如：

1. 某个枚举值业务语义发生变化，需要将其进行 rename 操作，以更好的表达新业务语义
2. 新增、删除或者为了展示调整了枚举定义顺序

这些在业务开发中非常常见，使用 IDE 的 refactor 功能可以快速且准确的完成重构工作。但，如果系统将这些暴露出去或者存储到数据库等存储引擎就变得非常麻烦，不管是 name 还是 ordrial 的变更都会产生兼容性问题。

对此，最常见的解决方案便是放弃使用 name 和 ordrial，转而使用控制能力更强的 code。

1.2. 目标

提供一组工具，以方便的基于 code 使用枚举，快速完成对现有框架的集成：

1. 完成与 Spring MVC 的集成，基于 code 使用枚举；加强返回值，以对象的方式进行返回，信息包括 code、name、description
2. 提供统一的枚举字典，自动扫描系统中的枚举并将其以 restful 的方式暴露给前端
3. 使用 code 进行数据存储操作，避免重构的影响

2. 快速入门

2.1. 添加 starter

在 Spring boot 项目的 pom 中增加如下依赖：

<groupId>com.geekhalo.lego</groupId>
<artifactId>lego-starter</artifactId>
<version>0.1.19-enum-SNAPSHOT</version>

2.2. 统一枚举结构

如何统一枚举行为呢？公共父类肯定是不行的，但可以为其提供一个接口，在接口中完成行为的定义。

2.2.1. 定义枚举接口

除了在枚举中自定义 code 外，通常还会为其提供描述信息，构建接口如下：

public interface CodeBasedEnum {
    int getCode();
}
public interface SelfDescribedEnum {
    default String getName(){
        return name();
    }
    String name();
    String getDescription();
}
public interface CommonEnum extends CodeBasedEnum, SelfDescribedEnum{
}

整体结构如下：

image

在定义枚举时便可以直接使用CommonEnum这个接口。

2.2.2. 实现枚举接口

有了统一的枚举接口，在定义枚举时便可以直接实现接口，从而完成对枚举的约束。

public enum NewsStatus implements CommonEnum {
    DELETE(1, "删除"),
    ONLINE(10, "上线"),
    OFFLINE(20, "下线");
    private final int code;
    private final String desc;
    NewsStatus(int code, String desc) {
        this.code = code;
        this.desc = desc;
    }
    @Override
    public int getCode() {
        return this.code;
    }
    @Override
    public String getDescription() {
        return this.desc;
    }
}

2.3. 自动注册 CommonEnum

有了统一的 CommonEnum 最大的好处便是可以进行统一管理，对于统一管理，第一件事便是找到并注册所有的 CommonEnum。

image

以上是核心处理流程：

1. 首先通过 Spring 的 ResourcePatternResolver 根据配置的 basePackage 对classpath进行扫描
2. 扫描结果以Resource来表示，通过 MetadataReader 读取 Resource 信息，并将其解析为 ClassMetadata
3. 获得 ClassMetadata 之后，找出实现 CommonEnum 的类
4. 将 CommonEnum 实现类注册到两个 Map 中进行缓存

备注：此处万万不可直接使用反射技术，反射会触发类的自动加载，将对众多不需要的类进行加载，从而增加 metaspace 的压力。

在需要 CommonEnum 时，只需注入 CommonEnumRegistry Bean 便可以方便的获得 CommonEnum 的具体实现。

2.4. Spring MVC 接入层

Web 层是最常见的接入点，对于 CommonEnum 我们倾向于：

1. 参数使用 code 来表示，避免 name、ordrial 变化导致业务异常
2. 丰富返回值，包括枚举的 code、name、description 等

image

2.4.1. 入参转化

Spring MVC 存在两种参数转化扩展：

1. 对于普通参数，比如 RequestParam 或 PathVariable 直接从 ConditionalGenericConverter 进行扩展
1. 基于 CommonEnumRegistry 提供的 CommonEnum 信息，对 matches 和 getConvertibleTypes方法进行重写
2. 根据目标类型获取所有的 枚举值，并根据 code 和 name 进行转化
2. 对于 Json 参数，需要对 Json 框架进行扩展（以 Jackson 为例）
1. 遍历 CommonEnumRegistry 提供的所有 CommonEnum，依次进行注册
2. 从 Json 中读取信息，根据 code 和 name 转化为确定的枚举值

两种扩展核心实现见：

@Order(1)
@Component
public class CommonEnumConverter implements ConditionalGenericConverter {
    @Autowired
    private CommonEnumRegistry enumRegistry;
    @Override
    public boolean matches(TypeDescriptor sourceType, TypeDescriptor targetType) {
        Class<?> type = targetType.getType();
        return enumRegistry.getClassDict().containsKey(type);
    }
    @Override
    public Set<ConvertiblePair> getConvertibleTypes() {
        return enumRegistry.getClassDict().keySet().stream()
                .map(cls -> new ConvertiblePair(String.class, cls))
                .collect(Collectors.toSet());
    }
    @Override
    public Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType) {
        String value = (String) source;
        List<CommonEnum> commonEnums = this.enumRegistry.getClassDict().get(targetType.getType());
        return commonEnums.stream()
                .filter(commonEnum -> commonEnum.match(value))
                .findFirst()
                .orElse(null);
    }
}
static class CommonEnumJsonDeserializer extends JsonDeserializer{
        private final List<CommonEnum> commonEnums;
        CommonEnumJsonDeserializer(List<CommonEnum> commonEnums) {
            this.commonEnums = commonEnums;
        }
        @Override
        public Object deserialize(JsonParser jsonParser, DeserializationContext deserializationContext) throws IOException, JacksonException {
            String value = jsonParser.readValueAs(String.class);
            return commonEnums.stream()
                    .filter(commonEnum -> commonEnum.match(value))
                    .findFirst()
                    .orElse(null);
        }
    }

2.4.2. 增强返回值

默认情况下，对于枚举类型在转换为 Json 时，只会输出 name，其他信息会出现丢失，对于展示非常不友好，对此，需要对 Json 序列化进行能力增强。

首先，需要定义 CommonEnum 对应的返回对象，具体如下：

@Value
@AllArgsConstructor(access = AccessLevel.PRIVATE)
@ApiModel(description = "通用枚举")
public class CommonEnumVO {
    @ApiModelProperty(notes = "Code")
    private final int code;
    @ApiModelProperty(notes = "Name")
    private final String name;
    @ApiModelProperty(notes = "描述")
    private final String desc;
    public static CommonEnumVO from(CommonEnum commonEnum){
        if (commonEnum == null){
            return null;
        }
        return new CommonEnumVO(commonEnum.getCode(), commonEnum.getName(), commonEnum.getDescription());
    }
    public static List<CommonEnumVO> from(List<CommonEnum> commonEnums){
        if (CollectionUtils.isEmpty(commonEnums)){
            return Collections.emptyList();
        }
        return commonEnums.stream()
                .filter(Objects::nonNull)
                .map(CommonEnumVO::from)
                .filter(Objects::nonNull)
                .collect(Collectors.toList());
    }
}

CommonEnumVO 是一个标准的 POJO，只是增加了 Swagger 相关注解。

CommonEnumJsonSerializer 是自定义序列化的核心，会将 CommonEnum 封装为 CommonEnumVO 并进行写回，具体如下：

static class CommonEnumJsonSerializer extends JsonSerializer{
        @Override
        public void serialize(Object o, JsonGenerator jsonGenerator, SerializerProvider serializerProvider) throws IOException {
            CommonEnum commonEnum = (CommonEnum) o;
            CommonEnumVO commonEnumVO = CommonEnumVO.from(commonEnum);
            jsonGenerator.writeObject(commonEnumVO);
        }
    }

2.4.3. 效果展示

首先，新建一个测试枚举 NewsStatus，具体如下：

public enum NewsStatus implements CommonEnum {
    DELETE(1, "删除"),
    ONLINE(10, "上线"),
    OFFLINE(20, "下线");
    private final int code;
    private final String desc;
    NewsStatus(int code, String desc) {
        this.code = code;
        this.desc = desc;
    }
    @Override
    public int getCode() {
        return this.code;
    }
    @Override
    public String getDescription() {
        return this.desc;
    }
}

然后新建 EnumController，具体如下：

@RestController
@RequestMapping("enum")
public class EnumController {
    @GetMapping("paramToEnum")
    public RestResult<CommonEnumVO> paramToEnum(@RequestParam("newsStatus") NewsStatus newsStatus){
        return RestResult.success(CommonEnumVO.from(newsStatus));
    }
    @GetMapping("pathToEnum/{newsStatus}")
    public RestResult<CommonEnumVO> pathToEnum(@PathVariable("newsStatus") NewsStatus newsStatus){
        return RestResult.success(CommonEnumVO.from(newsStatus));
    }
    @PostMapping("jsonToEnum")
    public RestResult<CommonEnumVO> jsonToEnum(@RequestBody NewsStatusRequestBody newsStatusRequestBody){
        return RestResult.success(CommonEnumVO.from(newsStatusRequestBody.getNewsStatus()));
    }
    @GetMapping("bodyToJson")
    public RestResult<NewsStatusResponseBody> bodyToJson(){
        NewsStatusResponseBody newsStatusResponseBody = new NewsStatusResponseBody();
        newsStatusResponseBody.setNewsStatus(Arrays.asList(NewsStatus.values()));
        return RestResult.success(newsStatusResponseBody);
    }
    @Data
    public static class NewsStatusRequestBody {
        private NewsStatus newsStatus;
    }
    @Data
    public static class NewsStatusResponseBody {
        private List<NewsStatus> newsStatus;
    }
}

执行结果如下：

image

整体符合预期：

1. 使用 code 作为请求参数可以自动转化为对应的 CommonEnum
2. 使用 CommonEnum 作为返回值，返回标准的 CommonEnumVO 对象结构

2.5. 通用枚举字典接口

有时可以将 枚举 理解为系统的一类字段，比较典型的就是管理页面的各种下拉框，下拉框中的数据来自于后台服务。

有了 CommonEnum 之后，可以提供统一的一组枚举字典，避免重复开发，同时在新增枚举时也无需进行扩展，系统自动识别并添加到字典中。

2.5.1. 构建字典Controller

在 CommonEnumRegistry 基础之上实现通用字典接口非常简单，只需按规范构建 Controller 即可，具体如下：

@Api(tags = "通用字典接口")
@RestController
@RequestMapping("/enumDict")
@Slf4j
public class EnumDictController {
    @Autowired
    private CommonEnumRegistry commonEnumRegistry;
    @GetMapping("all")
    public RestResult<Map<String, List<CommonEnumVO>>> allEnums(){
        Map<String, List<CommonEnum>> dict = this.commonEnumRegistry.getNameDict();
        Map<String, List<CommonEnumVO>> dictVo = Maps.newHashMapWithExpectedSize(dict.size());
        for (Map.Entry<String, List<CommonEnum>> entry : dict.entrySet()){
            dictVo.put(entry.getKey(), CommonEnumVO.from(entry.getValue()));
        }
        return RestResult.success(dictVo);
    }
    @GetMapping("types")
    public RestResult<List<String>> enumTypes(){
        Map<String, List<CommonEnum>> dict = this.commonEnumRegistry.getNameDict();
        return RestResult.success(Lists.newArrayList(dict.keySet()));
    }
    @GetMapping("/{type}")
    public RestResult<List<CommonEnumVO>> dictByType(@PathVariable("type") String type){
        Map<String, List<CommonEnum>> dict = this.commonEnumRegistry.getNameDict();
        List<CommonEnum> commonEnums = dict.get(type);
        return RestResult.success(CommonEnumVO.from(commonEnums));
    }
}

该 Controller 提供如下能力：

1. 获取全部字典，一次性获取系统中所有的 CommonEnum
2. 获取所有字典类型，仅获取字典类型，通常用于测试
3. 获取指定字典类型的全部信息，比如上述所说的填充下拉框

2.5.2. 效果展示

获取全部字典：

image

获取所有字典类型：

image

获取指定字段类型的全部信息：

image

2.6. 输出适配器

输出适配器主要以 ORM 框架为主，同时各类 ORM 框架均提供了类型映射的扩展点，通过该扩展点可以对 CommonEnum 使用 code 进行存储。

2.6.1. MyBatis 支持

MyBatis 作为最流行的 ORM 框架，提供了 TypeHandler 用于处理自定义的类型扩展。

@MappedTypes(NewsStatus.class)
public class MyBatisNewsStatusHandler extends CommonEnumTypeHandler<NewsStatus> {
    public MyBatisNewsStatusHandler() {
        super(NewsStatus.values());
    }
}

MyBatisNewsStatusHandler 通过 @MappedTypes(NewsStatus.class) 对其进行标记，以告知框架该 Handler 是用于 NewsStatus 类型的转换。

CommonEnumTypeHandler 是为 CommonEnum 提供的通用转化能力，具体如下：

public abstract  class CommonEnumTypeHandler<T extends Enum<T> & CommonEnum>
        extends BaseTypeHandler<T> {
    private final List<T> commonEnums;
    protected CommonEnumTypeHandler(T[] commonEnums){
        this(Arrays.asList(commonEnums));
    }
    protected CommonEnumTypeHandler(List<T> commonEnums) {
        this.commonEnums = commonEnums;
    }
    @Override
    public void setNonNullParameter(PreparedStatement preparedStatement, int i, T t, JdbcType jdbcType) throws SQLException {
        preparedStatement.setInt(i, t.getCode());
    }
    @Override
    public T getNullableResult(ResultSet resultSet, String columnName) throws SQLException {
        int code = resultSet.getInt(columnName);
        return commonEnums.stream()
                .filter(commonEnum -> commonEnum.match(String.valueOf(code)))
                .findFirst()
                .orElse(null);
    }
    @Override
    public T getNullableResult(ResultSet resultSet, int i) throws SQLException {
        int code = resultSet.getInt(i);
        return commonEnums.stream()
                .filter(commonEnum -> commonEnum.match(String.valueOf(code)))
                .findFirst()
                .orElse(null);
    }
    @Override
    public T getNullableResult(CallableStatement callableStatement, int i) throws SQLException {
        int code = callableStatement.getInt(i);
        return commonEnums.stream()
                .filter(commonEnum -> commonEnum.match(String.valueOf(code)))
                .findFirst()
                .orElse(null);
    }
}

由于逻辑比较简单，在此不做过多解释。

有了类型之后，需要在 spring boot 的配置文件中指定 type-handler 的加载逻辑，具体如下：

mybatis:
  type-handlers-package: com.geekhalo.lego.enums.mybatis

完成配置后，使用 Mapper 对数据进行持久化，数据表中存储的便是 code 信息，具体如下：

image

2.6.2. JPA 支持

随着 Spring data 越来越流行，JPA 又焕发出新的活力，JPA 提供 AttributeConverter 以对属性转换进行自定义。

首先，构建 JpaNewsStatusConverter，具体如下：

public class JpaNewsStatusConverter extends CommonEnumAttributeConverter<NewsStatus> {
    public JpaNewsStatusConverter() {
        super(NewsStatus.values());
    }
}

CommonEnumAttributeConverter 为 CommonEnum 提供的通用转化能力，具体如下：

public abstract class CommonEnumAttributeConverter<E extends Enum<E> & CommonEnum>
        implements AttributeConverter<E, Integer> {
    private final List<E> commonEnums;
    public CommonEnumAttributeConverter(E[] commonEnums){
        this(Arrays.asList(commonEnums));
    }
    public CommonEnumAttributeConverter(List<E> commonEnums) {
        this.commonEnums = commonEnums;
    }
    @Override
    public Integer convertToDatabaseColumn(E e) {
        return e.getCode();
    }
    @Override
    public E convertToEntityAttribute(Integer code) {
        return (E) commonEnums.stream()
                .filter(commonEnum -> commonEnum.match(String.valueOf(code)))
                .findFirst()
                .orElse(null);
    }
}

在有了 JpaNewsStatusConverter 之后，我们需要在 Entity 的属性上增加配置信息，具体如下：

@Entity
@Data
@Table(name = "t_jpa_news")
public class JpaNewsEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    @Convert(converter = JpaNewsStatusConverter.class)
    private NewsStatus status;
}

@Convert(converter = JpaNewsStatusConverter.class) 是对 status 的配置，使用 JpaNewsStatusConverter 进行属性的转换。

运行持久化指令后，数据库如下：

image

3. 项目信息

项目仓库地址：https://gitee.com/litao851025/lego

项目文档地址：https://gitee.com/litao851025/lego/wikis/support/enums