Java中怎么用 ArchUnit 编写架构规则拦截代码中滥用无界通配符 `List` 的行为-java教程-PHP中文网

archunit 可有效检测并拦截无界通配符（如 list），核心是识别 wildcardtype 且上界为 object、下界为空，并在方法参数、返回值、字段中禁止使用，以保障类型安全与可维护性。

java中怎么用 archunit 编写架构规则拦截代码中滥用无界通配符 `list<?>` 的行为

ArchUnit 可以有效检测代码中滥用无界通配符（如 List>）的情况，关键在于识别泛型类型中存在 WildcardType 且未指定上界或下界（即无界通配符），并结合实际使用场景（如方法参数、返回值、字段声明）进行规则拦截。

识别无界通配符的类型特征

Java 的 java.lang.reflect.Type 体系中，无界通配符对应 WildcardType 实例，其 getUpperBounds() 返回 {Object.class}，getLowerBounds() 返回空数组。ArchUnit 提供了 JavaType 和 JavaParameterizedType 等封装，可通过 resolveTypeArgument(...) 或反射底层 Type 获取原始信息。

ArchUnit 默认不直接暴露原始 Type，需用 javaClass.getGenericSuperclass() 或 javaMethod.getGenericReturnType() 等获取原始 Type
对字段、参数、返回值等元素，先调用 getRawType() 判断是否为泛型类型（如 List），再通过 getTypeDescription().getActualTypeArguments() 获取类型参数
若某个类型参数是 JavaWildcardType，且其上界为 Object、下界为空，则判定为无界通配符

编写 ArchUnit 规则拦截 `List>` 声明

以下规则禁止在方法参数、返回值和字段中出现无界通配符（如 List>、Map, ?>），但允许有界通配符（如 List extends Number>）：

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

import com.tngtech.archunit.core.domain.JavaField;
import com.tngtech.archunit.core.domain.JavaMethod;
import com.tngtech.archunit.core.domain.JavaParameter;
import com.tngtech.archunit.core.domain.properties.CanBeAnnotated;
import com.tngtech.archunit.lang.ArchRule;
import com.tngtech.archunit.lang.syntax.ArchRuleDefinition;

ArchRule NO_UNBOUNDED_WILDCARDS = ArchRuleDefinition
    .noFields()
        .should().haveRawType("java.util.List")
        .orShould().haveRawType("java.util.Map")
        .orShould().haveRawType("java.util.Set")
        .orShould().haveRawType("java.util.Collection")
        .because("unbounded wildcards like List> reduce type safety and hinder maintainability")
    .andShould().beDeclaredInClassesThat().resideInAPackage("..domain..")
    .andShould().beDeclaredInClassesThat().resideInAPackage("..dto..")
    .andShould().beDeclaredInClassesThat().resideInAPackage("..service..");

// 更精确：检查泛型参数是否为无界通配符
ArchRule STRICT_NO_UNBOUNDED_WILDCARDS = ArchRuleDefinition
    .methods().that().arePublic().or().areProtected()
        .should().haveRawReturnType("java.util.List")
            .andShould().haveTypeParameterAtPosition(0).that().areUnboundedWildcard()
        .orShould().haveRawReturnType("java.util.Map")
            .andShould().haveTypeParameterAtPosition(0).that().areUnboundedWildcard()
            .andShould().haveTypeParameterAtPosition(1).that().areUnboundedWildcard()
        .orShould().haveRawReturnType("java.util.Set")
            .andShould().haveTypeParameterAtPosition(0).that().areUnboundedWildcard()
    .orShould().parameters().that().haveRawType("java.util.List")
        .andShould().haveTypeParameterAtPosition(0).that().areUnboundedWildcard()
    .orShould().fields().that().haveRawType("java.util.List")
        .andShould().haveTypeParameterAtPosition(0).that().areUnboundedWildcard();

⚠️ 注意：haveTypeParameterAtPosition(...).that().areUnboundedWildcard() 需要自定义条件（ArchUnit 1.2+ 内置支持有限），推荐用 ArchCondition 手动校验：

private static ArchCondition<javamethod> haveUnboundedWildcardInParameterAt(int index) {
    return new ArchCondition("have unbounded wildcard at parameter " + index) {
        @Override
        public void check(JavaMethod method, com.tngtech.archunit.core.domain.DependencyCollector dependencies) {
            if (index >= method.getParameterTypes().size()) return;
            JavaType paramType = method.getParameterTypes().get(index);
            if (paramType instanceof JavaParameterizedType) {
                List<javatype> args = ((JavaParameterizedType) paramType).getTypeArguments();
                if (args.size() > index && isUnboundedWildcard(args.get(index))) {
                    fail(method, "uses unbounded wildcard in parameter " + index);
                }
            }
        }
    };
}

private static boolean isUnboundedWildcard(JavaType type) {
    return type instanceof JavaWildcardType
        && type.getErasure().equals(Object.class)
        && ((JavaWildcardType) type).getExtendsBound() == null
        && ((JavaWildcardType) type).getSuperBound() == null;
}
</javatype></javamethod>

集成到测试并启用严格模式

将规则加入 JUnit 测试类，确保构建时失败而非仅警告：

@Test
public void no_unbounded_wildcards_in_api_layers() {
    JavaClasses importedClasses = new ClassFileImporter()
        .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
        .importPackages("com.example.app");

    STRICT_NO_UNBOUNDED_WILDCARDS.check(importedClasses);
}

建议在 CI 中运行该测试，避免无界通配符流入主干
可配合 @ArchTest 注解（ArchUnit 1.0+）简化写法
若项目已广泛使用 List>，初期可用 ArchRuleDefinition.warnings().… 收集问题，再逐步收敛

为什么禁用 `List>` 而非所有通配符？

无界通配符 List> 几乎无法安全地添加/读取元素（只能 add(null)，get() 返回 Object），丧失泛型核心价值；而有界通配符如 List extends Animal> 或 List super Dog> 在 PECS 原则下有明确用途。

List> ≈ List（原始类型），编译器无法做类型推导，易引发 ClassCastException
常见误用场景：DTO 字段、REST 接口参数、Service 方法返回值——这些位置应明确类型或使用有界通配符
替代方案：用具体类型（List<string></string>）、有界通配符（List extends Serializable>）或泛型方法（<t> void process(List<t> list)</t></t>）