ArchUnit实践：在Java Record中强制执行敏感字段命名规范-java教程-PHP中文网

ArchUnit实践：在Java Record中强制执行敏感字段命名规范

DDD

发布： 2025-10-04 11:19:01

原创

439人浏览过

ArchUnit实践：在Java Record中强制执行敏感字段命名规范

本教程探讨了如何利用ArchUnit在Java Record类型中强制执行敏感字段命名规范，特别针对特定类型（如UUID）的字段名进行黑名单限制。通过ArchUnit的noFields().should().haveName()规则，可以有效禁止不符合要求的字段命名，从而提升代码质量和遵循项目约定。

1. 引言与ArchUnit基础

在现代java项目中，维护一致的代码风格和命名规范是确保代码可读性、可维护性和团队协作效率的关键。archunit作为一个强大的java架构测试库，允许开发者通过编写单元测试来验证和强制执行各种架构规则。这些规则可以涵盖包依赖、类命名、方法调用等多个层面。

本教程将聚焦于一个具体的应用场景：如何利用ArchUnit在Java 17引入的record类型中，对特定类型的字段（即record组件）强制执行命名规范，例如禁止将UUID类型的字段命名为uuid。

环境配置示例： 为了使用ArchUnit进行架构测试，您需要在项目中添加相应的依赖。以下是一个典型的Maven配置示例：

<properties>
    <java.version>17</java.version>
    <spring-boot.version>2.7.0</spring-boot.version>
    <junit-jupiter-engine.version>5.8.2</junit-jupiter-engine.version>
    <archunit.version>1.0.0-rc1</archunit.version>
</properties>

<dependencies>
    <!-- 其他依赖 -->
    <dependency>
        <groupId>com.tngtech.archunit</groupId>
        <artifactId>archunit-junit5</artifactId>
        <version>${archunit.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-engine</artifactId>
        <version>${junit-jupiter-engine.version}</version>
        <scope>test</scope>
    </dependency>
    <!-- Mockito等其他测试依赖 -->
</dependencies>

登录后复制

2. 理解Java Record的特性

Java record是一种特殊类型的类，旨在作为不可变数据载体，简化数据传输对象（DTO）的创建。其核心特性之一是：record的组件（在声明时定义的参数）会自动成为record的私有final字段，并生成相应的访问器方法。

例如，对于以下record声明：

public record MyRecordClass(UUID id, String name) {}

登录后复制

id和name不仅是构造函数的参数，它们也是MyRecordClass实例的实际字段。正是由于这一特性，ArchUnit能够将record组件视为普通字段进行分析和规则检查。

立即学习“Java免费学习笔记（深入）”；

3. 核心规则：禁止特定字段命名

针对在record中黑名单特定字段命名，ArchUnit提供了一种直接且强大的方式：noFields().that().haveRawType(...).should().haveName(...)。

规则详解：

行者AI

行者AI绘图创作，唤醒新的灵感，创造更多可能

100

查看详情

noFields(): 这是一个ArchUnit规则定义的起点，表示我们正在定义一个关于字段的规则。
that().haveRawType(UUID.class): 这是一个过滤条件，用于选择所有原始类型为UUID.class的字段。您可以根据需要替换为任何其他类型。
should().haveName("uuid"): 这是规则的核心断言，它声明被选中的字段不应该（should()，此处为否定规则，即noFields()...should()...）拥有名称"uuid"。如果字段名称与此匹配，则测试失败。
because("..."): 这是一个可选但强烈推荐的说明，用于解释该规则的目的或违反规则的原因。当测试失败时，这条信息会显示在错误报告中，帮助开发者理解问题所在。

示例代码：强制禁止UUID字段命名为'uuid'

假设我们希望禁止所有UUID类型的字段被命名为uuid，而是鼓励使用id或更具描述性的名称，例如pupilId、teacherId。我们可以这样编写ArchUnit测试：

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import java.util.UUID;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noFields;

/**
 * ArchUnit测试类，用于强制执行Java Record中的字段命名规范。
 */
@AnalyzeClasses(packages = "com.example.project") // 指定需要扫描的包
public class NamingConventionArchTest {

    /**
     * 定义一个ArchUnit规则：禁止所有UUID类型的字段命名为"uuid"。
     * 鼓励开发者使用"id"或更具体的名称。
     */
    @ArchTest
    static final ArchRule NO_UUID_NAMED_UUID = noFields()
        .that().haveRawType(UUID.class)
        .should().haveName("uuid")
        .because("开发者必须为UUID字段使用'id'或更具体的名称，避免使用泛泛的'uuid'。");

    // 您可以在此处添加其他命名规范或架构规则
}

登录后复制

为了演示这个规则的效果，考虑以下两个record类：

import java.io.Serializable;
import java.util.UUID;

// 合规的Record类示例：
// 这里的UUID字段使用了合规的名称 (id, userId)
public record MyCompliantRecord(
    UUID id,
    UUID userId,
    String name
) implements Serializable {}

// 违规的Record类示例：
// 这里的UUID字段使用了被禁止的名称 (uuid)
public record MyNonCompliantRecord(
    UUID id,
    UUID uuid, // <-- 这个字段会触发ArchUnit测试失败
    String name
) implements Serializable {}

登录后复制

当运行NamingConventionArchTest时，如果com.example.project包下包含MyNonCompliantRecord类，并且其中存在名为uuid的UUID类型字段，则NO_UUID_NAMED_UUID测试将失败，并显示because子句中定义的提示信息。

4. 注意事项与局限性

Record类型特有性： 本文介绍的解决方案主要适用于record类型，因为record组件在编译时被视为字段。对于常规类中的局部变量或方法参数的命名，ArchUnit在当前版本（如1.0.0-rc1）中不提供直接的、开箱即用的支持。局部变量或方法参数的命名检查通常需要更深层次的AST（抽象语法树）分析，这超出了ArchUnit作为架构测试工具的典型范畴。
未来展望： 值得注意的是，ArchUnit社区已经意识到了对更广泛的变量命名检查的需求，例如GitHub上的相关Issue（如#768）正在探讨未来版本中实现此功能的可能性。
规则扩展性： 您可以根据项目需求扩展此类规则。例如，使用haveNameMatching(".*deprecated.*")来禁止包含特定关键词的字段名，或者结合and()、or()等操作符构建更复杂的规则。
业务术语黑名单： 对于业务场景中需要禁止使用的旧有术语，如果它们体现在record的字段名中，此方法同样适用。只需将UUID.class替换为相应的业务对象类型，并将"uuid"替换为需要黑名单的旧有术语即可。

5. 总结

通过ArchUnit，我们可以有效地在Java record类型中强制执行字段命名规范，从而提高代码质量和一致性。尽管当前版本的ArchUnit主要针对类、字段和方法等结构元素进行检查，但其在架构治理方面的能力依然强大。对于record组件的命名限制，利用noFields().that().haveRawType(...).should().haveName(...)规则是一个简洁而有效的实践。随着ArchUnit的不断发展，未来有望支持更细粒度的代码元素检查，进一步赋能开发者构建更健壮、更规范的软件系统。

以上就是ArchUnit实践：在Java Record中强制执行敏感字段命名规范的详细内容，更多请关注php中文网其它相关文章！