SpringBoot 实战：优雅的使用枚举参数

妖狐艹你老母 2021-09-25 13:16 509阅读 0赞

![Spring 实战：优雅的使用枚举参数][Spring]

> 该图片由[Sinousxl][]在[Pixabay][]上发布

你好，我是看山。

接口开发过程中不免有表示类型的参数，比如 0 表示未知，1 表示男，2 表示女。通常有两种做法，一种是用数字表示，另一种是使用枚举实现。

使用数字表示就是通过契约形式，约定每个数字表示的含义，接口接收到参数，就按照约定对类型进行判断，接口维护成本比较大。

在 Spring 体系中，使用枚举表示，是借助 Spring 的 Converter 机制，可以将数字或字符串对应到枚举的序号或者 name，然后将前端的输入转换为枚举类型。

在场景不复杂的场景中，枚举可以轻松胜任。

于是，迅速实现逻辑，准备提测。这个时候需求变了，不允许选择未知性别，只能选男或女，就没有 0 值。这样，因为取值是从 1 开始，而枚举的序号是从 0 开始，就会产生冲突。

还有一些不太多的场景，就是前端不期望类型都是用数字，可能期望用一些有意义的字符串表示。但是按照前端规范，需要用小写或者驼峰命名。但是后端的规范中，枚举必须是大写，又是冲突。

需求合不合理暂且不论，我们要保存对技术的探索精神。

## 确认需求 ##

首先确认需求。我们期望定义一个枚举类作为参数，接口访问的时候，可以是 int 类型的 id，id 取值不限于枚举的序号；也可以是 String 类型的 code，code 取值不限于枚举的 name。换句话说，这个枚举有个 id 和 code，随意定义，只要接口传过来匹配上，就能够自动转成枚举类型。

既然这样，我们就规范下 id 和 code 取值。为了扩展，定义三个接口：IdBaseEnum、CodeBaseEnum 以及 IdCodeBaseEnum。

public interface IdBaseEnum { 
        Integer getId();
    }
    
    public interface CodeBaseEnum { 
        String getCode();
    }
    
    public interface IdCodeBaseEnum extends IdBaseEnum, CodeBaseEnum { 
    }

接下来就该定义我们的主角了。

## 定义枚举 ##

前面定义了三个接口，分别是单独 id、单独 code，和有 id 和 code 的。这样，我们就可以定义三种枚举，分别对应三个接口。三种方式类似，所以就不在文中重复列举了。感兴趣的可以关注公众号「看山的小屋」回复 spring 获取源码。

我们定义一个性别枚举，枚举包含 id 和 code 两个属性。

public enum GenderIdCodeEnum implements IdCodeBaseEnum { 
        MALE(1, "male"),
        FEMALE(2, "female");
    
        private final Integer id;
        private final String code;
    
        GenderIdCodeEnum(Integer id, String code) { 
            this.id = id;
            this.code = code;
        }
    
        @Override
        public String getCode() { 
            return code;
        }
    
        @Override
        public Integer getId() { 
            return id;
        }
    }

这里需要注意一点，id 和 code 不能重复。

1.  id 与 id、code 与 code 不能重复，比如 MAIL 定义 id 是 1，FAMLE 就不能定义 id 是 1 了。
2.  id 与 code 之间也不能重复，比如，MALE 定义 id 是 1001，FEMALE 定义 code 是 1001。

这是由于 Spring 在转换参数的时候，将输入参数全部视为 String 类型。虽然我们定义 id 和 code 类型不同，但是在匹配的时候，都是按照字符串匹配的。如果存在相同值，就会产生歧义。

## Converter 和 ConverterFactory ##

根据规范，接下来定义一下 Converter 和 ConverterFactory。这些是 Spring 留给我们的扩展口，按照规范定义即可。

Converter 类：

public class IdCodeToEnumConverter<T extends IdCodeBaseEnum> implements Converter<String, T> { 
        private final Map<String, T> idEnumMap = Maps.newHashMap();
        private final Map<String, T> codeEnumMap = Maps.newHashMap();
    
        public IdCodeToEnumConverter(Class<T> enumType) { 
            Arrays.stream(enumType.getEnumConstants())
                    .forEach(x -> { 
                        idEnumMap.put(x.getId().toString(), x);
                        codeEnumMap.put(x.getCode(), x);
                    });
        }
    
        @Override
        public T convert(String source) { 
            return Optional.of(source)
                    .map(codeEnumMap::get)
                    .orElseGet(() -> Optional.of(source)
                            .map(idEnumMap::get)
                            .orElseThrow(() -> new CodeBaseException(ErrorResponseEnum.PARAMS_ENUM_NOT_MATCH)));
        }
    }

ConverterFactory 类：

public class IdCodeToEnumConverterFactory implements ConverterFactory<String, IdCodeBaseEnum> { 
        @SuppressWarnings("rawtypes")
        private static final Map<Class, Converter> CONVERTERS = Maps.newHashMap();
    
        @Override
        public <T extends IdCodeBaseEnum> Converter<String, T> getConverter(Class<T> targetType) { 
            //noinspection unchecked
            Converter<String, T> converter = CONVERTERS.get(targetType);
            if (converter == null) { 
                converter = new IdCodeToEnumConverter<>(targetType);
                CONVERTERS.put(targetType, converter);
            }
            return converter;
        }
    }

这两个就是转换的核心了，我们只要将他们装配到 Spring 的类型转换器中，就能够实现枚举类型的自动转化了。

## 加载配置 ##

将我们定义的 Converter 和 ConverterFactory 注册到 Spring 的类型转换器中。

@Configuration
    public class WebConfig implements WebMvcConfigurer { 
        @Override
        public void addFormatters(FormatterRegistry registry) { 
            registry.addConverterFactory(new IdCodeToEnumConverterFactory());
            registry.addConverterFactory(new CodeToEnumConverterFactory());
            registry.addConverterFactory(new IdToEnumConverterFactory());
        }
    }

至此，核心定义全部结束。

## 测试 ##

写一个 Controller 作为测试入口：

@RestController
    @RequestMapping("echo")
    public class EchoController { 
        @GetMapping("gender-id-code")
        public String genderIdCode(@RequestParam("gender") GenderIdCodeEnum gender) { 
            return gender.name();
        }
    }

准备测试用例测试：

@SpringBootTest(classes = SpringEnumParamApplication.class)
    @AutoConfigureMockMvc
    class EchoControllerTest { 
        @Autowired
        private MockMvc mockMvc;
    
        @ParameterizedTest
        @ValueSource(strings = { "MALE", "male", "1"})
        void genderIdCode(String gender) throws Exception { 
            final String result = mockMvc.perform(
                    MockMvcRequestBuilders.get("/echo/gender-id-code")
                            .param("gender", gender)
            )
                    .andExpect(MockMvcResultMatchers.status().isOk())
                    .andDo(MockMvcResultHandlers.print())
                    .andReturn()
                    .getResponse()
                    .getContentAsString();
    
            Assertions.assertEquals("MALE", result);
        }
    }

## 文末总结 ##

实现枚举参数并不难，只要按照 Spring 的扩展规范实现即可。需要注意的是，注意枚举类中唯一的 id 和 code。

本文是应用，下篇说一下原理。以及 http body 形式请求的枚举转换逻辑。

关注公众号「看山的小屋」回复 spring 获取源码。源码中完整定义了三种枚举形式。

--------------------

你好，我是看山，公众号：看山的小屋，10 年老猿，开源贡献者。游于码界，戏享人生。

个人主页：[https://www.howardliu.cn][https_www.howardliu.cn]  
个人博文：[SpringBoot 实战：优雅的使用枚举参数][SpringBoot]  
CSDN 主页：[https://kanshan.blog.csdn.net/][https_kanshan.blog.csdn.net]  
CSDN 博文：[SpringBoot 实战：优雅的使用枚举参数][SpringBoot 1]

![公众号：看山的小屋][21785bb43b333b0ff8efda479e715378.png]

[Spring]: /images/20210923/7bd3d188da8c4ea38d29ac5b58465fc1.png
[Sinousxl]: https://pixabay.com/zh/users/sinousxl-7554155/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=6389888
[Pixabay]: https://pixabay.com/zh/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=6389888
[https_www.howardliu.cn]: https://www.howardliu.cn
[SpringBoot]: https://www.howardliu.cn/spring-enum-params/
[https_kanshan.blog.csdn.net]: https://kanshan.blog.csdn.net/
[SpringBoot 1]: https://kanshan.blog.csdn.net/article/details/119581202
[21785bb43b333b0ff8efda479e715378.png]: /images/20210923/362b62007ed24d6db4834c878c6b65ee.png