Java Checker Framework：Map的NonNull值为何无法适配Nullable泛型参数？

问题重现 #

调用代码 #

schema.validate(
    MapMaker.makeMap(
        new AbstractMap.SimpleEntry<>(
            "foo",
            "baz"
        ),
        new AbstractMap.SimpleEntry<>(
            "bar",
            2
        )
    ),
    configuration
);

错误信息 #

java: [argument] incompatible argument for parameter arg of validate.
  found   : @Initialized @NonNull Map<@Initialized @NonNull String, @Initialized @NonNull Object>
  required: @Initialized @NonNull Map<@Initialized @NonNull String, @Initialized @Nullable Object>

方法定义 #

public FrozenMap<@Nullable Object> validate(Map<String, @Nullable Object> arg, SchemaConfiguration configuration) throws ValidationException, InvalidTypeException {
    // 方法实现（仅读取arg中的内容）
}

核心疑问 #

既然@NonNull Object是@Nullable Object的子类型，为什么Map<String, @NonNull Object>不能适配Map<String, @Nullable Object>？如何让NonNull值的Map正常传入？是否需要为Nullable和NonNull输入分别定义方法？

原因解析 #

Java泛型默认是**不变（invariant）**的，即使类型参数存在子类型关系，对应的泛型容器也不会自动成为子类型。这是为了保证类型安全：如果允许Map<String, @NonNull Object>传入接受Map<String, @Nullable Object>的方法，方法内部理论上可以往Map中存入null值，而调用者的Map原本是约束值不能为null的，这就会破坏类型契约，引发潜在的空指针问题。

解决方案 #

因为你的validate方法仅读取Map内容，不会修改它，所以可以通过以下方式解决：

1. 使用协变泛型接口（推荐） #

Checker Framework的@Covariant注解可以标记泛型参数为协变，适用于只读场景。你可以定义一个只读的Map子接口，将值类型参数标记为协变：

import org.checkerframework.checker.nullness.qual.Covariant;
import java.util.Map;

public interface ReadOnlyMap<K, @Covariant V> extends Map<K, V> {
    // 仅保留读取方法，屏蔽所有修改方法（可选，进一步约束只读行为）
    @Override
    V get(Object key);
    // 其他读取方法如containsKey、keySet等，移除put、remove等修改方法
}

然后修改validate方法的参数类型：

public FrozenMap<@Nullable Object> validate(ReadOnlyMap<String, @Nullable Object> arg, SchemaConfiguration configuration) throws ValidationException, InvalidTypeException {
    // 方法实现
}

此时Map<String, @NonNull Object>可以安全地传入，因为协变允许子类型的容器替换父类型容器，且只读场景下不会有类型安全风险。

2. 安全的类型转换（临时方案） #

如果无法修改接口定义，可以在调用时添加@SuppressWarnings("nullness")注解做类型转换，但必须确保方法内部绝对不会修改Map：

@SuppressWarnings("nullness")
schema.validate(
    (Map<String, @Nullable Object>) MapMaker.makeMap(...),
    configuration
);

3. 使用@PolyNull实现多态null支持 #

给方法参数的类型参数添加@PolyNull注解，让方法同时支持NonNull和Nullable的Map值：

import org.checkerframework.checker.nullness.qual.PolyNull;

public FrozenMap<@Nullable Object> validate(Map<String, @PolyNull Object> arg, SchemaConfiguration configuration) throws ValidationException, InvalidTypeException {
    // 方法实现
}

这样无论是Map<String, @NonNull Object>还是Map<String, @Nullable Object>都能匹配该方法，无需额外转换。

总结 #

不需要为Nullable和NonNull输入分别定义方法，上述三种方案都能解决问题，其中协变只读接口是最符合类型安全原则的方案，能从根源上约束方法的只读行为。

内容的提问来源于stack exchange，提问作者spacether