Kotlin 中的显式 API 模式

1. 概述

本文将深入讲解 Kotlin 的 显式 API 模式（Explicit API Mode），包括它在 Strict 和 Warning 两种模式下的行为差异。你将学会如何在不同构建工具（Gradle KTS、Gradle Groovy、Maven、命令行编译器）中启用该功能。

这个特性对库作者尤其重要——它能有效防止公共接口意外暴露或类型悄然变更，避免给下游用户埋下“坑”。✅

2. 什么是显式 API 模式？

显式 API 模式主要是为 Kotlin 库开发者设计的，目的是让公共 API 更安全、清晰且一致。

启用后，Kotlin 编译器会进行额外检查，确保所有公共 API 的定义都是显式的。⚠️ 注意：该模式仅作用于生产代码，测试类（test sources）会被自动忽略。

2.1. 可见性修饰符必须显式声明

Kotlin 中，函数和属性的默认可见性是 public。虽然这在应用开发中问题不大，但在发布库时却容易“踩坑”——你不希望某个内部实现被无意中暴露成公共接口吧？

✅ 显式 API 模式强制要求：所有公共 API 必须显式标注可见性修饰符，杜绝意外暴露。

举个例子：

class Calculator {
    fun sum(a: Int, b: Int) = a + b  
}

如果启用了显式 API 模式，编译器会报错：

Visibility must be specified in explicit API mode

解决方法很简单：显式加上 public：

public class Calculator {
    public fun sum(a: Int, b: Int) = a + b
}

否则，这个类和方法就会因“隐式 public”而被拒之门外 ❌

2.2. 返回类型必须显式声明

Kotlin 的类型推断非常强大，写代码时很省事。但对公共 API 来说，依赖推断可能带来隐患——比如你重构时不小心改变了返回类型，下游用户可能毫无察觉，从而引发运行时异常。

✅ 显式 API 模式要求：公共 API 的返回类型必须明确写出，防止类型在不知情的情况下变更。

继续上面的例子：

public fun sum(a: Int, b: Int) = a + b  // ❌ 编译报错

尽管编译器能推断出返回类型是 Int，但在显式 API 模式下仍需手动声明：

public fun sum(a: Int, b: Int): Int = a + b  // ✅ 合规

否则会收到提示：

Return type must be specified in explicit API mode

这一点在涉及类型检查与转换的场景中尤为重要，显式类型能让调用方更安心。

2.3. 允许的例外情况

为了避免过度冗余，显式 API 模式允许以下几种情况无需显式声明：

主构造函数（primary constructors）
数据类的属性（properties of data classes）
属性的 getter 和 setter
被覆写的方法（overridden methods）

这些属于合理的设计妥协，既保证了关键 API 的严谨性，又不会让代码变得啰嗦。

3. 显式 API 的两种模式

Kotlin 提供两种级别来控制显式 API 的严格程度：

模式	行为
`Warning`	仅输出警告，不中断构建，适合渐进式迁移
`Strict`	直接报错，构建失败，适合 CI/CD 中强制规范

两者执行相同的检查逻辑，区别仅在于错误级别。建议新项目直接上 Strict，老项目可先用 Warning 扫描问题。

4. 如何启用显式 API 模式

需要通过编译器参数开启。以下是主流构建工具的配置方式。

4.1. Gradle (KTS)

在 build.gradle.kts 中配置：

启用 Strict 模式：

kotlin {
    explicitApi()
    // 或等价写法
    explicitApi = ExplicitApiMode.Strict
}

启用 Warning 模式：

kotlin {
    explicitApiWarning()
    // 或等价写法
    explicitApi = ExplicitApiMode.Warning
}

4.2. Gradle (Groovy)

在 build.gradle 中配置：

启用 Strict 模式：

kotlin {
    explicitApi()
    // 或等价写法
    explicitApi = 'strict'
}

启用 Warning 模式：

kotlin {
    explicitApiWarning()
    // 或等价写法
    explicitApi = 'warning'
}

4.3. Maven

在 pom.xml 中为 kotlin-maven-plugin 添加参数：

<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>compile</id>
            <phase>compile</phase>
            <goals>
                <goal>compile</goal>
            </goals>
        </execution>
        <execution>
            <id>test-compile</id>
            <phase>test-compile</phase>
            <goals>
                <goal>test-compile</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <args>
            <arg>-Xexplicit-api=strict</arg>
        </args>
    </configuration>
</plugin>

如需改为 Warning 模式，将 strict 替换为 warning 即可。

4.4. 命令行编译器

直接使用 kotlinc：

启用 Strict 模式：

$ kotlinc MyKotlinFile.kt -Xexplicit-api=strict

启用 Warning 模式：

$ kotlinc MyKotlinFile.kt -Xexplicit-api=warning

5. 总结

显式 API 模式是 Kotlin 库开发的“最佳实践”之一。它通过强制声明可见性和返回类型，帮助我们：

✅ 避免公共 API 意外暴露
✅ 防止返回类型被悄悄更改
✅ 提升 API 的可维护性和稳定性

无论你是维护开源库还是公司内部 SDK，强烈建议在项目中启用 Strict 模式，把潜在问题拦截在编译期。

文中示例代码已托管至 GitHub：https://github.com/Baeldung/kotlin-tutorials/tree/master/kotlin-api

Persistence

REST

Security