看看人家在接口中使用枚舉類(lèi)型的方式

1. 概覽

枚舉作為 Java 5 的重要特征，相信大家并不陌生，但在實(shí)際開(kāi)發(fā)過(guò)程中，當(dāng) name 和 ordrial 發(fā)生變化時(shí)，如果處理不當(dāng)非常容易引起系統(tǒng)bug。這種兼容性bug非常難以定位，需要從框架層次進(jìn)行避免，而非僅靠開(kāi)發(fā)人員的主觀意識(shí)。

1.1. 背景

枚舉很好用，特別是提供的 name 和 ordrial 特性，但這點(diǎn)對(duì)重構(gòu)造成了一定影響，比如：

某個(gè)枚舉值業(yè)務(wù)語(yǔ)義發(fā)生變化，需要將其進(jìn)行 rename 操作，以更好的表達(dá)新業(yè)務(wù)語(yǔ)義

新增、刪除或者為了展示調(diào)整了枚舉定義順序

這些在業(yè)務(wù)開(kāi)發(fā)中非常常見(jiàn)，使用 IDE 的 refactor 功能可以快速且準(zhǔn)確的完成重構(gòu)工作。但，如果系統(tǒng)將這些暴露出去或者存儲(chǔ)到數(shù)據(jù)庫(kù)等存儲(chǔ)引擎就變得非常麻煩，不管是 name 還是 ordrial 的變更都會(huì)產(chǎn)生兼容性問(wèn)題。

對(duì)此，最常見(jiàn)的解決方案便是放棄使用 name 和 ordrial，轉(zhuǎn)而使用控制能力更強(qiáng)的 code。

1.2. 目標(biāo)

提供一組工具，以方便的基于 code 使用枚舉，快速完成對(duì)現(xiàn)有框架的集成：

完成與 Spring MVC 的集成，基于 code 使用枚舉；加強(qiáng)返回值，以對(duì)象的方式進(jìn)行返回，信息包括 code、name、description

提供統(tǒng)一的枚舉字典，自動(dòng)掃描系統(tǒng)中的枚舉并將其以 restful 的方式暴露給前端

使用 code 進(jìn)行數(shù)據(jù)存儲(chǔ)操作，避免重構(gòu)的影響

2. 快速入門(mén)

2.1. 添加 starter

在 Spring boot 項(xiàng)目的 pom 中增加如下依賴：

com.geekhalo.lego
lego-starter
0.1.19-enum-SNAPSHOT

2.2. 統(tǒng)一枚舉結(jié)構(gòu)

如何統(tǒng)一枚舉行為呢？公共父類(lèi)肯定是不行的，但可以為其提供一個(gè)接口，在接口中完成行為的定義。

2.2.1. 定義枚舉接口

除了在枚舉中自定義 code 外，通常還會(huì)為其提供描述信息，構(gòu)建接口如下：

publicinterfaceCodeBasedEnum{
intgetCode();
}
publicinterfaceSelfDescribedEnum{
defaultStringgetName(){
returnname();
}

Stringname();

StringgetDescription();
}
publicinterfaceCommonEnumextendsCodeBasedEnum,SelfDescribedEnum{

}

整體結(jié)構(gòu)如下：

在定義枚舉時(shí)便可以直接使用CommonEnum這個(gè)接口。

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

有了統(tǒng)一的枚舉接口，在定義枚舉時(shí)便可以直接實(shí)現(xiàn)接口，從而完成對(duì)枚舉的約束。

publicenumNewsStatusimplementsCommonEnum{
DELETE(1,"刪除"),
ONLINE(10,"上線"),
OFFLINE(20,"下線");
privatefinalintcode;
privatefinalStringdesc;

NewsStatus(intcode,Stringdesc){
this.code=code;
this.desc=desc;
}

@Override
publicintgetCode(){
returnthis.code;
}

@Override
publicStringgetDescription(){
returnthis.desc;
}
}

2.3. 自動(dòng)注冊(cè) CommonEnum

有了統(tǒng)一的 CommonEnum 最大的好處便是可以進(jìn)行統(tǒng)一管理，對(duì)于統(tǒng)一管理，第一件事便是找到并注冊(cè)所有的 CommonEnum。

以上是核心處理流程：

首先通過(guò) Spring 的 ResourcePatternResolver 根據(jù)配置的 basePackage 對(duì)classpath進(jìn)行掃描

掃描結(jié)果以Resource來(lái)表示，通過(guò) MetadataReader 讀取 Resource 信息，并將其解析為 ClassMetadata

獲得 ClassMetadata 之后，找出實(shí)現(xiàn) CommonEnum 的類(lèi)

將 CommonEnum 實(shí)現(xiàn)類(lèi)注冊(cè)到兩個(gè) Map 中進(jìn)行緩存

備注：此處萬(wàn)萬(wàn)不可直接使用反射技術(shù)，反射會(huì)觸發(fā)類(lèi)的自動(dòng)加載，將對(duì)眾多不需要的類(lèi)進(jìn)行加載，從而增加 metaspace 的壓力。

在需要 CommonEnum 時(shí)，只需注入 CommonEnumRegistry Bean 便可以方便的獲得 CommonEnum 的具體實(shí)現(xiàn)。

2.4. Spring MVC 接入層

Web 層是最常見(jiàn)的接入點(diǎn)，對(duì)于 CommonEnum 我們傾向于：

參數(shù)使用 code 來(lái)表示，避免 name、ordrial 變化導(dǎo)致業(yè)務(wù)異常

豐富返回值，包括枚舉的 code、name、description 等

2.4.1. 入?yún)⑥D(zhuǎn)化

Spring MVC 存在兩種參數(shù)轉(zhuǎn)化擴(kuò)展：

對(duì)于普通參數(shù)，比如 RequestParam 或 PathVariable 直接從 ConditionalGenericConverter 進(jìn)行擴(kuò)展

基于 CommonEnumRegistry 提供的 CommonEnum 信息，對(duì) matches 和 getConvertibleTypes方法進(jìn)行重寫(xiě)

根據(jù)目標(biāo)類(lèi)型獲取所有的 枚舉值，并根據(jù) code 和 name 進(jìn)行轉(zhuǎn)化

對(duì)于 Json 參數(shù)，需要對(duì) Json 框架進(jìn)行擴(kuò)展（以 Jackson 為例）

遍歷 CommonEnumRegistry 提供的所有 CommonEnum，依次進(jìn)行注冊(cè)

從 Json 中讀取信息，根據(jù) code 和 name 轉(zhuǎn)化為確定的枚舉值

兩種擴(kuò)展核心實(shí)現(xiàn)見(jiàn)：

@Order(1)
@Component
publicclassCommonEnumConverterimplementsConditionalGenericConverter{
@Autowired
privateCommonEnumRegistryenumRegistry;

@Override
publicbooleanmatches(TypeDescriptorsourceType,TypeDescriptortargetType){
Classtype=targetType.getType();
returnenumRegistry.getClassDict().containsKey(type);
}

@Override
publicSetgetConvertibleTypes(){
returnenumRegistry.getClassDict().keySet().stream()
.map(cls->newConvertiblePair(String.class,cls))
.collect(Collectors.toSet());
}

@Override
publicObjectconvert(Objectsource,TypeDescriptorsourceType,TypeDescriptortargetType){
Stringvalue=(String)source;
ListcommonEnums=this.enumRegistry.getClassDict().get(targetType.getType());
returncommonEnums.stream()
.filter(commonEnum->commonEnum.match(value))
.findFirst()
.orElse(null);
}
}

staticclassCommonEnumJsonDeserializerextendsJsonDeserializer{
privatefinalListcommonEnums;

CommonEnumJsonDeserializer(ListcommonEnums){
this.commonEnums=commonEnums;
}

@Override
publicObjectdeserialize(JsonParserjsonParser,DeserializationContextdeserializationContext)throwsIOException,JacksonException{
Stringvalue=jsonParser.readValueAs(String.class);
returncommonEnums.stream()
.filter(commonEnum->commonEnum.match(value))
.findFirst()
.orElse(null);
}
}

2.4.2. 增強(qiáng)返回值

默認(rèn)情況下，對(duì)于枚舉類(lèi)型在轉(zhuǎn)換為 Json 時(shí)，只會(huì)輸出 name，其他信息會(huì)出現(xiàn)丟失，對(duì)于展示非常不友好，對(duì)此，需要對(duì) Json 序列化進(jìn)行能力增強(qiáng)。

首先，需要定義 CommonEnum 對(duì)應(yīng)的返回對(duì)象，具體如下：

@Value
@AllArgsConstructor(access=AccessLevel.PRIVATE)
@ApiModel(description="通用枚舉")
publicclassCommonEnumVO{
@ApiModelProperty(notes="Code")
privatefinalintcode;

@ApiModelProperty(notes="Name")
privatefinalStringname;

@ApiModelProperty(notes="描述")
privatefinalStringdesc;

publicstaticCommonEnumVOfrom(CommonEnumcommonEnum){
if(commonEnum==null){
returnnull;
}
returnnewCommonEnumVO(commonEnum.getCode(),commonEnum.getName(),commonEnum.getDescription());
}

publicstaticListfrom(ListcommonEnums){
if(CollectionUtils.isEmpty(commonEnums)){
returnCollections.emptyList();
}
returncommonEnums.stream()
.filter(Objects::nonNull)
.map(CommonEnumVO::from)
.filter(Objects::nonNull)
.collect(Collectors.toList());
}
}

CommonEnumVO 是一個(gè)標(biāo)準(zhǔn)的 POJO，只是增加了 Swagger 相關(guān)注解。

CommonEnumJsonSerializer 是自定義序列化的核心，會(huì)將 CommonEnum 封裝為 CommonEnumVO 并進(jìn)行寫(xiě)回，具體如下：

staticclassCommonEnumJsonSerializerextendsJsonSerializer{

@Override
publicvoidserialize(Objecto,JsonGeneratorjsonGenerator,SerializerProviderserializerProvider)throwsIOException{
CommonEnumcommonEnum=(CommonEnum)o;
CommonEnumVOcommonEnumVO=CommonEnumVO.from(commonEnum);
jsonGenerator.writeObject(commonEnumVO);
}
}

2.4.3. 效果展示

首先，新建一個(gè)測(cè)試枚舉 NewsStatus，具體如下：

publicenumNewsStatusimplementsCommonEnum{
DELETE(1,"刪除"),
ONLINE(10,"上線"),
OFFLINE(20,"下線");
privatefinalintcode;
privatefinalStringdesc;

NewsStatus(intcode,Stringdesc){
this.code=code;
this.desc=desc;
}

@Override
publicintgetCode(){
returnthis.code;
}

@Override
publicStringgetDescription(){
returnthis.desc;
}
}

然后新建 EnumController，具體如下：

@RestController
@RequestMapping("enum")
publicclassEnumController{
@GetMapping("paramToEnum")
publicRestResultparamToEnum(@RequestParam("newsStatus")NewsStatusnewsStatus){
returnRestResult.success(CommonEnumVO.from(newsStatus));
}

@GetMapping("pathToEnum/{newsStatus}")
publicRestResultpathToEnum(@PathVariable("newsStatus")NewsStatusnewsStatus){
returnRestResult.success(CommonEnumVO.from(newsStatus));
}

@PostMapping("jsonToEnum")
publicRestResultjsonToEnum(@RequestBodyNewsStatusRequestBodynewsStatusRequestBody){
returnRestResult.success(CommonEnumVO.from(newsStatusRequestBody.getNewsStatus()));
}

@GetMapping("bodyToJson")
publicRestResultbodyToJson(){
NewsStatusResponseBodynewsStatusResponseBody=newNewsStatusResponseBody();
newsStatusResponseBody.setNewsStatus(Arrays.asList(NewsStatus.values()));
returnRestResult.success(newsStatusResponseBody);
}

@Data
publicstaticclassNewsStatusRequestBody{
privateNewsStatusnewsStatus;
}

@Data
publicstaticclassNewsStatusResponseBody{
privateListnewsStatus;
}
}

執(zhí)行結(jié)果如下：

整體符合預(yù)期：

使用 code 作為請(qǐng)求參數(shù)可以自動(dòng)轉(zhuǎn)化為對(duì)應(yīng)的 CommonEnum

使用 CommonEnum 作為返回值，返回標(biāo)準(zhǔn)的 CommonEnumVO 對(duì)象結(jié)構(gòu)

2.5. 通用枚舉字典接口

有時(shí)可以將 枚舉 理解為系統(tǒng)的一類(lèi)字段，比較典型的就是管理頁(yè)面的各種下拉框，下拉框中的數(shù)據(jù)來(lái)自于后臺(tái)服務(wù)。

有了 CommonEnum 之后，可以提供統(tǒng)一的一組枚舉字典，避免重復(fù)開(kāi)發(fā)，同時(shí)在新增枚舉時(shí)也無(wú)需進(jìn)行擴(kuò)展，系統(tǒng)自動(dòng)識(shí)別并添加到字典中。

2.5.1. 構(gòu)建字典Controller

在 CommonEnumRegistry 基礎(chǔ)之上實(shí)現(xiàn)通用字典接口非常簡(jiǎn)單，只需按規(guī)范構(gòu)建 Controller 即可，具體如下：

@Api(tags="通用字典接口")
@RestController
@RequestMapping("/enumDict")
@Slf4j
publicclassEnumDictController{
@Autowired
privateCommonEnumRegistrycommonEnumRegistry;

@GetMapping("all")
publicRestResult>>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()));
}
returnRestResult.success(dictVo);
}

@GetMapping("types")
publicRestResult>enumTypes(){
Map>dict=this.commonEnumRegistry.getNameDict();
returnRestResult.success(Lists.newArrayList(dict.keySet()));
}

@GetMapping("/{type}")
publicRestResult>dictByType(@PathVariable("type")Stringtype){
Map>dict=this.commonEnumRegistry.getNameDict();
ListcommonEnums=dict.get(type);

returnRestResult.success(CommonEnumVO.from(commonEnums));
}
}

該 Controller 提供如下能力：

獲取全部字典，一次性獲取系統(tǒng)中所有的 CommonEnum

獲取所有字典類(lèi)型，僅獲取字典類(lèi)型，通常用于測(cè)試

獲取指定字典類(lèi)型的全部信息，比如上述所說(shuō)的填充下拉框

2.5.2. 效果展示

獲取全部字典：

獲取所有字典類(lèi)型：

獲取指定字段類(lèi)型的全部信息：

2.6. 輸出適配器

輸出適配器主要以 ORM 框架為主，同時(shí)各類(lèi) ORM 框架均提供了類(lèi)型映射的擴(kuò)展點(diǎn)，通過(guò)該擴(kuò)展點(diǎn)可以對(duì) CommonEnum 使用 code 進(jìn)行存儲(chǔ)。

2.6.1. MyBatis 支持

MyBatis 作為最流行的 ORM 框架，提供了 TypeHandler 用于處理自定義的類(lèi)型擴(kuò)展。

@MappedTypes(NewsStatus.class)
publicclassMyBatisNewsStatusHandlerextendsCommonEnumTypeHandler{
publicMyBatisNewsStatusHandler(){
super(NewsStatus.values());
}
}

MyBatisNewsStatusHandler 通過(guò) @MappedTypes(NewsStatus.class) 對(duì)其進(jìn)行標(biāo)記，以告知框架該 Handler 是用于 NewsStatus 類(lèi)型的轉(zhuǎn)換。

CommonEnumTypeHandler 是為 CommonEnum 提供的通用轉(zhuǎn)化能力，具體如下：

publicabstractclassCommonEnumTypeHandler&CommonEnum>
extendsBaseTypeHandler{
privatefinalListcommonEnums;

protectedCommonEnumTypeHandler(T[]commonEnums){
this(Arrays.asList(commonEnums));
}

protectedCommonEnumTypeHandler(ListcommonEnums){
this.commonEnums=commonEnums;
}

@Override
publicvoidsetNonNullParameter(PreparedStatementpreparedStatement,inti,Tt,JdbcTypejdbcType)throwsSQLException{
preparedStatement.setInt(i,t.getCode());
}

@Override
publicTgetNullableResult(ResultSetresultSet,StringcolumnName)throwsSQLException{

intcode=resultSet.getInt(columnName);
returncommonEnums.stream()
.filter(commonEnum->commonEnum.match(String.valueOf(code)))
.findFirst()
.orElse(null);
}

@Override
publicTgetNullableResult(ResultSetresultSet,inti)throwsSQLException{
intcode=resultSet.getInt(i);
returncommonEnums.stream()
.filter(commonEnum->commonEnum.match(String.valueOf(code)))
.findFirst()
.orElse(null);
}

@Override
publicTgetNullableResult(CallableStatementcallableStatement,inti)throwsSQLException{
intcode=callableStatement.getInt(i);
returncommonEnums.stream()
.filter(commonEnum->commonEnum.match(String.valueOf(code)))
.findFirst()
.orElse(null);
}
}

由于邏輯比較簡(jiǎn)單，在此不做過(guò)多解釋。

有了類(lèi)型之后，需要在 spring boot 的配置文件中指定 type-handler 的加載邏輯，具體如下：

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

完成配置后，使用 Mapper 對(duì)數(shù)據(jù)進(jìn)行持久化，數(shù)據(jù)表中存儲(chǔ)的便是 code 信息，具體如下：

2.6.2. JPA 支持

隨著 Spring data 越來(lái)越流行，JPA 又煥發(fā)出新的活力，JPA 提供 AttributeConverter 以對(duì)屬性轉(zhuǎn)換進(jìn)行自定義。

首先，構(gòu)建 JpaNewsStatusConverter，具體如下：

publicclassJpaNewsStatusConverterextendsCommonEnumAttributeConverter{
publicJpaNewsStatusConverter(){
super(NewsStatus.values());
}
}

CommonEnumAttributeConverter 為 CommonEnum 提供的通用轉(zhuǎn)化能力，具體如下：

publicabstractclassCommonEnumAttributeConverter&CommonEnum>
implementsAttributeConverter{
privatefinalListcommonEnums;

publicCommonEnumAttributeConverter(E[]commonEnums){
this(Arrays.asList(commonEnums));
}

publicCommonEnumAttributeConverter(ListcommonEnums){
this.commonEnums=commonEnums;
}

@Override
publicIntegerconvertToDatabaseColumn(Ee){
returne.getCode();
}

@Override
publicEconvertToEntityAttribute(Integercode){
return(E)commonEnums.stream()
.filter(commonEnum->commonEnum.match(String.valueOf(code)))
.findFirst()
.orElse(null);
}
}

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

@Entity
@Data
@Table(name="t_jpa_news")
publicclassJpaNewsEntity{
@Id
@GeneratedValue(strategy=GenerationType.IDENTITY)
privateLongid;

@Convert(converter=JpaNewsStatusConverter.class)
privateNewsStatusstatus;
}

@Convert(converter = JpaNewsStatusConverter.class) 是對(duì) status 的配置，使用 JpaNewsStatusConverter 進(jìn)行屬性的轉(zhuǎn)換。

運(yùn)行持久化指令后，數(shù)據(jù)庫(kù)如下：

審核編輯：劉清