开源推荐 | 轻量级枚举字典Spring Boot Starter：让枚举管理变得如此简单！

原创已于 2025-09-29 17:09:04 修改 · 599 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#开源 #spring boot #后端 #java

于 2025-09-29 17:06:41 首次发布

前言

在Java企业级开发中，枚举（Enum）是我们经常使用的数据类型，特别是在处理状态码、类型标识等场景。但是，如何优雅地管理和暴露这些枚举数据给前端使用，一直是一个让人头疼的问题。

今天给大家推荐一个我最近开源的枚举字典Spring Boot Starter项目，它能够自动扫描项目中的枚举类，并提供统一的REST API接口，让枚举管理变得前所未有的简单！

项目亮点

核心特性

自动扫描：基于注解自动扫描指定包路径下的枚举类
多包支持：支持扫描多个包路径，灵活配置
注解驱动：使用@EnableDictionary和@EnumDictionary注解，配置简单
REST API：提供统一的枚举字典查询接口
高性能：内置缓存机制，避免重复扫描
灵活配置：支持注解参数和配置文件两种配置方式

技术栈

Java 21+：使用最新的Java特性
Spring Boot 3.2.4+：基于最新的Spring Boot版本
Maven：标准的Maven项目结构

快速开始

添加依赖

<dependency>
    <groupId>com.github</groupId>
    <artifactId>enums-springboot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

启用字典功能

在启动类上添加@EnableDictionary注解：

@SpringBootApplication
@EnableDictionary
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

创建枚举字典

创建枚举类并添加@EnumDictionary注解：

package com.example.enums;

import com.github.enums.annotation.EnumDictionary;
import com.github.enums.scan.Valuable;

@EnumDictionary("用户状态")
public enum UserStatus implements Valuable {
    ACTIVE(1, "激活"),
    INACTIVE(0, "未激活"),
    LOCKED(-1, "锁定");

    private final int code;
    private final String description;

    UserStatus(int code, String description) {
        this.code = code;
        this.description = description;
    }

    @Override
    public Object getCode() {
        return code;
    }

    @Override
    public Object getValue() {
        return description;
    }
}

访问API

启动应用后，可以通过以下接口访问枚举字典：

# 获取所有枚举类型名称
GET /v1/enums/names

# 获取指定枚举的字典项
GET /v1/enums/UserStatus

API接口详解

获取所有枚举类型

请求：

GET /v1/enums/names

响应：

{
  "code": 0,
  "message": "Success",
  "types": [
    {
      "name": "UserStatus",
      "description": "用户状态"
    },
    {
      "name": "OrderStatus", 
      "description": "订单状态"
    }
  ]
}

获取指定枚举字典

请求：

GET /v1/enums/UserStatus

响应：

{
  "code": 0,
  "message": "Success",
  "items": [
    {
      "name": "ACTIVE",
      "code": 1,
      "value": "激活"
    },
    {
      "name": "INACTIVE",
      "code": 0,
      "value": "未激活"
    },
    {
      "name": "LOCKED",
      "code": -1,
      "value": "锁定"
    }
  ]
}

高级配置

多包路径扫描

@SpringBootApplication
@EnableDictionary(basePackages = {
    "com.example.enums",
    "com.example.common.dict",
    "com.example.business.enums"
})
public class Application {
    // 会扫描所有指定的包路径
}

配置文件配置

spring:
  dictionary:
    enabled: true
    basePackages:
      - com.example.enums
      - com.example.common.dict

自定义枚举值

支持字符串类型的code：

@EnumDictionary("订单状态")
public enum OrderStatus implements Valuable {
    PENDING("P", "待处理"),
    PROCESSING("PR", "处理中"),
    COMPLETED("C", "已完成"),
    CANCELLED("CA", "已取消");

    private final String code;
    private final String description;

    OrderStatus(String code, String description) {
        this.code = code;
        this.description = description;
    }

    @Override
    public Object getCode() {
        return code;
    }

    @Override
    public Object getValue() {
        return description;
    }
}

架构设计

核心组件

DictionaryImportSelector: 处理@EnableDictionary注解，决定是否启用字典功能
EnumsScanner: 负责扫描枚举类并构建字典缓存
EnumsController: 提供枚举字典的REST API接口
DictionaryProperties: 字典配置属性类

扫描流程

@EnableDictionary注解触发DictionaryImportSelector
根据注解参数确定要扫描的包路径
EnumsStarterAutoConfiguration调用EnumsScanner.scan()进行扫描
EnumsScanner扫描指定包下的枚举类，构建缓存
EnumsController提供API接口访问缓存数据

使用场景

1. 前端下拉框数据源

// 前端获取用户状态选项
fetch('/v1/enums/UserStatus')
  .then(response => response.json())
  .then(data => {
    // 渲染下拉框选项
    data.items.forEach(item => {
      console.log(`${item.name}: ${item.value}`);
    });
  });