Kotlin调用含JetBrains注解的Java API：@Unmodifiable与List映射问题

现有如下Java API：

public interface Recipe {

    @NotNull
    List<Ingredient> getIngredients();

    void AddOptionalIngredient(@Nullable Ingredient ingredient);
}

在Kotlin中实现该接口时，IntelliJ会根据@NotNull和@Nullable注解自动插入正确的可空修饰符：

class CakeRecipe : Recipe {

    // 返回值为非可空类型...
    fun getIngredients(): MutableList<Ingredient> { ... }

    // 参数为可空类型...
    fun addOptionalIngredient(ingredient: Ingredient?) { ... }
}

但该实现存在问题：Java的List<T>会映射为Kotlin的MutableList<T>，虽可手动修改为只读List：

class CakeRecipe : Recipe {

    // 返回类型为只读（不可修改）
    fun getIngredients(): List<Ingredient> { ... }

    ...
}

了解到@Unmodifiable注解后，以为JetBrains会像识别@NotNull和@Nullable一样识别它，于是修改Java API如下：

public interface Recipe {

    @NotNull
    @Unmodifiable List<Ingredient> getIngredients();

    void AddOptionalIngredient(@Nullable Ingredient ingredient);
}

但Kotlin实现仍自动生成MutableList<T>：

class CakeRecipe : Recipe {

    // IDE未识别@Unmodifiable注解
    fun getIngredients(): MutableList<Ingredient> { ... }

    ...
}

请问@Unmodifiable注解的作用是什么？是否可以通过注解或其他方式，让Kotlin在实现对应Java的List<T>时自动使用List<T>而非MutableList<T>？

一、@Unmodifiable注解的作用 #

@Unmodifiable是JDK 9及以上版本提供的注解，核心作用是文档说明与静态代码检查：

• 作为文档标记：明确告知开发者被注解的集合是不可修改的，调用方不应尝试修改该集合；
• 静态检查支持：配合SpotBugs这类静态代码分析工具，能检测出试图修改该集合的代码，提前发现潜在bug。

但该注解不会改变Java集合的实际类型，也不会影响Kotlin对Java类型的默认映射规则——这就是添加注解后IDE仍生成MutableList的原因。

二、让Kotlin自动映射为只读List的方法 #

目前IntelliJ默认不会识别JDK的@Unmodifiable来调整Kotlin类型映射，但可以通过以下方式实现需求：

1. 使用JetBrains专属的@Unmodifiable注解 #

JetBrains提供了自己的org.jetbrains.annotations.Unmodifiable注解，这个注解会被IntelliJ识别，在生成Kotlin接口实现时，自动将Java的List<T>映射为Kotlin的只读List<T>。

使用步骤：

• 引入JetBrains annotations依赖（通过Maven/Gradle添加对应依赖）；
• 修改Java API：

import org.jetbrains.annotations.Unmodifiable;

public interface Recipe {

    @NotNull
    @Unmodifiable List<Ingredient> getIngredients();

    void AddOptionalIngredient(@Nullable Ingredient ingredient);
}

此时再生成Kotlin实现，getIngredients的返回类型会自动变成List<Ingredient>。

2. 手动修改返回类型 #

这是最直接可靠的方式，就像你之前操作的那样，把生成的MutableList手动改成List，无需额外依赖，也没有兼容性问题。

3. 自定义IDE代码模板 #

在IntelliJ中修改「实现接口」的代码生成模板，让生成的方法默认返回只读List。不过这种方式全局生效，可能影响其他项目的代码生成，需要谨慎调整。

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