我们一起聊聊枚举规范化

2024年 1月 2日 68.5k 0

1. 规范&封装

凡是只给规范,不给封装和工具的都是耍流氓。

规范是靠不住的,如果想保障落地质量必须对最佳实践进行封装!

  • 规范靠人来执行,但人是最靠不住的!
  • 封装复用才是王道,才是保障落地质量的重要手段。
  • 1.1. 规范化枚举

    枚举仅提供了 name 和 ordrial 两个特性,而这两个特性在重构时都会发生变化,为了更好的解决枚举的副作用,我们通过接口为其添加了新能力:

  • 添加 code 用作枚举的唯一标识
  • 添加 description 用于统一枚举的展示
  • 图片图片

    image

    为此,还定义了两个接口

  • CodeBasedEnum 提供 getCode 方法,增加唯一标识
  • SelfDescribedEnum 提供 getDescription 方法,增加枚举的描述信息
  • 在这两个接口基础之上,可以构建出通用枚举 CommonEnum,定义如下:

    // 定义统一的枚举接口
    public interface CommonEnum extends CodeBasedEnum, SelfDescribedEnum{
    
    }

    整体结构如下:

    图片图片

    在定义枚举时便可以直接实现 CommonEnum 这个接口。示例代码如下:

    public enum CommonOrderStatus implements CommonEnum {
        CREATED(1, "待支付"),
        TIMEOUT_CANCELLED(2, "超时取消"),
        MANUAL_CANCELLED(5, "手工取消"),
        PAID(3, "支付成功"),
        FINISHED(4, "已完成");
        private final int code;
        private final String description;
    
        CommonOrderStatus(int code, String description) {
            this.code = code;
            this.description = description;
        }
    
        @Override
        public String getDescription() {
            return description;
        }
    
        @Override
        public int getCode() {
            return this.code;
        }
    }

    1.2. 统一管理 CommonEnum

    使用 CommonEnum 最大的好处便是可以进行统一管理,对于统一管理,第一件事便是找到并注册所有的 CommonEnum 实现。整体架构如下:

    图片图片

    核心处理流程如下:

  • 首先通过 Spring 的 ResourcePatternResolver 根据配置的 basePackage 对 classpath 进行扫描
  • 扫描结果以 Resource 来表示,通过 MetadataReader 读取 Resource 信息,并将其解析为 ClassMetadata
  • 获得 ClassMetadata 之后,找出实现 CommonEnum 的类
  • 将 CommonEnum 实现类注册到两个 Map 中进行缓存
  • 备注:此处万万不可直接使用反射技术,反射会触发类的自动加载,将对众多不需要的类进行加载,从而增加 metaspace 的压力。

    在需要 CommonEnum 时,只需注入 CommonEnumRegistry Bean 便可以方便的获得 CommonEnum 的全部实现。

    1.3. Spring MVC 集成

    有了统一的 CommonEnum,便可以对枚举进行统一管理,由框架自动完成与 Spring MVC 的集成。集成内容包括:

  • 使用 code 作为输入参数的唯一标识,避免 name、ordrial 变化导致业务异常
  • 对返回值展示信息包括枚举的 code、name、description 等信息
  • 基于 CommonEnumRegistry 提供通用的枚举字典
  • 整体架构如下:

    图片图片

    1.3.1. 入参集成

    核心就是以 code 作为枚举的唯一标识,自动完成 code 到枚举的转化。

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

  • 对于普通参数,比如 RequestParam 或 PathVariable 直接从 ConditionalGenericConverter 进行扩展
  • 基于 CommonEnumRegistry 提供的 CommonEnum 信息,对 matches 和 getConvertibleTypes方法进行重写

    根据目标类型获取所有的 枚举值,并根据 code 和 name 进行转化

  • 对于 Json 参数,需要对 Json 框架进行扩展(以 Jackson 为例)
  • 遍历 CommonEnumRegistry 提供的所有 CommonEnum,依次进行注册

  • 从 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 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 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 commonEnums;
    
            CommonEnumJsonDeserializer(List 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);
            }
        }

    1.3.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 from(List 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);
            }
        }

    1.3.3. 通用枚举字典

    有了 CommonEnum 之后,可以提供统一的枚举字典接口,避免重复开发,同时在新增枚举时也无需编码,系统自动识别并添加到字典中。

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

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

    该 Controller 提供如下能力:

  • 获取全部字典,一次性获取系统中所有的 CommonEnum
  • 获取所有字典类型,仅获取字典类型,通常用于测试
  • 获取指定字典类型的全部信息,比如上述所说的填充下拉框
  • 1.4. 存储层集成

    存储层并没有提供足够的扩展能力,并不能自动向框架注册类型转换器。但,由于逻辑都是想通的,框架提供了公共父类来实现复用。

    1.4.1. MyBatis 集成

    CommonEnumTypeHandler 实现 MyBatis 的 BaseTypeHandler接口,为 CommonEnum 提供的通用转化能力,具体如下:

    public abstract  class CommonEnumTypeHandler
            extends BaseTypeHandler {
        private final List commonEnums;
    
        protected CommonEnumTypeHandler(T[] commonEnums){
            this(Arrays.asList(commonEnums));
        }
    
        protected CommonEnumTypeHandler(List 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);
        }
    }

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

    1.4.2. JPA 集成

    CommonEnumAttributeConverter 实现 JPA 的 AttributeConverter 接口,为 CommonEnum 提供的通用转化能力,具体如下:

    public abstract class CommonEnumAttributeConverter
            implements AttributeConverter {
        private final List commonEnums;
    
        public CommonEnumAttributeConverter(E[] commonEnums){
            this(Arrays.asList(commonEnums));
        }
    
        public CommonEnumAttributeConverter(List 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);
        }
    }

    2. 应用示例

    在有封装后,业务代码将变的非常简单。

    2.1. 项目配置

    由于是在 lego 项目中进行的封装,第一步便是引入lego依赖,具体如下:

    
        com.geekhalo.lego
        lego-starter
        0.1.23
    

    为了能自动识别 CommonEnum 的实现,需要指定扫描包,具体如下:

    baseEnum:
      basePackage: com.geekhalo.demo

    项目启动时,CommonEnumRegistry 会自动扫描包下的 CommonEnum 实现,并完成注册。

    最后,需要在启动类上增加如下配置:

    @ComponentScan(value = "com.geekhalo.lego.core.enums")

    从而,让 Spring完成核心组件的加载。

    2.2. Spring MVC 示例

    完成以上配置后,Spring MVC 就已经完成集成。新建一个 OrderStatus 枚举,具体如下:

    public enum CommonOrderStatus implements CommonEnum {
        CREATED(1, "待支付"),
        TIMEOUT_CANCELLED(2, "超时取消"),
        MANUAL_CANCELLED(5, "手工取消"),
        PAID(3, "支付成功"),
        FINISHED(4, "已完成");
        private final int code;
        private final String description;
    
        CommonOrderStatus(int code, String description) {
            this.code = code;
            this.description = description;
        }
    
        @Override
        public String getDescription() {
            return description;
        }
    
        @Override
        public int getCode() {
            return this.code;
        }
    }

    2.2.1. 入参示例

    如下图所示:

    图片图片

    可见,status:3 系统自动转换为 PAID,成功完成了 code 到 CommonOrderStatus 的转换。

    2.2.2. 返回结果示例

    图片图片

    返回结果也不再是简单的name,而是一个对象,返回字段包括:code、name、desc 等。

    2.2.3. 通用字典示例

    通过 swagger 可以看到增加一个字典Controller 如下:

    图片图片

    /enumDict/types 返回已加载的所有字段类型,如下所示:

    图片图片

    系统中只有一个实现类 CommonOrderStatus,新增实现类会自动出现在这里。

    /enumDict/all 返回所有字典信息,如下所示:

    图片图片

    一次性返回全部字典信息。

    /enumDict/{type} 返回指定字典信息,如下所示:

    图片图片

    指定返回 CommonOrderStatus 字典。

    2.3. 存储层示例

    有了可复用的公共父类后,类型转换器变的非常简单。

    2.3.1. MyBatis 类型转化器

    MyBatis 类型转换器只需继承自 CommonEnumTypeHandler 即可,具体代码如下:

    @MappedTypes(CommonOrderStatus.class)
    public class CommonOrderStatusTypeHandler extends CommonEnumTypeHandler {
        public CommonOrderStatusTypeHandler() {
            super(CommonOrderStatus.values());
        }
    }

    当然,别忘了添加 MyBatis 配置:

    mybatis:
      type-handlers-package: com.geekhalo.demo.enums.code.fix

    2.3.2. JPA 类型转化器

    JPA 类型转化器只需继承自 CommonEnumAttributeConverter 即可,具体代码如下:

    @Converter(autoApply = true)
    public class CommonOrderStatusAttributeConverter extends CommonEnumAttributeConverter {
        public CommonOrderStatusAttributeConverter() {
            super(CommonOrderStatus.values());
        }
    }

    如有必要,可以在实体类的属性上增加 注解,具体如下:

    /**
     * 指定枚举的转换器
     */
    @Convert(converter = CommonOrderStatusAttributeConverter.class)
    private CommonOrderStatus status;

    3. 示例&源码

    代码仓库:https://gitee.com/litao851025/learnFromBug

    代码地址:https://gitee.com/litao851025/learnFromBug/tree/master/src/main/java/com/geekhalo/demo/enums/support

    相关文章

    JavaScript2024新功能:Object.groupBy、正则表达式v标志
    PHP trim 函数对多字节字符的使用和限制
    新函数 json_validate() 、randomizer 类扩展…20 个PHP 8.3 新特性全面解析
    使用HTMX为WordPress增效:如何在不使用复杂框架的情况下增强平台功能
    为React 19做准备:WordPress 6.6用户指南
    如何删除WordPress中的所有评论

    发布评论