ArchUnit 中处理 Kotlin 扩展函数导致的类名检查问题

问题背景

在使用 ArchUnit 进行架构测试时，经常会遇到需要验证类名命名规范的情况。特别是在 Kotlin 项目中，当文件中同时包含数据类和扩展函数时，Kotlin 编译器会生成一个带有"Kt"后缀的辅助类，这会导致基于类名的架构测试失败。

典型场景分析

考虑以下常见场景：一个名为 FooEntity.kt 的文件中包含了一个数据类和一个扩展函数：

@Entity(name = "foo")
data class FooEntity(
    @Id
    var id: UUID,
    var name: String,
)

fun Foo.toBar(): String {
    return "Bar is better"
}

在这种情况下，Kotlin 编译器会生成两个类：

1. FooEntity - 我们显式定义的数据类
2. FooEntityKt - 包含扩展函数的辅助类

当我们使用 ArchUnit 进行如下测试时：

@ArchTest
val `check entities`: ArchRule = classes()
    .that().haveSimpleNameEndingWith("Entity")
    .or().resideInAPackage("..entity..")
    .or().areAnnotatedWith(Entity::class.java)
    .should().haveSimpleNameEndingWith("Entity")
    .andShould().resideInAPackage("..entity..")
    .andShould().beAnnotatedWith(Entity::class.java)

测试会失败，因为 FooEntityKt 类不符合"以 Entity 结尾"的命名规范。

解决方案

方案一：分离扩展函数

最直接的解决方案是将扩展函数移到单独的文件中，或者将其放入伴生对象中：

// 方案1：单独文件
// FooExtensions.kt
fun Foo.toBar(): String {
    return "Bar is better"
}

// 方案2：伴生对象
@Entity(name = "foo")
data class FooEntity(
    @Id
    var id: UUID,
    var name: String,
) {
    companion object {
        fun Foo.toBar(): String {
            return "Bar is better"
        }
    }
}

方案二：调整架构测试规则

如果无法改变代码结构，可以调整测试规则来适应这种情况：

1. 拆分测试规则：将单一的复杂规则拆分为多个针对性规则
2. 排除Kt类：添加条件过滤掉Kotlin生成的辅助类
3. 放宽包规则：允许包中包含非实体类

示例实现：

// 规则1：验证带@Entity注解的类必须符合实体命名规范
@ArchTest
val `annotated entities should follow naming convention`: ArchRule =
    classes()
        .that().areAnnotatedWith(Entity::class.java)
        .should().haveSimpleNameEndingWith("Entity")

// 规则2：验证实体包中的类要么是实体，要么是实体扩展
@ArchTest
val `entity package should contain only entities and their extensions`: ArchRule =
    classes()
        .that().resideInAPackage("..entity..")
        .should().haveSimpleNameEndingWith("Entity")
        .orShould().haveSimpleNameEndingWith("EntityKt")

方案三：自定义谓词

对于更复杂的情况，可以创建自定义谓词来精确识别需要检查的类：

private fun isEntityOrEntityExtension(): DescribedPredicate<JavaClass> {
    return object : DescribedPredicate<JavaClass>("be an entity or entity extension") {
        override fun test(javaClass: JavaClass): Boolean {
            return javaClass.simpleName.endsWith("Entity") ||
                   (javaClass.simpleName.endsWith("Kt") && 
                    javaClass.methods.all { it.isExtensionFunctionForEntity() })
        }
    }
}

private fun JavaMethod.isExtensionFunctionForEntity(): Boolean {
    return modifiers.contains(JavaModifier.STATIC) &&
           parameters.size == 1 &&
           parameters[0].type.simpleName.endsWith("Entity")
}

最佳实践建议

1. 保持测试专注：每个测试规则应该只验证一个特定的方面
2. 合理使用包结构：考虑将扩展函数放在单独的包中
3. 平衡严格性与灵活性：对于工具生成的类可以适当放宽规则
4. 文档化约定：在团队中明确约定扩展函数的存放位置

通过以上方法，可以在保持架构整洁的同时，灵活处理 Kotlin 语言特性带来的特殊情况。