# enums-spring-boot-starter **Repository Path**: zc_oss/enums-spring-boot-starter ## Basic Information - **Project Name**: enums-spring-boot-starter - **Description**: 适用于Spring项目中的枚举全局转换框架, 包括前后端的枚举传参与序列化, ORM框架中的枚举与数据库类型映射, 以及全项目枚举码表扫描 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 19 - **Forks**: 4 - **Created**: 2020-07-09 - **Last Updated**: 2025-08-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🚀 Enums Spring Boot Starter [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) [![Maven Central](https://img.shields.io/maven-central/v/io.gitee.zhucan123/enum-spring-boot-starter.svg)](https://search.maven.org/artifact/io.gitee.zhucan123/enum-spring-boot-starter) [![Java](https://img.shields.io/badge/Java-8%2B-orange.svg)](https://www.oracle.com/java/) [![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.3%2B-brightgreen.svg)](https://spring.io/projects/spring-boot) [![Gitee Stars](https://gitee.com/zc_oss/enums-spring-boot-starter/badge/star.svg?theme=dark)](https://gitee.com/zc_oss/enums-spring-boot-starter) [![GitHub Stars](https://img.shields.io/github/stars/your-repo/enums-spring-boot-starter.svg)](https://github.com/your-repo/enums-spring-boot-starter) [English](README_en.MD) | **简体中文** **Enums Spring Boot Starter** 是一个功能强大的Java枚举处理框架，专为Spring Boot应用设计。它提供了枚举与数据库、JSON、前后端参数之间的自动转换能力，让您能够更优雅、更高效地使用Java枚举类型。 --- ## 📋 目录 - [✨ 核心特性](#-核心特性) - [🏗️ 架构设计](#️-架构设计) - [📦 快速开始](#-快速开始) - [🛠️ 模块介绍](#️-模块介绍) - [📚 使用示例](#-使用示例) - [⚙️ 配置选项](#️-配置选项) - [🔧 高级功能](#-高级功能) - [📖 文档链接](#-文档链接) - [🤝 贡献指南](#-贡献指南) - [📄 开源协议](#-开源协议) ## ✨ 核心特性 ### 🎯 **三层架构，分层解耦** - **🔧 enums-core**: 枚举核心定义和基础转换 - **🔄 enum-conversion**: 数据库自动转换和持久化 - **🔍 enums-scanner**: 全局枚举扫描和码表管理 ### 🚀 **开箱即用** - ⚡ **零配置启动**: 基于Spring Boot自动配置 - 🎨 **注解驱动**: 简单注解即可启用所有功能 - 🔗 **无缝集成**: 完美融入现有Spring Boot项目 ### 🎨 **强大的转换能力** - 🌐 **JSON序列化**: 枚举与JSON的双向自动转换 - 🗄️ **数据库映射**: 枚举与数据库数值类型的自动映射 - 📡 **MVC参数绑定**: 前后端参数传递的智能转换 - 📊 **码表查询**: 统一的枚举码表查询API ### ⚡ **高性能设计** - 🔧 **编译时处理**: 基于APT技术，运行时零性能损耗 - 💾 **智能缓存**: 多级缓存策略，支持Redis、内存等 - 🔄 **增量更新**: 支持枚举的动态刷新和增量同步 ## 安装使用攻略 ### 一、最小化引入使用(仅需前后端的传参枚举转换和Json序列化) 在我们的项目中, 如果仅仅是只需要使用到全局处理枚举的一些基础功能, 如前后端传参和获取数据时能自动实现枚举与数值的转换映射那么我们仅需要本框架包中的**enums-core**模块部分 #### 使用Maven 在你的 `pom.xml` 文件中添加以下依赖： ```xml io.gitee.zhucan123 enums-core 1.1.8-RELEASE ``` #### 使用Gradle 在你的 build.gradle 文件中添加以下依赖： ```groovy implementation 'io.gitee.zhucan123:enums-core:1.1.8-RELEASE' ``` ### 使用方法（在此部分提供关于如何在项目中使用该库的具体代码示例） #### 示例 ##### 1.定义我们的枚举 ```java @Getter @AllArgsConstructor public enum OrderBillStateEnum implements ExtensionEnum { PENDING_AUDIT(1, "待审核"), PART_AUDIT(2, "部分审核通过"), NOT_PASS(3, "审核不通过"), UNCONFIRMED(5, "未确认"), UNDER_COMPLAINT(7, "申诉中"), CONFIRMED(9, "已确认"); private final int code; private final String name; } ``` ##### 2.前端接受参数枚举(前端传递code值就行) 如 http://localhost:8080/orders?billState=1 ```java @Data public class PluginOrderBillQuery { @ApiModelProperty("账单审核状态") private OrderBillStateEnum billState; } ``` ##### 3.接口查询出来的数据DTO返回前端时, 定义的枚举会自动转换为code值 ```java @Data public class PluginOrderBillDTO { @ApiModelProperty("账单id") private Long id; @ApiModelProperty("账单审核状态") private OrderBillStateEnum billState; } ``` 响应体结构示例 ```json { "success": 1, "message": "", "data": { "id": 1244, "billState": 1 } } ``` ### 二、集成数据库的Enum映射和JSON映射转换如果我们在使用到全局处理枚举的一些基础功能, 如前后端传参和获取数据时能自动实现枚举与数值的转换映射, 同时也需要枚举能自动与数据的数字类型进行转换时我们则需要使用**enums-conversion**框架包 (包含了**enums-core**核心框架) #### 使用Maven 在你的 `pom.xml` 文件中添加以下依赖： ```xml io.gitee.zhucan123 spring-boot-starter-enums-conversion 1.1.8-RELEASE ``` #### 使用Gradle 在你的 build.gradle 文件中添加以下依赖： ```groovy implementation 'io.gitee.zhucan123:spring-boot-starter-enums-conversion:1.1.8-RELEASE' ``` ### 使用方法（在此部分提供关于如何在项目中使用该库的具体代码示例） #### 示例 ##### 1.定义我们的枚举需要注意其实我们只是需要额外的增加一个**@EnumAutoConverter**注解就行了 ```java @Getter @AllArgsConstructor @EnumAutoConverter public enum OrderBillStateEnum implements ExtensionEnum { PENDING_AUDIT(1, "待审核"), PART_AUDIT(2, "部分审核通过"), NOT_PASS(3, "审核不通过"), UNCONFIRMED(5, "未确认"), UNDER_COMPLAINT(7, "申诉中"), CONFIRMED(9, "已确认"); private final int code; private final String name; } ``` ### 三、全服务枚举码表扫描器在我们服务中存在N多枚举状态等情况下, 我们需要提供一个全局枚举数据扫描器来给我们前端做各种选项候选项值时, 这个就是 **enums-scanner**(同样包含了**enums-core**核心框架) #### 使用Maven 在你的 `pom.xml` 文件中添加以下依赖： ```xml io.gitee.zhucan123 spring-boot-starter-enums-scanner 1.1.8-RELEASE ``` #### 使用Gradle 在你的 build.gradle 文件中添加以下依赖： ```groovy implementation 'io.gitee.zhucan123:spring-boot-starter-enums-scanner:1.1.8-RELEASE' ``` ### 使用方法（在此部分提供关于如何在项目中使用该库的具体代码示例） #### 示例 ##### 1.定义我们的枚举需要注意其实我们只是需要额外的增加一个**@EnumScan**注解就行了, 这个注解标识了我们需要扫描的枚举. ```java @Getter @AllArgsConstructor @EnumScan public enum OrderBillStateEnum implements ExtensionEnum { PENDING_AUDIT(1, "待审核"), PART_AUDIT(2, "部分审核通过"), NOT_PASS(3, "审核不通过"), UNCONFIRMED(5, "未确认"), UNDER_COMPLAINT(7, "申诉中"), CONFIRMED(9, "已确认"); private final int code; private final String name; } ``` ##### 2. 提供一个Api用来获取全项目枚举数据(通过EnumScanHandler处理器可以得到全项目枚举数据) ```java @RestController @RequestMapping public class EnumsController { @Resource private EnumScanHandler enumScanHandler; @GetMapping("/enums") public List enums(){ return enumScanHandler.codeTables(); } } ``` 响应体结构示例 ```json [{ "enumName": "OrderBillStateEnum", "items": [{ "code": 1, "name": "待审核" }, { "code": 2, "name": "部分审核通过" }, { "code": 3, "name": "审核不通过" }, { "code": 5, "name": "未确认" }, { "code": 7, "name": "申诉中" }, { "code": 9, "name": "已确认" }], "defaultItem": 1, "classPath": "com.zhucan.management.infrastructure.constants.enums.OrderBillStateEnum" },{ "enumName": "AbnormalHandleRoleEnum", "items": [{ "code": 1, "name": "Scrum Master" }, { "code": 2, "name": "Product Owner" }, { "code": 3, "name": "Handler" }], "defaultItem": 1, "classPath": "com.zhucan.management.infrastructure.constants.enums.AbnormalHandleRoleEnum" }, { "enumName": "AbnormalCauseTypeEnum", "items": [{ "code": 1, "name": "需求分类错误" }, { "code": 2, "name": "租户名称未填写或格式不规范" }, { "code": 3, "name": "出库工时未填写" }, { "code": 4, "name": "出库工时为0，但未出库原因未填写" }, { "code": 5, "name": "需求评估工时不正确" }], "defaultItem": 1, "classPath": "com.zhucan.management.infrastructure.constants.enums.AbnormalCauseTypeEnum" }] ``` ## 贡献我们欢迎所有对该项目感兴趣的开发者参与其中。请阅读我们的贡献指南了解更多信息。 ## 许可证该项目根据 Apache License 2.0 许可进行授权。 > 希望这个README模板对你有所帮助。你可以根据实际情况进一步完善和优化这个README文件，确保它包含所有必要的信息，以便其他开发者更容易理解和使用你的项目。祝你好运！