1. 引言与ArchUnit基础
在现代java项目中，维护一致的代码风格和命名规范是确保代码可读性、可维护性和团队协作效率的关键。archunit作为一个强大的java架构测试库，允许开发者通过编写单元测试来验证和强制执行各种架构规则。这些规则可以涵盖包依赖、类命名、方法调用等多个层面。
本教程将聚焦于一个具体的应用场景：如何利用ArchUnit在Java 17引入的record类型中，对特定类型的字段（即record组件）强制执行命名规范，例如禁止将UUID类型的字段命名为uuid。
环境配置示例： 为了使用ArchUnit进行架构测试，您需要在项目中添加相应的依赖。以下是一个典型的Maven配置示例：
17 2.7.0 5.8.2 1.0.0-rc1com.tngtech.archunit archunit-junit5${archunit.version} test org.junit.jupiter junit-jupiter-engine${junit-jupiter-engine.version} test
2. 理解Java Record的特性
Java record是一种特殊类型的类，旨在作为不可变数据载体，简化数据传输对象（DTO）的创建。其核心特性之一是：record的组件（在声明时定义的参数）会自动成为record的私有final字段，并生成相应的访问器方法。
例如，对于以下record声明：
public record MyRecordClass(UUID id, String name) {}id和name不仅是构造函数的参数，它们也是MyRecordClass实例的实际字段。正是由于这一特性，ArchUnit能够将record组件视为普通字段进行分析和规则检查。
3. 核心规则：禁止特定字段命名
针对在record中黑名单特定字段命名，ArchUnit提供了一种直接且强大的方式：noFields().that().haveRawType(...).should().haveName(...)。
规则详解：
- noFields(): 这是一个ArchUnit规则定义的起点，表示我们正在定义一个关于字段的规则。
- that().hav
eRawType(UUID.class): 这是一个过滤条件，用于选择所有原始类型为UUID.class的字段。您可以根据需要替换为任何其他类型。 - should().haveName("uuid"): 这是规则的核心断言，它声明被选中的字段不应该（should()，此处为否定规则，即noFields()...should()...）拥有名称"uuid"。如果字段名称与此匹配，则测试失败。
- because("..."): 这是一个可选但强烈推荐的说明，用于解释该规则的目的或违反规则的原因。当测试失败时，这条信息会显示在错误报告中，帮助开发者理解问题所在。
eRawType(UUID.class): 这是一个过滤条件，用于选择所有原始类型为UUID.class的字段。您可以根据需要替换为任何其他类型。示例代码：强制禁止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的不断发展，未来有望支持更细粒度的代码元素检查，进一步赋能开发者构建更健壮、更规范的软件系统。
