编译期拦截枚举重复定义：推荐一个实用的Maven插件

三产

826人浏览 · 2026-03-20 09:39:53

三产 · 2026-03-20 09:39:53 发布

欢迎关注公众号【拿客】，这里聚焦低延迟架构、AI智能体、高并发系统设计领域。点击上方「蓝色字体」关注，星标获取最新技术内容。

编译期拦截枚举重复定义：推荐一个实用的Maven插件

在Java开发中，枚举（Enum）是我们经常使用的一种数据类型，它用来定义一组固定的常量集合。但是你有没有遇到过这样的问题：在枚举中定义了重复的code值，直到线上运行才发现问题？

今天给大家推荐一款我自己开发的Maven插件 —— enum-check-maven-plugin，它能在编译阶段自动帮你检查枚举中的重复字段值，让问题提前暴露，避免线上故障。

问题场景

让我们先来看一个常见的错误场景：

public enum StatusEnum {

    SUCCESS(200, "成功"),
    ERROR(500, "失败"),
    // 不小心复制粘贴，code重复了！
    BAD_REQUEST(400, "错误请求"),
    NOT_FOUND(400, "未找到");  // 400 重复了！

    private final int code;
    private final String desc;

    StatusEnum(int code, String desc) {
        this.code = code;
        this.desc = desc;
    }
}

这种错误在日常开发中很常见：

复制粘贴代码时忘记改code
多人协作开发时重复定义
新增枚举项时没注意已有值

而问题在于：这种错误在编译期不会被发现，只有运行到对应逻辑才会报错。如果你正好没有覆盖到这个测试用例，那就等着线上出问题吧。

解决方案：enum-check-maven-plugin

enum-check-maven-plugin 就是为了解决这个问题而生的Maven插件。它能够：

✅ 在编译阶段自动检查枚举字段是否重复
✅ 支持单字段检查（比如code唯一）
✅ 支持组合字段检查（多个字段组合唯一）
✅ 注解驱动，只检查你标记的枚举，不侵入其他代码
✅ 支持多模块项目，自动扫描所有模块
✅ 源码级别解析，不需要等待编译完成

核心特性

1. 注解驱动，按需检查

插件采用注解驱动，你只需要在需要检查的枚举上添加 @EnumCheck 注解即可：

import io.github.coderknock.enumcheck.annotation.EnumCheck;

@EnumCheck // 开启检查
public enum StatusEnum {
    // ...
}

不想检查的枚举不加注解就行，完全灵活。

2. 支持单字段和组合字段检查

单字段检查（最常用场景）：

@EnumCheck(fields = "code")  // 检查code唯一
public enum ErrorCodeEnum {
    SUCCESS(200, "成功"),
    BAD_REQUEST(400, "错误请求"),
    NOT_FOUND(404, "未找到");
    // ...
}

组合字段检查（多个字段联合唯一）：

@EnumCheck(fields = {"type", "code"})  // type + code 组合唯一
public enum BizErrorCodeEnum {
    // ...
}

3. 灵活配置

插件提供了灵活的配置项：

<plugin>
    <groupId>io.github.coderknock</groupId>
    <artifactId>enum-check-maven-plugin</artifactId>
    <version>2.0.0</version>
    <executions>
        <execution>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <!-- 发现重复是否中断构建 -->
        <failOnError>true</failOnError>
        <!-- 指定要扫描的包，不指定则扫描整个项目 -->
        <includes>
            <include>com.example.*</include>
        </includes>
    </configuration>
</plugin>

4. 扫描效果展示

当插件发现重复值时，会在构建阶段立即报错，阻止你把有问题的代码打包：

[ERROR] Found duplicate enum values:
[ERROR]   Enum: com.example.StatusEnum, field: code, value: 400
[ERROR]       BAD_REQUEST
[ERROR]       NOT_FOUND
[ERROR] Enumeration error check failed!

这样就能在编译阶段就发现问题，而不是等到线上运行出错。

工作原理

插件使用 JBoss Forge Roaster 进行源码级别解析，不需要等待编译完成，就能直接分析源码中的枚举定义。整体工作流程：

使用方式

只需要两步就能集成到你的项目中：

第一步：添加插件依赖

在你的 pom.xml 中添加插件配置：

<build>
    <plugins>
        <plugin>
            <groupId>io.github.coderknock</groupId>
            <artifactId>enum-check-maven-plugin</artifactId>
            <version>2.0.0</version>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>check</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

第二步：添加依赖注解

项目中需要使用 @EnumCheck 注解，因此需要添加依赖：

<dependency>
    <groupId>io.github.coderknock</groupId>
    <artifactId>enum-check-annotation</artifactId>
    <version>2.0.0</version>
</dependency>

第三步：在枚举上添加注解

import io.github.coderknock.enumcheck.annotation.EnumCheck;

@EnumCheck(fields = "code")
public enum YourEnum {
    // ...
}

完成！之后每次编译，插件都会自动帮你检查。

为什么选择这个插件？

对比其他方案

方案	优点	缺点
单元测试	灵活	需要手写测试用例，容易遗漏
运行时检查	简单	发现问题太晚，已经到线上
IDE检查	开发阶段发现	需要安装插件，团队协作难以统一
enum-check-maven-plugin	编译阶段自动检查，无需手写用例，全团队统一	需要集成到Maven构建

核心优势

提前发现问题：在CI/CD流程就能发现错误，不把问题带到线上
零侵入：只在需要检查的枚举上加注解，不影响现有代码
集成简单：几分钟就能完成集成，之后自动运行
开源免费：MIT许可证，可自由使用和修改

适用场景

这个插件特别适合：

📌 基础框架开发：统一错误码定义需要保证code唯一
🏢 企业级应用：多种状态枚举、业务错误码管理
👥 多人协作项目：避免多人开发导致的重复定义
🚀 对质量要求高的项目：尽可能在早期发现问题

项目地址

GitHub：https://github.com/coder-knock/enum-check-maven-plugin
Maven Central：https://search.maven.org/artifact/io.github.coder-knock/enum-check-maven-plugin

欢迎Star、Fork，也欢迎提交Issue和PR！