2. 搭建开发环境
Kotlin 开发者的工作环境由三个相互独立的组成部分构成:
- JDK (“Java Development Kit”):如本文档所用,Kotlin 被编译为 字节码 ,并由 Java 虚拟机 (JVM)执行,就像 Java 程序一样。JDK 提供这个虚拟机、运行程序的 [java] 命令、标准的 Java SE 库(Kotlin 直接使用它们:文件、网络、日期、线程等),以及 [javap] 或 [jar]等工具;
- 项目 构建工具,这里是 Gradle:它下载 Kotlin 编译器和项目所需的库,编译项目,运行其测试,并进行打包;
- 一个 编辑器 或 IDE (集成开发环境):[IntelliJ IDEA]由创建 Kotlin 的公司设计,是自然的选择;[VS Code] 配合 Kotlin 扩展是另一种选择。IDE 以 JDK 为基础,并且能够读取 Gradle 项目。
Kotlin 编译器本身不在此列:Gradle 会为每个项目下载它,IntelliJ IDEA 也内置了它。不过,你也可以使用 [kotlinc] 命令单独安装它,用来编译单个文件:我们会在第一个程序中这样做,但这是可选的。
本文档对所有操作都使用 [java]、[kotlinc]和 [gradlew] 命令:无论你选择哪种编辑器,它们在 Windows、Linux 和 macOS 上的工作方式都相同。
2.1. JDK 25
2.1.1. 安装
JDK 有多种发行版,它们都由 OpenJDK 源代码构建,对我们的用途来说是等价的。我们推荐 Eclipse Temurin,这是 Eclipse 基金会提供的免费开源发行版,可从 https://adoptium.net下载:在那里选择版本 25—LTS、操作系统和软件包类型(在 Windows 上是 [.msi] 安装程序)。在 Windows 上,你也可以在终端(PowerShell 或命令提示符)中使用 [winget] 包管理器安装:
必须选择 JDK (它包含全部内容),而不是只选择 JRE(它只能运行预编译的程序)。在 Windows 上安装时,请勾选把 JDK 添加到 [PATH] 并设置 [JAVA_HOME] 环境变量的选项:Gradle、[kotlinc] 编译器和 IDE 文件都用它来定位 JDK。在 Linux 上,JDK 可在主要发行版的软件仓库中获得(例如在 Ubuntu 上使用 [sudo apt install openjdk-25-jdk] )。
安装完成后,打开一个 新的 终端,验证 [java] 命令可用并显示 JDK 的版本:
这些结果是使用 JDK Temurin 25.0.4 得到的,本文档就是用它编写的。确切的版本取决于安装日期:错误修复更新每季度发布一次。所有 JDK 25.0.x 版本都适用于本文档。同一台计算机上可以共存多个 JDK 实例:在 [PATH] 目录中找到的第一个会响应 [java] 命令。
JDK 还包含 Java 编译器 [javac] ([javac --version] 显示 [javac 25.0.4])。我们用不到它:Kotlin 编译器自己生成字节码。但它就在那里,而且一个 Gradle 项目可以轻松地混合 Kotlin 和 Java 文件,它们能协同工作。
2.1.2. JDK 的命令
下面是我们将使用的 JDK 命令:
命令 | 作用 |
[java -jar program.jar] | 运行 [.jar] 归档中包含的程序,其清单文件指定了主类 |
[java -cp classes MyClass] | 执行已编译类的 [main] 函数,该类在类路径中查找([-cp],“class path”) |
[javap -cp classes MyClass] | 显示已编译类的成员:我们将用 它来查看 Kotlin 编译器生成了什么 |
[jar] | 创建或读取 [.jar] 归档(已编译类的 ZIP 文件) |
JDK 还提供交互式解释器 [jshell],但它只接受 Java 语句。要在不编写程序的情况下测试 Kotlin 表达式,请改用下文介绍的 IntelliJ IDEA 工具。
2.2. Kotlin 命令行编译器
2.2.1. 安装
此安装是 可选的:Gradle 项目不需要它,IntelliJ IDEA 也包含自己的编译器。它使你可以在终端中编译并运行独立的 Kotlin 文件,而无需创建项目。
编译器可以从 Kotlin 项目的发布版本页面下载,具体是 GitHub(https://github.com/JetBrains/kotlin/releases):在 2.4.20 版的“Assets”部分,下载归档 [kotlin-compiler-2.4.20.zip]。将其解压到一个文件夹,例如 [C:\Program Files\kotlinc],并将其子文件夹 [bin] 添加到 [PATH] (Windows:“编辑系统环境变量”)。你也可以使用包管理器:在 Windows 上使用 [scoop install kotlin] (借助 Scoop),或在 Linux 和 macOS 上使用 SDKMAN!([sdk install kotlin 2.4.20])。编译器需要 JDK,它通过 [JAVA_HOME] 变量或 [PATH] 变量来定位 JDK。
在新终端中验证安装:
编译器版本(2.4.20)后面跟着运行它的 JVM 版本(JDK 25)。
2.2.2. 编译器命令
[bin] 目录包含两个主要命令:[kotlinc] (编译器)和 [kotlinr] (启动器,“runner”):
命令 | 作用 |
[kotlinc File.kt -d classes] | 编译一个或多个源文件,并将生成的 [.class] 文件放入 [classes] 文件夹 |
[kotlinc File.kt -include-runtime -d prog.jar] | 编译并生成名为 [.jar], 的可执行归档,其中还包含 Kotlin 标准库 |
[kotlinr -cp classes MyClass] | 与 [java -cp classes MyClass]相同,但会把 Kotlin 标准库添加到类路径中 |
[kotlinr script.main.kts] | 运行 Kotlin 脚本 (文件 [.main.kts]),没有可见的编译步骤 |
Kotlin 脚本是一系列从上到下执行的指令,没有 [main] 函数。例如,下面的脚本 [essai.main.kts]:
运行结果如下:
在 Kotlin 2.4.20 之前,该启动器名为 [kotlin];在 Kotlin 2.4.20 中它被重命名为 [kotlinr] ,以避免与另一个命令 [kotlin] 发生命名冲突,后者属于“Kotlin Toolchain”工具。旧名称在 2.4.20 版编译器中仍然有效(并未被正式弃用),但 Kotlin 文档现在推荐使用 [kotlinr]。
不带任何参数时,[kotlinc] 命令曾用于启动交互式解释器(“REPL”,相当于 [jshell])。此功能现已被弃用:
要试验几行 Kotlin 代码,应改用 IntelliJ IDEA 创建的 草稿文件 (“File / New / Scratch File”,选择 Kotlin 语言),它会在每一行旁边显示结果。
2.3. Gradle
2.3.1. Gradle 的作用
实际的应用程序会使用不属于 JDK 或 Kotlin 标准库的 库 :数据库驱动、测试框架、Hibernate、Spring、协程……它们以 [.jar] 归档的形式通过公共仓库 Maven Central (https://central.sonatype.com)分发。构建工具读取项目描述来确定它需要哪些库,下载它们(连同它们所依赖的库),然后编译、测试并打包项目。
Java 世界中的两大构建工具是 Maven (本文档所依据的 Java 课程使用它)和 Gradle。Kotlin 可以与两者配合使用,但 Gradle 是 Kotlin 生态系统中事实上的标准:Android 以及 IntelliJ IDEA 创建的 Kotlin 项目都使用它,而且它的构建文件是用……Kotlin 编写的。本文档使用 Gradle 9.8。
2.3.2. Gradle 包装器:无需安装
无需安装 Gradle。本文档中的每个项目都自带 Gradle 包装器——一个由位于项目根目录的三个文件组成的小型启动器:
- [gradlew]:适用于 Linux 和 macOS 的启动脚本([./gradlew]);
- [gradlew.bat]:适用于 Windows 的同一脚本([gradlew]);
- [gradle/wrapper] 文件夹,其中包含启动程序([gradle-wrapper.jar])及其配置([gradle-wrapper.properties])。
文件 [gradle-wrapper.properties] 指定要使用的 Gradle 版本:
第一次运行时,[gradlew] 会下载这个版本的 Gradle 并存储在计算机上;之后再运行时,直接使用它。因此,每个项目都使用编写它时所用的 Gradle 版本,而不论计算机上安装的是哪个版本。Gradle 运行只需要一个 JDK,它通过 [JAVA_HOME] 变量或 [PATH] 变量找到它。
在本文档中,命令采用 Windows 格式书写([gradlew build]);在 Linux 或 macOS 上,应写成 [./gradlew build]。在 PowerShell 中,还必须写成 [.\gradlew build]。
如果你仍想使用 [gradle] 命令(例如用 [gradle init] 创建项目),请从 [gradle-9.8.0-bin.zip] 归档下载 https://gradle.org/releases,解压后将其 [bin] 子文件夹添加到 [PATH];或者使用 [scoop install gradle] 或 [sdk install gradle]。然后验证安装:
这些结果是在 Linux 上得到的。[Kotlin:] 这一行给出了 集成在 Gradle 中的 Kotlin 版本,它用于读取 [.gradle.kts] 构建文件:它与用于编译我们程序的 Kotlin 编译器版本(2.4.20)无关,后者由各个项目设定。[Launcher JVM] 这一行表示运行 Gradle 的 JDK。
2.3.3. Gradle 命令
[gradlew] 命令后面跟一个或多个 任务;它在项目的根目录中输入,即包含 [settings.gradle.kts] 文件的目录:
命令 | 作用 |
[gradlew build] | 编译 [src/main/kotlin] 的源代码,运行测试,并创建项目归档 [.jar] 于 [build/libs] 中 |
[gradlew run] | 先编译,再运行项目的主类([application] 插件) |
[gradlew test] | 先编译,再运行 [src/test/kotlin] 的单元测试(第 6 章) |
[gradlew clean] | 删除 [build] 文件夹 |
[gradlew tasks] | 显示项目中可用任务的列表 |
[gradlew installDist] | 在 [build/install] 中创建程序的可安装版本:其归档和启动脚本 |
[gradlew bootRun] | 运行 Spring Boot 应用程序(第 13 章) |
任务之间相互依赖:运行 [run] 也会触发编译,而且 Gradle 只重新运行自上次构建以来发生变化的部分。[-q] (“quiet”)选项会抑制 Gradle 消息,只显示被执行程序的消息;[-Pname=value] 选项设置构建文件可以读取的 属性 :我们将用它来选择要运行哪个程序。由 [run] 启动的程序的参数通过 [--args="a b"] 选项传递。
在项目中运行的第一条命令会很慢:Gradle 会启动一个后台进程(Gradle“守护进程”),它会保持活动几个小时以加快后续命令的速度,并下载项目所需的内容。
2.3.4. Maven Central 与 Gradle 缓存
Gradle 下载的库存储在本地的 Gradle 缓存中,即 [%USERPROFILE%\.gradle\caches] 文件夹(Linux 和 macOS:[~/.gradle/caches])。它们只下载一次,之后由所有项目重复使用。因此,第一次构建项目时需要互联网连接。同一个 [.gradle] 文件夹在 [wrapper/dists]中还包含由包装器下载的 Gradle 版本。
库由其 坐标标识——用冒号分隔的三个名称:组(通常是反向域名,例如 [org.hibernate.orm])、库名称及其版本,例如 [tools.jackson.core:jackson-databind:3.1.5]。这些坐标就是你在项目构建文件中要填写的内容,可以通过在 Maven Central 网站上搜索该库找到它们。
2.3.5. Kotlin 语法:DSL
项目的构建文件名为 [build.gradle.kts]。扩展名 [.kts] 表示它是一个 Kotlin 脚本:该文件使用一种基于 Kotlin 语法构建的专用语言(“DSL”,“Domain Specific Language”,领域特定语言)编写。Gradle 还支持用 Groovy 编写的 [build.gradle] 文件,它们见于较旧的项目;自 Gradle 8.2 起,Kotlin DSL 已成为默认格式。下面是一个典型的节选:
即使还不了解 Kotlin,你也可以把这段文本当作配置来阅读:
- 一个名称后面跟着用花括号括起来的块([plugins { ... }]、[dependencies { ... }])就是配置的一个 节 。在 Kotlin 中,这是一次函数调用,它接受一个代码块作为参数(即 lambda,第 7 章);
- [kotlin("jvm")] 和 [implementation("...")] 是函数调用;字符串用双引号括起来;
- [version = "1.0"] 为项目属性赋值。
这种格式的一个优点是,IntelliJ IDEA 把它识别为 Kotlin 代码:它提供代码补全,并在你输入时标出错误。
2.4. 编辑器
2.4.1. IntelliJ IDEA
IntelliJ IDEA由 JetBrains 公司出品,是本文档推荐的编辑器。JetBrains 也是开发 Kotlin 的公司(该语言的第一个稳定版本发布于 2016 年),并持续开发它:IntelliJ IDEA 内置了对 Kotlin 的支持,无需任何扩展,而且它是最紧跟语言演进的版本。其基本功能对本文档来说绰绰有余,并且是免费的。
IntelliJ IDEA 能识别 Gradle 项目:选择“File / Open”,然后选择包含 [settings.gradle.kts] 文件的文件夹;IntelliJ 会启动 Gradle 读取项目(你可以在“Build”窗口中监视这一过程),下载库,然后显示“Gradle”视图,通过它可以访问项目的所有任务。然后,你可以点击 绿色三角形 来运行程序,该三角形位于其 [main] 函数旁边的边栏中([Ctrl-Shift-F10]),或者点击测试函数旁边的同样三角形来运行测试。你在“File / Project Structure / SDK”中指定要使用的 JDK;对于 Gradle 项目,通常由项目的 [jvmToolchain(25)] 声明(见下文)来指定用于编译的 JDK。
IntelliJ IDEA 还提供 Kotlin 专属的功能:将 Java 文件自动转换为 Kotlin(“Code / Convert Java File to Kotlin File”,或者直接把 Java 代码粘贴到 Kotlin 文件中)、显示编译器生成的字节码(“Tools / Kotlin / Show Kotlin Bytecode”),以及前面提到的草稿文件。
2.4.2. VS Code
VS Code是一款免费的跨平台编辑器。要用 Kotlin 编程,请安装由 JetBrains 发布的 Kotlin 扩展(进入“Extensions”菜单,搜索“Kotlin”,选择发布者为 JetBrains 的那个)。这个官方扩展 还很新:它使用与 IntelliJ IDEA 相同的代码分析引擎,可以导入 Gradle 项目,但还不能提供 IDE 或 JetBrains 的全部功能,而且其功能会随版本变化。请查看扩展的页面,了解安装时它支持什么。就本文档的目的而言,它适合阅读和编辑程序;你始终可以使用正文中给出的 [gradlew] 命令,在内置终端(“Terminal / New Terminal”)中运行它们。
在 VS Code 中,打开某一章的 文件夹 (“File / Open Folder”),例如 [kotlin-oct-2026/03-basics] 文件夹。
2.4.3. Android Studio
Kotlin 也是 Google 推荐用于 Android 应用的语言。Android Studio基于 IntelliJ IDEA 构建,专用于这类应用,本文档不涉及。
在本文档的其余部分,操作使用 [java]、[kotlinc]和 [gradlew]命令来描述,无论使用哪种编辑器,它们都产生相同的结果。
2.5. 示例程序:Hello.kt 文件
2.5.1. 程序
Kotlin 程序可以只是一个包含名为 [main] 的函数的简单文件,无需声明类。让我们创建如下文件 [Hello.kt] (位于 [02-installation] 示例文件夹中):
说明:
- 第 1 行:注释。[//] 之后直到行尾的所有内容都会被编译器忽略;
- 第 2 行:[main] 函数,即程序的入口点。关键字 [fun] 引入一个函数。它声明在 文件级别 (“顶层函数”),位于任何类之外;它不需要声明为 [public] (这是 Kotlin 的默认可见性),也不需要接收任何程序参数;
- 第 3 行:程序唯一的语句:它在屏幕上打印一行文本。[println] 函数(以及 [print],它不换行)是 Kotlin 标准库的一部分;它相当于 Java 中的 [System.out.println] 。请注意语句末尾没有分号:在 Kotlin 中分号是可选的,不写。
这个程序比 Java 课程中的等价程序([void main() { IO.println(...); }])略微简单一些,但真正的区别在别处:顶层 [main] 函数自 Kotlin 的第一个版本起就存在,而 Java 直到 Java 25 才支持它。
2.5.2. 编译与执行
我们用 [kotlinc] 编译程序,指定一个名为 [.jar] 的可执行归档,然后使用 JDK 的 [java] 命令运行它:
- [-d hello.jar]:编译目标。如果它以 [.jar] 结尾,编译器就生成归档;否则它是一个文件夹,编译器把 [.class] 文件存放在其中;
- [-include-runtime]:归档中还包含 Kotlin 标准库 ([kotlin-stdlib]),Kotlin 程序在运行时需要它,还包含指定主类的清单文件。这样,程序就可以通过 [java -jar] 在任何安装了 JDK(或 JRE)的机器上运行,即使该机器没有安装 Kotlin。另一方面,该归档的大小超过 5 MB,主要由标准库构成;
- 编译需要几秒钟:Kotlin 编译器本身是一个 Java 程序,必须先启动。Gradle 和 IntelliJ IDEA 通过在两次编译之间保持一个编译器处于活动状态来避免这一开销。
Kotlin 中没有与 Java 命令 [java Hello.java] 等价的命令,后者一步完成源文件的编译和执行;最接近的等价物是上文介绍的 [.main.kts] 脚本。
2.5.3. 编译器生成了什么
Java 虚拟机(JVM)只认识类:函数不能存在于类之外。因此,Kotlin 编译器会把文件中的顶层函数 包装 进它生成的一个类中,并按文件命名:文件名后面加上 [Kt]。对于 [Hello.kt],生成的类是 [HelloKt]。JDK 的 [javap] 命令显示它的成员:
- 类 [HelloKt] 是 [public final];
- 它包含我们的 [main] 函数,该函数已变成不带参数的静态方法;
- 还有第二个方法 [main(String[])],由编译器添加:这就是虚拟机知道如何调用的 [public static void main(String[] args)] 方法。它只是调用第一个方法。我们将在第 3 章回到这一机制。
正是这个类名标识了要执行的程序:[hello.jar] 的清单文件包含这一行 [Main-Class: HelloKt],也可以写成 [java -cp hello.jar HelloKt]。
与 Java 不同,对 文件名没有限制:它不必是有效的标识符,也不必与其包含的某个类的名称一致。名为 [first-try.kt] 的文件是可以接受的,其生成的类名为 [First_tryKt] (编译器把首字母大写,并把标识符中禁止出现的字符替换为 [_])。不过按照惯例,文件名以大写字母开头且不含连字符,例如 [Hello.kt] 或 [Basics01.kt]。
在 Windows 上,用 [println] 写出的带重音符号的字符能在终端中正确显示:虚拟机会把文本转换为终端的编码。源文件必须保存为 UTF-8,这是 VS Code 和 IntelliJ IDEA 的默认编码,也是 Kotlin 编译器始终假定的编码。当程序由 Gradle 启动时([gradlew run],或 Gradle 项目中的绿色三角形),情况就不同了:其输出不再是控制台,而是通向 Gradle 的管道,虚拟机随后用历史上的 Windows 编码(windows-1252)对其编码,这样等待 UTF-8 的 IntelliJ IDEA 就会在每个带重音符号的字符处显示一个占位字符(里面带问号的菱形)。课程项目在其 [build.gradle.kts] 文件中解决了这个问题(见下一节)。对于 IntelliJ IDEA 的内置终端(PowerShell),你也可以在会话开始时输入 [chcp 65001] 把控制台切换到 UTF-8,或者通过在“File / Settings / Tools / Terminal / Shell path”中把 [powershell.exe -NoExit -Command "[Console]::OutputEncoding = [Text.Encoding]::UTF8"] 指定为解释器来一劳永逸地解决。
[kotlinc] 命令适用于只使用标准库的单文件程序。一旦程序需要外部库,你就必须下载它——连同它所依赖的库——并把它传递给编译器,然后再传递给虚拟机:这就涉及创建 Gradle 项目。本文档中的所有示例都将这样做。
2.6. Gradle 项目
2.6.1. 项目结构
Gradle 项目 是一个文件夹,其中包含名为 [build.gradle.kts] 的构建文件,以及按标准目录结构组织的源文件。Gradle 构建的根目录还包含名为 [settings.gradle.kts] 的文件,它提供构建的名称和所含项目的列表,以及包装器。示例中的 [02-installation] 文件夹是一个把两个项目 [FirstProgram] 和 [TwoHands] 组合在一起的构建:
- [src/main/kotlin] 包含程序的源文件;[src/main/resources] 用于存放要与编译后的类放在一起的数据或配置文件;[src/test/kotlin] 用于存放测试(第 6 章);
- 在 [src/main/kotlin] 之下,文件夹结构与 包 (第 4 章)的结构相对应:包 [first] 中的文件 [Main.kt] 位于文件夹 [first] 中。与 Java 不同,Kotlin 并不强制这种对应关系,但推荐这样做,我们将始终遵循;
- 文件 [Hello.kt] 不属于任何项目:把它放在那里是为了用 [kotlinc] 编译,Gradle 会忽略它。
独立项目(不与其他项目组合)具有相同的结构,带有自己的 [settings.gradle.kts] 和包装器文件:第 3 章的项目就是这种情况。你可以手动创建这个目录结构,也可以让 IDE 来创建(IntelliJ:“File / New / Project”,选择“Kotlin”作为语言、“Gradle”作为构建系统,并使用 Kotlin DSL)。
我们将在下一节介绍根目录中的文件。[build.gradle.kts] 文件在 [FirstProgram] 项目中的内容如下:
说明:
- 第 1 行:注释。构建文件是用 Kotlin 编写的:注释的写法与在程序中完全一样。
- 第 2–7 行:应用于项目的 插件 。它们为 Gradle 提供我们需要的任务:
- 第 4 行:用于 JVM 的 Kotlin 插件。它添加编译 [src/main/kotlin] 中文件的任务,并自动把 Kotlin 标准库添加到项目的依赖中。记法 [kotlin("jvm")] 是插件完整标识符 [org.jetbrains.kotlin.jvm] 的简写。这里没有指定其版本,因为该项目属于一个多项目构建,由根项目为所有项目统一设定这一版本(见下一节)。在独立项目中,你应写成 [kotlin("jvm") version "2.4.20"]:这个版本决定所使用的 Kotlin 编译器的版本;
- 第 6 行:[application] 插件,它添加任务 [run] (运行程序)和 [installDist] (准备可安装版本);
- 第 10–11 行:项目、组和版本 标识符,它们通过名称([FirstProgram],即其文件夹的名称)来标识项目。它们也是另一个项目引用本项目时可以使用的标识符,类似于引用 Maven Central 中某个库的方式(第 6 章);
- 第 14–15 行:Gradle 查找项目库的仓库,这里是 Maven Central;
- 第 18–20 行:项目使用的库。除了 Kotlin 插件自动添加的 Kotlin 标准库之外,这个项目不使用任何库;
- 第 24 行:项目的工具链:代码针对 Java 25 编译,并由 [gradlew run] 使用 JDK 25 运行,即使 Gradle 本身由另一个 JDK 运行。Gradle 在机器上已安装的 JDK 中查找这个 JDK。如果找不到,它会失败并给出错误消息 [Cannot find a Java installation on your machine ... matching: {languageVersion=25 ...}],除非构建声明了 [foojay-resolver-convention] 插件——课程中的所有项目都声明了它(见下一节):这样 Gradle 就会自行下载 JDK 25。在 IntelliJ IDEA 中,你也可以通过“File / Project Structure / SDK / Add SDK / Download JDK”安装这个 JDK;
- 第 27 行:编译器警告被视为错误,并会中止编译。Kotlin 编译器会标出许多问题(未使用的变量、不必要的类型转换、多余的 [!!] 运算符等):我们希望程序不出现任何这类问题;
- 第 29 行:编译器在字节码中保留函数参数的名称。一些库会利用这一点,例如 Jackson 用它从 JSON 文档创建对象(第 5 章),Spring 也是如此(第 13 章);
- 第 33–35 行:由 [gradlew run] 执行其 [main] 函数的类。这个名称是编译器为 [first] 包中的 [Main.kt] 文件生成的类的名称:[first.MainKt];
- 第 38–41 行:所有执行 Java 程序的任务([JavaExec]),例如 [run],都会从虚拟机收到两个选项:程序的屏幕输出([System.out]、[System.err])以 UTF-8 编码。没有它们,程序写出的带重音符号的字符在 Windows 下 IntelliJ IDEA 的控制台中会出现乱码(见上文关于重音符号的说明)。[tasks.withType<JavaExec>()] 指代这种类型的所有任务,而 [configureEach { … }] 配置其中的每一个。所有运行程序的课程项目都包含此配置。
这个项目不使用任何库。使用库的项目会在 [dependencies] 节中用其坐标声明它,从第 5 章开始我们就会这样做:
术语 [implementation] 表示编译和运行程序都需要该库。你还会遇到 [runtimeOnly] (仅执行时需要,例如数据库驱动)和 [testImplementation] (仅测试时需要)。然后,Gradle 会下载 [jackson-databind] 以及它所依赖的库。
文件 [Main.kt] 包含程序:
- 第 1 行:该文件属于 [first] 包。因此,为该文件生成的类的完整名称是 [first.MainKt];
- 第 4–6 行:[main] 函数,其形式与 [Hello.kt] 中的相同。一个 Kotlin 文件可以包含任意数量的函数和类,无论是否公开:文件名不取决于其内容。
2.6.2. 编译与执行
命令 [gradlew build] 在 [02-installation] 文件夹中输入,会编译构建中的各个项目(如果它们有测试,还会运行测试):Gradle 按需下载 Kotlin 插件、编译器和标准库,然后编译 [src/main/kotlin] 中的文件,并为每个项目把生成的类放入 [build/classes/kotlin/main] 文件夹,同时保留包结构([FirstProgram/build/classes/kotlin/main/first/MainKt.class])。
[gradlew run] 命令先编译项目,再运行它。在涉及多个项目的构建中,项目由其路径指定,路径前加冒号:[:FirstProgram:run] 是 [run] 任务,属于项目 [FirstProgram]。使用选项 [-q] 时,只显示程序输出:
你也可以进入项目文件夹并输入 [..\gradlew -q run]:Gradle 会向上追溯到根目录中的 [settings.gradle.kts] 文件,并执行当前文件夹中该项目的 [run] 任务。另一方面,在根目录输入 [gradlew run] 会为 [run] 任务执行 所有 具有该任务的项目。
项目编译完成后,你也可以使用 [java] 命令直接运行类,并指定类的位置(在 [FirstProgram] 文件夹中):
这在这里可行,是因为该程序在运行时实际上没有使用 Kotlin 标准库中的任何内容:编译器把对 [println] 的调用替换为对 [System.out.println] 的直接调用。然而,例如使用列表([listOf(1, 2, 3)])的程序,按这种方式运行会失败,并出现错误 [java.lang.NoClassDefFoundError: kotlin/collections/CollectionsKt]:找不到标准库中的 [CollectionsKt] 类。这时你必须把 [kotlin-stdlib-2.4.20.jar] 归档添加到类路径中(它在 Gradle 缓存中;[lib] 文件夹中的 [kotlinc] 编译器也包含它,名称为 [kotlin-stdlib.jar]):在 Windows 上为 [java -cp "build/classes/kotlin/main;path/kotlin-stdlib-2.4.20.jar" first.MainKt] (在 Linux 和 macOS 上分隔符是 [:] )。命令行编译器的 [kotlinr -cp build/classes/kotlin/main first.MainKt] 命令会替我们完成这一工作。
最简单的方法是使用 [installDist] 任务(来自 [application] 插件),让 Gradle 构建程序及其所需的一切:
它会创建 [FirstProgram/build/install/FirstProgram] 文件夹,其中包含一个 [lib] 文件夹(项目归档、Kotlin 标准库,以及项目的其他库,如果有的话)和一个 [bin] 文件夹,后者包含两个启动脚本:[FirstProgram] (Linux、macOS)和 [FirstProgram.bat] (Windows),它们用正确的类路径调用 [java] 。程序以这种形式交付,以便复制到另一台运行 JDK 的计算机上:
可以放心删除 [build] 文件夹([gradlew clean]):下次编译时会重新创建它。[gradlew build] 命令还会生成项目的归档 [build/libs/FirstProgram-1.0.jar],其中只包含项目自己的类。
2.7. 多模块项目
2.7.1. 多项目构建
一个 Gradle 构建可以把多个项目组合在一起,它们被称为其 子项目 (或模块)。根目录中的 [settings.gradle.kts] 文件列出它们。[02-installation] 文件夹中的该文件如下:
- 第 3–6 行:针对构建本身(而不是项目)的插件 [foojay-resolver-convention]:当项目通过 [jvmToolchain(25)] 请求一个 Gradle 在机器上找不到的 JDK 时,Gradle 会从 foojay.io服务下载它,并存储在缓存中。第一次运行会稍长一些,但学生不再需要安装正确的 JDK。[plugins] 块必须是文件中的第一个块。课程中的所有构建都声明了这个插件;
- 第 8 行:构建名称(根项目)。如果没有这一行,它就是文件夹名称;
- 第 11 行:子项目,由其文件夹名称标识。子项目可以嵌套得更深:[include("TaxV5:tax-dao")] 指的是 [TaxV5/tax-dao] 文件夹中的项目(第 6 章)。
根项目也有一个名为 [build.gradle.kts] 的文件:
- 第 3–4 行:声明了 Kotlin 插件及其版本,但没有把它应用到根项目([apply false]),根项目不包含任何要编译的代码。这个声明使插件对子项目可用,子项目通过 [kotlin("jvm")] 应用它而无需重复版本:因此所有子项目使用相同版本的 Kotlin,可以在一个位置修改。如果每个子项目各自声明插件版本,Gradle 就会多次加载它,而 Kotlin 插件不建议这样做。
在 [02-installation] 文件夹中,[gradlew build] 命令会编译这两个项目;打开该文件夹的 IDE 可以同时看到这两个项目。在第 6 章中,我们将看到一个子项目可以依赖另一个子项目([implementation(project(":TaxV5:tax-dao"))]),而在第 10 章到第 13 章中,我们将看到一个构建甚至可以复用另一个构建中的项目([includeBuild])。
2.7.2. 具有多个 main 函数的项目
一个项目可以包含多个文件,每个文件都有一个 [main] 函数:每个都是可能的入口点,要执行的类在运行时选择。[TwoHands] 项目包含 [twohands] 包中的两个文件。[P1.kt] 文件:
以及文件 [P2.kt],除名称外与前者完全相同。两个函数都名为 [main] 并且属于同一个包:它们不会冲突,因为它们位于两个不同的类中,即 [twohands.P1Kt] 和 [twohands.P2Kt]。[java] 命令执行指定给它的类(在 [TwoHands] 文件夹中,项目编译完成之后):
对于 [gradlew run] 命令,项目的 [build.gradle.kts] 文件指定要执行的类:
- 第 5 行:要执行的类由 Gradle 属性 [main] 指定,该属性通过选项 [-Pmain=...] 在命令行上提供。[providers.gradleProperty("main")] 函数读取这个属性;[orElse(...)] 指定未提供该属性时使用的值:这里是 [twohands.P2Kt] 类。
文件的其余部分与 [FirstProgram] 的相同,只是增加了对 [run] 任务的配置([standardInput = System.in]),它把键盘输入传给程序:没有它,由 [gradlew run] 启动的程序就无法读取键盘。
结果:
这样,你无需修改 [build.gradle.kts] 文件就可以选择要运行的程序。使用 IntelliJ IDEA 时不存在这个问题:每个 [main] 函数在边栏中都有自己的绿色三角形。
2.7.3. 每个程序一个包
后续各章的项目都使用这一机制,因为每个项目都包含许多小程序。为了防止这些程序相互干扰,本文档遵循一个简单的约定:每个程序有自己的包,包名是程序名的小写形式,并存放在同名的文件夹中。因此,第 3 章的程序 [Basics04.kt] 就是文件 [03-basics/src/main/kotlin/basics04/Basics04.kt],它以 [package basics04] 这一行开头;它的类是 [basics04.Basics04Kt],其执行方式如下:
这一约定有两个原因:
- 项目中的所有程序一起编译。如果它们在同一个包中,两个程序就不能声明同名的函数或类(函数 [display]、类 [Person]……):编译器会报告重复声明。每个程序一个包,每个程序就有自己的命名空间;
- 由多个文件组成的程序就是包含多个文件的包:在第 4 章中,包 [persons] 包含 [Person.kt] 中的类 [Person] ,以及 [Main.kt] 中的主程序,后者由 [-Pmain=persons.MainKt] 执行。
每章的正文都会在程序结果之前给出执行该程序的确切命令。我们将在第 3 章再讨论这一结构。
2.8. 本文档中的示例
要运行本文档中的示例:
- 下载 [kotlin-oct-2026] 文件夹(链接在文档开头)。它为每一章包含一个文件夹([02-installation]、[03-basics]、[04-classes]……),这些文件夹中的每一个都是一个 Gradle 构建,并带有其包装器:可以是单个项目,也可以是由其 [settings.gradle.kts] 文件组合在一起的多个子项目;
- 在 IntelliJ IDEA 中打开某一章的文件夹(“File / Open”);然后点击其 绿色三角形 (位于 [main] 函数旁边)来运行程序;
- 或者,在位于该章文件夹的终端中,使用 [gradlew -q run -Pmain=package.ClassKt] 运行程序(如果有多个子项目,则在 [run] 之前加上子项目路径);每章的正文都给出了确切的命令。
每章的第一条 [gradlew] 命令需要访问互联网:Gradle 会下载自己的发行版、Kotlin 插件和项目的库,并随后存储在缓存中。
第 10 章和第 11 章使用名为 MySQL 的数据库;使用 [Laragon] 安装 MySQL 的方法在附录中介绍。