一只捡星星的熊

1. Kotlin 概览#

Kotlin 是 JetBrains 设计并开源的静态类型编程语言。它最早以 JVM 语言的身份进入开发者视野，目标不是完全替代 Java 生态，而是在保持互操作能力的前提下，提供更现代、更安全、更简洁的语法和标准库。Android 官方在 2017 年宣布支持 Kotlin，现代 Android 开发中 Kotlin 已经是主流语言；在服务端、桌面、多平台共享代码、脚本和构建配置中也能看到 Kotlin 的广泛使用。

学习 Kotlin 时，不要只把它理解为“语法更短的 Java”。Kotlin 的重要价值在于：它把很多工程中经常靠约定、注释和代码审查保证的事情放进了类型系统和语言机制里，例如空安全、只读集合接口、密封类型、协程结构化并发、默认不可继承等。这些设计会改变代码组织方式，也会改变你建模业务状态和处理异步任务的习惯。

Kotlin 能运行在哪里

Kotlin 不是只能写 Android。它是一门多目标语言，常见目标平台包括：

• Kotlin/JVM：编译成 JVM 字节码，可运行在 Java 虚拟机上，适合 Android、Spring Boot、Ktor、桌面工具、命令行程序等。
• Kotlin/Android：本质上属于 JVM/Android 目标，是 Android 官方推荐语言之一，常与 Jetpack、Compose、Room、ViewModel、协程等一起使用。
• Kotlin/JS：编译到 JavaScript，适合 Web 前端、Node.js 或与现有 JS 生态互操作。
• Kotlin/Native：编译为原生二进制，适合没有 JVM 的平台，例如 iOS、Linux、macOS、Windows 等。
• Kotlin Multiplatform：在 commonMain 中共享业务逻辑，在不同平台用 actual 实现平台差异。
• Kotlin/Wasm：面向 WebAssembly 的目标，适合探索浏览器或 WASI 场景下的 Kotlin 应用。

实际项目中最常见的是 Kotlin/JVM 和 Kotlin/Android。初学者建议先掌握 JVM/Android 方向，再根据需要学习 KMP、JS、Native 或 Wasm。

Kotlin 的设计目标

Kotlin 的设计目标可以概括为几个关键词：

• 务实：优先解决真实工程里的痛点，而不是追求语言理论上的极端纯粹。
• 安全：通过空安全、智能类型转换、不可变优先等机制，把一部分运行时错误提前到编译期。
• 简洁：减少样板代码，但仍保留静态类型语言的明确性。
• 可读：支持表达式语法、命名参数、数据类、密封类型、扩展函数，让代码更接近业务模型。
• 兼容：与 Java 生态高度互操作，允许渐进式迁移，而不是要求一次性重写项目。
• 多范式：同时支持面向对象、函数式风格、声明式 DSL 和异步协程模型。

Kotlin 的很多语法都围绕这些目标展开。例如，数据类解决 Java Bean 样板代码；空安全减少 NPE；扩展函数让 API 更顺手；密封类型让状态建模更严谨；协程让异步代码更接近同步写法。

Kotlin 的核心特点

1. 空安全

Kotlin 的类型系统区分可空和非空：

1
var name: String = "Alice"
2
var nickname: String? = null

String 默认不能为 null，String? 才能为 null。因此调用可空对象成员时，编译器会要求你处理空值：

1
val length = nickname?.length ?: 0

这不是简单的语法糖，而是 Kotlin 编码风格的基础。好的 Kotlin 代码通常会尽早消除不确定的 null，让核心业务逻辑尽量面对非空模型。

2. 简洁表达

Kotlin 用属性、默认参数、命名参数、表达式函数体、数据类等语法减少样板代码：

1
data class User(
2
    val id: Long,
3
    val name: String,
4
    val age: Int = 0,
5
)

这段代码会自动生成 equals()、hashCode()、toString()、copy() 和解构相关函数。相比 Java 中手写或生成 getter、setter、构造器、equals、hashCode，Kotlin 更关注数据模型本身。

3. 与 Java 互操作

Kotlin 可以调用 Java 类库，Java 也可以调用 Kotlin 代码：

1
val list = java.util.ArrayList<String>()
2
list.add("Kotlin")

这使得 Kotlin 特别适合已有 Java/JVM 项目的渐进式迁移。你可以先把测试、工具类、新业务模块或 Android 新页面改为 Kotlin，而不是一次性重写整个系统。

4. 表达力强

Kotlin 的 when、密封类型、扩展函数、作用域函数、Lambda、协程和 DSL 能让代码更贴近问题域：

1
sealed interface LoginState {
2
    data object Idle : LoginState
3
    data object Loading : LoginState
4
    data class Success(val user: User) : LoginState
5
    data class Failed(val message: String) : LoginState
6
}
7

8
fun render(state: LoginState) = when (state) {
9
    LoginState.Idle -> "等待登录"
10
    LoginState.Loading -> "登录中"
11
    is LoginState.Success -> "欢迎 ${state.user.name}"
12
    is LoginState.Failed -> state.message
13
}

这种写法比多个布尔值组合更安全，也更容易维护。

5. 默认保守

Kotlin 的类、方法和属性默认都是 final，不能被继承或重写。需要开放时必须显式加 open：

1
open class Animal {
2
    open fun speak() {
3
        println("...")
4
    }
5
}
6

7
class Dog : Animal() {
8
    override fun speak() {
9
        println("汪")
10
    }
11
}

这和 Java 默认可继承的设计不同。Kotlin 鼓励你先通过组合、接口和明确抽象来组织代码，只有确实需要继承扩展时才开放。

Kotlin 与 Java 的关系

Kotlin 和 Java 的关系非常紧密，尤其在 JVM 平台上：

• Kotlin 编译后可以生成 JVM 字节码。
• Kotlin 可以直接使用 Java 标准库、第三方 JVM 库和大部分 Java 框架。
• Java 可以调用 Kotlin 编译后的类和方法。
• Kotlin 没有 checked exception，但调用 Java API 时仍可能遇到 Java 抛出的异常。
• Java 类型进入 Kotlin 时可能成为平台类型，空安全需要调用方谨慎处理。

从 Java 转 Kotlin 时，最容易误解的地方包括：

• val 不是深度不可变，只是引用不能重新赋值。
• List<T> 是只读接口，不等于底层集合一定不可变。
• Kotlin 没有 Java 风格的 static，通常用顶层函数、顶层常量、object 或 companion object。
• Kotlin 的 == 调用结构相等，类似 Java 中的 equals()；=== 才是引用相等。
• Kotlin 的类默认不能继承，方法默认不能重写。
• Kotlin 不会在不同数字类型之间做隐式赋值转换。

如果你有 Java 基础，学习 Kotlin 的关键不是背所有语法，而是接受 Kotlin 更强调类型建模、空值边界、不可变优先和表达式风格。

Kotlin 常见适用场景：

• Android 应用开发：与 Jetpack、Compose、ViewModel、Room、协程、Flow 配合成熟。
• JVM 服务端开发：可用于 Spring Boot、Ktor、Micronaut 等框架。
• 脚本和构建逻辑：Gradle Kotlin DSL 使用 .gradle.kts 编写构建配置。
• 多平台共享业务逻辑：KMP 可在 Android、iOS、桌面、Web 等平台共享模型、网络、序列化和业务规则。
• 命令行工具和自动化脚本：适合 JVM 环境下写类型安全的小工具。
• 领域建模明显的业务系统：数据类、密封类型、不可变模型能提升可维护性。

不一定优先选择 Kotlin 的场景：

• 团队完全没有 JVM、Android 或 Kotlin 经验，且项目周期极短。
• 项目依赖的框架或工具链对 Kotlin 支持较弱。
• 对启动体积、运行时、编译链路有极端限制，且 Kotlin/Native 或 Wasm 生态无法满足。
• 只是写非常简单的一次性脚本，Shell、Python 或 Node.js 更直接。

选择语言时要看生态、团队经验、部署环境和维护周期。Kotlin 的优势在中长期维护、类型安全和 JVM/Android 生态复用上更明显。

Kotlin 的心智模型

写 Kotlin 时可以牢记几个心智模型：

• 类型先行：先把业务状态、成功失败、空值、边界条件建模清楚，再写流程代码。
• 不可变优先：优先使用 val、只读集合、数据拷贝和明确状态流转。
• 边界处理不确定性：网络、数据库、Intent、JSON、Java API 这些边界可能为空或失败，进入核心逻辑前先转换成可靠模型。
• 组合优先于继承：Kotlin 默认 final，也鼓励用接口、委托、组合表达扩展点。
• 表达式优先：if、when、try 都可以作为表达式返回值，减少临时变量和分散赋值。
• 生命周期明确：协程必须绑定清晰的作用域，例如 viewModelScope、请求作用域或应用作用域。

这些习惯会让 Kotlin 代码更短，但更重要的是更稳定、更容易推理。

版本选择

实际项目中的 Kotlin 版本应以团队 Gradle 配置、Android Gradle Plugin、Kotlin Multiplatform 插件和依赖兼容性为准。新项目建议先查看官方发布页，再结合以下因素决定：

• IDE 是否支持该 Kotlin 版本。
• Gradle、Android Gradle Plugin、Compose Compiler、KSP、kotlinx.coroutines、kotlinx.serialization 等插件和依赖是否兼容。
• CI/CD 构建环境是否已经准备好对应 JDK 和 Gradle 版本。
• 团队是否需要使用新版本语言特性。
• 是否存在历史模块、注解处理器、Java 互操作或三方库兼容风险。

对于学习笔记，重点不在背某个版本号，而是掌握稳定通用的语言机制。具体项目升级时再阅读官方发布说明和迁移指南。

2. 环境与项目结构#

学习 Kotlin 不只是安装一个编译器。实际项目通常由 JDK、IDE、Gradle、Kotlin 插件、测试框架和平台插件共同组成。环境搭得清楚，后面学习语法、协程、Android 或服务端框架时会少很多无关问题。

开发环境组成

常见 Kotlin 开发环境包括：

• JDK：JVM、Android、Gradle 都依赖 Java 工具链。新项目通常选择当前 Gradle、Android Gradle Plugin 和部署平台支持的 LTS 版本。
• IDE：IntelliJ IDEA 适合 JVM、后端、脚本、KMP；Android Studio 适合 Android 和 Compose。
• Gradle：现代 Kotlin 项目的主流构建工具，推荐使用 Gradle Wrapper 固定团队构建版本。
• Kotlin Gradle Plugin：负责把 Kotlin 源码编译到目标平台。
• 平台插件：例如 application、com.android.application、com.android.library、kotlin("multiplatform")。
• 测试工具：常见有 kotlin.test、JUnit、MockK、Turbine、Robolectric、Android Instrumentation Test。

不同开发方向的推荐组合：

JDK 与版本选择

JDK 是 Kotlin/JVM 项目的基础。选择版本时不要只看“越新越好”，而要看兼容矩阵：

• Gradle 是否支持该 JDK。
• Android Gradle Plugin 是否支持该 JDK。
• 部署环境是否支持对应 class file 版本。
• 依赖库和框架是否声明了最低或最高 JDK 要求。
• CI 环境是否已安装相同版本。

Gradle 中可以使用 toolchain 固定编译 JDK：

1
kotlin {
2
    jvmToolchain(17)
3
}

这表示 Kotlin 编译任务使用 Java 17 工具链。Android 项目也常见类似配置：

1
android {
2
    compileOptions {
3
        sourceCompatibility = JavaVersion.VERSION_17
4
        targetCompatibility = JavaVersion.VERSION_17
5
    }
6
}
7

8
kotlin {
9
    jvmToolchain(17)
10
}

注意：jvmToolchain 控制编译使用的 JDK，不等于应用运行时一定就是这个 JDK。服务端部署、Android 设备运行时、Docker 镜像里的 JRE 都需要单独确认。

IDE 选择

IntelliJ IDEA

适合：

• Kotlin/JVM
• Spring Boot、Ktor 等服务端项目
• Kotlin Multiplatform
• Kotlin 脚本
• Gradle 插件或命令行工具开发

Android Studio

适合：

• Android App
• Android Library
• Jetpack Compose
• Android 测试、模拟器、布局预览、Profiler

IDE 的 Kotlin 插件通常与 IDE 版本绑定。项目中 Kotlin 插件版本、IDE 内置支持版本、Compose Compiler/KSP 等工具版本不一致时，可能出现代码能编译但 IDE 报红，或 IDE 正常但 CI 失败。遇到这类问题先检查版本兼容性。

Gradle Wrapper

团队项目应优先使用 Gradle Wrapper，而不是依赖每个人机器上全局安装的 Gradle：

1
gradlew
2
gradlew.bat
3
gradle/
4
  wrapper/
5
    gradle-wrapper.jar
6
    gradle-wrapper.properties

Windows 下常用：

1
.\gradlew.bat build

macOS/Linux 下常用：

1
./gradlew build

Wrapper 的好处：

• 固定 Gradle 版本，减少“我本地能跑”的环境差异。
• CI 和本地使用同一构建入口。
• 新成员无需手动安装 Gradle。

常用命令：

1
./gradlew tasks          # 查看任务
2
./gradlew build          # 编译、测试、打包
3
./gradlew test           # 运行 JVM 单元测试
4
./gradlew clean          # 清理构建产物
5
./gradlew run            # application 项目运行 main
6
./gradlew dependencies   # 查看依赖树

Android 常用命令：

1
./gradlew assembleDebug       # 构建 debug apk
2
./gradlew testDebugUnitTest   # 运行 debug 单元测试
3
./gradlew connectedDebugAndroidTest # 运行设备/模拟器测试

Gradle Kotlin DSL

Kotlin 项目推荐使用 Gradle Kotlin DSL，也就是 .gradle.kts 文件。它比 Groovy DSL 有更好的类型提示和重构支持。

根目录常见文件：

1
settings.gradle.kts
2
build.gradle.kts
3
gradle.properties
4
gradle/
5
  libs.versions.toml

settings.gradle.kts 定义项目名、插件仓库、依赖仓库和模块：

1
pluginManagement {
2
    repositories {
3
        google()
4
        mavenCentral()
5
        gradlePluginPortal()
6
    }
7
}
8

9
dependencyResolutionManagement {
10
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
11
    repositories {
12
        google()
13
        mavenCentral()
14
    }
15
}
16

17
rootProject.name = "KotlinStudy"
18
include(":app")
19
include(":core")

根 build.gradle.kts 常用于声明插件版本但不立即应用：

1
plugins {
2
    kotlin("jvm") version "<kotlin-version>" apply false
3
    kotlin("android") version "<kotlin-version>" apply false
4
    id("com.android.application") version "<agp-version>" apply false
5
    id("com.android.library") version "<agp-version>" apply false
6
}

模块自己的 build.gradle.kts 再应用需要的插件：

1
plugins {
2
    kotlin("jvm")
3
}

版本目录

现代 Gradle 项目常用 Version Catalog 管理依赖版本，文件通常是 gradle/libs.versions.toml：

1
[versions]
2
kotlin = "<kotlin-version>"
3
coroutines = "<coroutines-version>"
4
junit = "5.10.2"
5

6
[libraries]
7
kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test" }
8
coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
9
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
10

11
[plugins]
12
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }

使用方式：

1
plugins {
2
    alias(libs.plugins.kotlin.jvm)
3
}
4

5
dependencies {
6
    implementation(libs.coroutines.core)
7
    testImplementation(libs.kotlin.test)
8
    testImplementation(libs.junit.jupiter)
9
}

优点：

• 所有版本集中管理。
• 多模块项目依赖一致。
• 升级时更容易检查影响范围。

Gradle JVM 项目示例

一个最小 Kotlin/JVM 应用模块的 build.gradle.kts：

1
plugins {
2
    kotlin("jvm") version "<kotlin-version>"
3
    application
4
}
5

6
repositories {
7
    mavenCentral()
8
}
9

10
dependencies {
11
    testImplementation(kotlin("test"))
12
}
13

14
application {
15
    mainClass.set("MainKt")
16
}

对应目录结构：

1
src/
2
  main/
3
    kotlin/
4
      Main.kt
5
  test/
6
    kotlin/
7
      MainTest.kt

Main.kt：

1
fun main() {
2
    println("Hello, Kotlin")
3
}

如果 main 函数放在包中：

1
package com.example
2

3
fun main() {
4
    println("Hello, Kotlin")
5
}

则 mainClass 需要写成：

1
application {
2
    mainClass.set("com.example.MainKt")
3
}

MainKt 是 Kotlin 顶层函数在 JVM 上编译后的默认文件类名。也可以通过 @file:JvmName 改变生成名。

JVM 库项目结构

如果项目产物是库，而不是可执行程序，可以不使用 application 插件：

1
plugins {
2
    kotlin("jvm")
3
}
4

5
repositories {
6
    mavenCentral()
7
}
8

9
dependencies {
10
    api("org.example:public-api:1.0.0")
11
    implementation("org.example:internal-lib:1.0.0")
12
    testImplementation(kotlin("test"))
13
}

api 和 implementation 的区别：

• api：依赖会暴露给使用该库的下游模块。
• implementation：依赖只在当前模块内部使用，不暴露给下游。

只有使用 java-library 插件时，api 配置才可用：

1
plugins {
2
    `java-library`
3
    kotlin("jvm")
4
}

建议：

• 公共类型出现在方法签名里时，用 api。
• 只在内部实现中使用时，用 implementation。

Android 项目结构

Android Kotlin 项目通常包含：

1
settings.gradle.kts
2
build.gradle.kts
3
app/
4
  build.gradle.kts
5
  src/
6
    main/
7
      AndroidManifest.xml
8
      java/
9
      kotlin/
10
      res/
11
    test/
12
      kotlin/
13
    androidTest/
14
      kotlin/

app/build.gradle.kts 示例：

1
plugins {
2
    id("com.android.application")
3
    kotlin("android")
4
}
5

6
android {
7
    namespace = "com.example.app"
8
    compileSdk = 35
9

10
    defaultConfig {
11
        applicationId = "com.example.app"
12
        minSdk = 23
13
        targetSdk = 35
14
        versionCode = 1
15
        versionName = "1.0"
16
    }
17

18
    compileOptions {
19
        sourceCompatibility = JavaVersion.VERSION_17
20
        targetCompatibility = JavaVersion.VERSION_17
21
    }
22
}
23

24
kotlin {
25
    jvmToolchain(17)
26
}
27

28
dependencies {
29
    implementation("androidx.core:core-ktx:<version>")
30
    testImplementation(kotlin("test"))
31
}

Android 源码目录说明：

• src/main：正式代码和资源。
• src/test：本地 JVM 单元测试，不需要设备。
• src/androidTest：运行在设备或模拟器上的测试。
• res：布局、图片、字符串、主题等 Android 资源。
• AndroidManifest.xml：声明组件、权限和应用基础配置。

很多 Android 项目会同时存在 java/ 和 kotlin/ 目录。Kotlin 文件可以放在 java/ 下，也能正常编译；但为了清晰，新项目通常使用 kotlin/。

Kotlin Multiplatform 项目结构

KMP 项目核心是 source set。典型结构：

1
shared/
2
  build.gradle.kts
3
  src/
4
    commonMain/
5
      kotlin/
6
    commonTest/
7
      kotlin/
8
    androidMain/
9
      kotlin/
10
    androidUnitTest/
11
      kotlin/
12
    iosMain/
13
      kotlin/
14
    iosTest/
15
      kotlin/

shared/build.gradle.kts 简化示例：

1
plugins {
2
    kotlin("multiplatform")
3
    id("com.android.library")
4
}
5

6
kotlin {
7
    androidTarget()
8

9
    iosX64()
10
    iosArm64()
11
    iosSimulatorArm64()
12

13
    sourceSets {
14
        commonMain.dependencies {
15
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:<version>")
16
        }
17

18
        commonTest.dependencies {
19
            implementation(kotlin("test"))
20
        }
21
    }
22
}
23

24
android {
25
    namespace = "com.example.shared"
26
    compileSdk = 35
27
}

KMP 的基本规则：

• commonMain 只能使用公共 API，不能直接调用 Android、iOS 或 JVM 专属 API。
• 平台差异通过 expect / actual、接口注入或分平台 source set 处理。
• 不要为了“共享”强行把 UI、生命周期、权限等平台强相关逻辑塞进 common 层。

Kotlin 脚本

Kotlin 脚本文件通常使用 .kts 后缀。常见场景：

• Gradle Kotlin DSL：build.gradle.kts、settings.gradle.kts。
• 简单自动化脚本。
• 一次性数据处理脚本。

示例：

1
#!/usr/bin/env kotlin
2

3
println("Hello from Kotlin script")

脚本适合简单自动化。如果脚本开始出现复杂依赖、测试需求、多人维护，建议改成标准 Gradle 项目。

包声明与导入

1
package com.example.app
2

3
import kotlin.math.max
4
import java.time.LocalDate

Kotlin 文件的包名不要求和目录完全一致，但 JVM/Android 项目中建议保持一致，便于维护。

常见默认导入包括：

• kotlin.*
• kotlin.annotation.*
• kotlin.collections.*
• kotlin.comparisons.*
• kotlin.io.*
• kotlin.ranges.*
• kotlin.sequences.*
• kotlin.text.*
• JVM 平台还会默认导入部分 java.lang.*、kotlin.jvm.*

导入可以重命名，解决命名冲突：

1
import com.example.domain.User as DomainUser
2
import com.example.dto.User as UserDto

不推荐滥用星号导入。团队可以通过 IDE formatter 或 ktlint 统一导入风格。

源码集与测试目录

JVM 项目常见源码集：

1
src/main/kotlin      # 生产 Kotlin 代码
2
src/main/java        # 生产 Java 代码
3
src/main/resources   # 资源文件
4
src/test/kotlin      # 测试 Kotlin 代码
5
src/test/java        # 测试 Java 代码
6
src/test/resources   # 测试资源

测试示例：

1
import kotlin.test.Test
2
import kotlin.test.assertEquals
3

4
class CalculatorTest {
5
    @Test
6
    fun addsTwoNumbers() {
7
        assertEquals(3, 1 + 2)
8
    }
9
}

Android 项目还会区分：

• test：本地单元测试。
• androidTest：设备/模拟器测试。
• testFixtures：测试夹具，适合多模块共享测试辅助代码。

多模块项目建议

随着项目变大，可以拆成多个模块：

1
app/
2
core/
3
  common/
4
  database/
5
  network/
6
feature/
7
  login/
8
  profile/

常见拆分方式：

• 按层拆分：domain、data、presentation。
• 按功能拆分：feature-login、feature-profile。
• 按能力拆分：core-network、core-database、core-ui。
• 混合拆分：大型 Android 项目常用 feature + core 组合。

拆模块不是越多越好。模块会增加 Gradle 配置、依赖边界和构建复杂度。适合拆模块的信号：

• 编译时间明显变长，需要增量构建收益。
• 某些代码边界稳定，适合作为公共能力复用。
• 团队多人并行开发，功能边界清晰。
• 需要限制依赖方向，避免业务互相引用。

不适合过早拆分的情况：

• 项目还很小，业务边界不稳定。
• 只是为了看起来“架构完整”。
• 团队没有维护多模块构建的经验。

常用 gradle.properties 配置

gradle.properties 可以放 Gradle、Kotlin 和 Android 构建配置：

1
org.gradle.jvmargs=-Xmx4g -Dfile.encoding=UTF-8
2
org.gradle.parallel=true
3
org.gradle.caching=true
4
kotlin.code.style=official

Android 项目常见：

1
android.useAndroidX=true
2
android.nonTransitiveRClass=true

注意：

• 不要盲目增大 org.gradle.jvmargs，内存过大可能影响 CI 并发。
• parallel 和 caching 是否有效取决于项目结构和任务配置。
• 团队应统一 kotlin.code.style=official，减少格式差异。

编译、运行与测试

JVM 应用：

1
./gradlew run

JVM 测试：

1
./gradlew test

构建所有模块：

1
./gradlew build

查看某个任务详情：

1
./gradlew help --task test

刷新依赖缓存：

1
./gradlew build --refresh-dependencies

Android Debug 构建：

1
./gradlew :app:assembleDebug

指定模块运行测试：

1
./gradlew :core:test

工程约定建议

新 Kotlin 项目建议尽早统一这些约定：

• 使用 Gradle Wrapper。
• 使用 Kotlin DSL：.gradle.kts。
• 使用 Version Catalog 管理版本。
• 源码 UTF-8 编码。
• 包名与目录结构保持一致。
• 公共 API 谨慎使用 api，内部依赖优先 implementation。
• 生产代码优先 src/main/kotlin，测试代码放 src/test/kotlin。
• 引入 ktlint、detekt 或 IDE formatter 统一风格。
• CI 至少运行 build 或核心模块测试。
• README 写清楚 JDK、Gradle、Android SDK、运行命令和测试命令。

3. 基础语法#

本章只讨论 Kotlin 的“读写代码入口”：一个 .kt 文件怎样组织、程序从哪里开始执行、变量怎样声明、类型怎样写、表达式怎样求值、注释和命名怎样约定。更深入的类型、空安全、控制流、函数、类和集合会在后续章节展开。

1
package com.example.demo
2

3
import kotlin.math.max
4

5
const val APP_NAME = "KotlinDemo"
6

7
fun main() {
8
    val left = 10
9
    val right = 20
10
    println("max = ${max(left, right)}")
11
}
12

13
class User(val name: String)

1
fun main() {
2
    println("Hello, Kotlin")
3
}

1
fun main(args: Array<String>) {
2
    println(args.joinToString())
3
}

1
package com.example.user

1
src/main/kotlin/com/example/user/User.kt

1
import kotlin.math.max

1
import java.util.Date as JavaDate
2
import java.sql.Date as SqlDate

1
val userName = "Alice"
2
val count2 = 2

1
fun `should return user when id exists`() {
2
    // ...
3
}

1
class, object, interface, fun, val, var, if, else, when, for, while,
2
do, return, break, continue, try, catch, finally, throw, this, super,
3
is, in, as, typealias

1
by, get, set, constructor, init, where, field, property, suspend,
2
actual, expect, value

1
val name = "Kotlin"     // 只读引用，初始化后不能重新赋值
2
var count = 1           // 可变引用，可以重新赋值
3
count += 1

1
val users = mutableListOf("Alice")
2
users.add("Bob")        // 可以修改集合内容
3
// users = mutableListOf("Tom") // 编译错误

1
class UserStore {
2
    private val mutableUsers = mutableListOf<String>()
3

4
    val users: List<String>
5
        get() = mutableUsers.toList()
6

7
    fun addUser(name: String) {
8
        mutableUsers.add(name)
9
    }
10
}

1
val input = readln()
2
var retryCount = 0
3

4
retryCount += 1

1
val age = 18            // Int
2
val price = 19.9        // Double
3
val enabled = true      // Boolean

1
val id: Long
2
id = 1001L

1
val name: String = "Alice"
2
var score: Int = 95

1
fun greet(name: String) {
2
    println("Hello, $name")
3
}

1
fun loadUser(id: Long): User {
2
    return repository.getById(id)
3
}

1
val result: String
2

3
if (success) {
4
    result = "成功"
5
} else {
6
    result = "失败"
7
}
8

9
println(result)

1
val message: String
2

3
if (success) {
4
    message = "OK"
5
}
6

7
// println(message) // 编译错误：message 可能未初始化

1
const val APP_NAME = "Demo"
2

3
fun printAppName() {
4
    println(APP_NAME)
5
}

1
fun normalizeName(name: String): String {
2
    return name.trim().lowercase()
3
}

1
val defaultTimeoutMillis = 3_000
2

3
// 不推荐：全局可变状态难测试，也容易产生并发问题
4
var currentUserId: Long? = null

1
const val MAX_PAGE_SIZE = 100
2

3
val startedAt = System.currentTimeMillis() // 不是编译期常量，不能用 const

1
// 单行注释
2

3
/*
4
 * 多行注释
5
 * Kotlin 的块注释可以嵌套。
6
 */
7

8
/**
9
 * KDoc 文档注释。
10
 */

1
/**
2
 * 根据用户 id 查询用户。
3
 *
4
 * @param id 用户唯一标识。
5
 * @return 找到的用户；不存在时返回 null。
6
 */
7
fun findUser(id: Long): User? {
8
    return null
9
}

1
val level = if (score >= 60) "PASS" else "FAIL"

1
val label = when (statusCode) {
2
    200 -> "OK"
3
    404 -> "Not Found"
4
    else -> "Unknown"
5
}

1
val number = try {
2
    input.toInt()
3
} catch (e: NumberFormatException) {
4
    0
5
}

1
fun printUser(active: Boolean) {
2
    if (active) {
3
        val message = "用户可用"
4
        println(message)
5
    }
6

7
    // println(message) // 编译错误：message 不在作用域内
8
}

1
val message = if (score >= 60) {
2
    println("calculated")
3
    "合格"
4
} else {
5
    "不合格"
6
}

1
val name = "Alice"
2
println(name)

1
val a = 1; val b = 2

1
val names = users
2
    .filter { it.active }
3
    .map { it.name }
4
    .sorted()

1
print("Hello")
2
println("Kotlin")

1
val line = readln()

1
val line: String? = readlnOrNull()

1
val age = readlnOrNull()?.toIntOrNull() ?: 0

1
val name = "Alice"
2
val age = 20
3

4
println("name = $name")
5
println("next age = ${age + 1}")

1
val item = "book"
2
println("${item}_count")

1
val a = 10
2
val b = 3
3

4
println(a + b)
5
println(a - b)
6
println(a * b)
7
println(a / b) // Int / Int 结果仍是 Int
8
println(a % b)

1
var count = 0
2
count += 1
3
count *= 2

1
println(a > b)
2
println(a <= b)
3
println(a == b)
4
println(a != b)

1
val valid = age in 0..150
2
val enabled = valid && userActive
3
val hidden = !enabled

1
if (user != null && user.isActive) {
2
    println(user.name)
3
}

1
data class User(val name: String)
2

3
val a = User("Alice")
4
val b = User("Alice")
5

6
println(a == b)   // true，内容相等
7
println(a === b)  // false，不是同一个对象

1
fun printLength(value: Any) {
2
    if (value is String) {
3
        println(value.length) // 智能转换为 String
4
    }
5
}

1
if (value !is String) {
2
    return
3
}
4

5
println(value.length)

1
val text = value as String

1
val text = value as? String

1
fun formatUserName(firstName: String, lastName: String): String {
2
    return "$firstName $lastName".trim()
3
}

1
fun isAdult(age: Int): Boolean = age >= 18

1
val activeNames = users
2
    .filter { user -> user.active }
3
    .map { user -> user.name }
4
    .sorted()

1
val list = mutableListOf("a")
2
list.add("b") // 可以修改内容

1
val age = readlnOrNull()!!.toInt()

1
val age = readlnOrNull()?.toIntOrNull() ?: 0

1
fun getUsers() = repository.loadUsers()

1
fun getUsers(): List<User> = repository.loadUsers()

1
var currentToken: String? = null

1
class SessionStore {
2
    var currentToken: String? = null
3
        private set
4

5
    fun updateToken(token: String?) {
6
        currentToken = token
7
    }
8
}

1
val result = if (a > b) if (c > d) "x" else "y" else "z"

1
val result = if (a > b) {
2
    if (c > d) "x" else "y"
3
} else {
4
    "z"
5
}

4. 基本类型、字符串与数组#

Kotlin 是静态类型语言。变量、表达式、函数参数和返回值都有明确类型，只是很多地方编译器可以自动推断。理解基本类型很重要，因为后续的空安全、泛型、集合、协程返回值和 Java 互操作都建立在类型系统之上。

Kotlin 的基本类型在源码层面表现为对象类型，例如 Int、Boolean、String 都有成员函数；但在 JVM 等平台上，编译器会尽量把它们优化为高效的原生表示。你通常不需要手动区分“基本类型”和“包装类型”，但在泛型、可空类型、数组和 Java 互操作中仍然需要理解装箱行为。

1
val a = 100            // Int
2
val b = 3_000_000_000  // Long

1
val price = 12.5       // Double
2
val ratio = 0.75f      // Float

1
val byteValue: Byte = 1
2
val shortValue: Short = 2
3
val longValue: Long = 3

1
val decimal = 123
2
val longNumber = 123L
3
val hex = 0x0F
4
val binary = 0b00001011
5
val readable = 1_000_000
6
val doubleValue = 123.5
7
val floatValue = 123.5f

1
println(Int.MIN_VALUE)
2
println(Int.MAX_VALUE)
3
println(Long.MAX_VALUE)

1
val max = Int.MAX_VALUE
2
println(max + 1) // 溢出为 Int.MIN_VALUE

1
import java.math.BigInteger
2

3
val big = BigInteger("999999999999999999999999999999")
4
println(big + BigInteger.ONE)

1
import java.math.BigDecimal
2

3
val price = BigDecimal("19.99")
4
val count = BigDecimal("3")
5
println(price * count)

1
val x: Int = 10
2
val y: Long = x.toLong()

1
toByte()
2
toShort()
3
toInt()
4
toLong()
5
toFloat()
6
toDouble()
7
toChar()

1
val x = 300
2
println(x.toByte()) // 44，超出 Byte 范围后截断
3

4
val y = 3.99
5
println(y.toInt())  // 3，向零截断

1
val a = 1
2
val b = 1L
3
println(a.toLong() == b)

1
val intValue = 10
2
val longValue = 20L
3

4
println(intValue.toLong() < longValue)

1
println(5 / 2)      // 2
2
println(5 / 2.0)    // 2.5

1
val average = total.toDouble() / count

1
println(7 % 3)      // 1
2
println(-7 % 3)     // -1

1
fun positiveMod(value: Int, modulus: Int): Int {
2
    return ((value % modulus) + modulus) % modulus
3
}

1
val flags: UInt = 0b1010u
2
val max = UInt.MAX_VALUE
3
println(max)

1
val bytes: UByteArray = ubyteArrayOf(0u, 255u)

1
val flags = 0b0010
2
val shifted = flags shl 1
3
val hasFlag = (flags and 0b0010) != 0

1
const val READ = 1      // 0001
2
const val WRITE = 1 shl 1 // 0010
3
const val EXECUTE = 1 shl 2 // 0100
4

5
val permission = READ or WRITE
6

7
val canRead = (permission and READ) != 0
8
val canExecute = (permission and EXECUTE) != 0
9

10
println(canRead)    // true
11
println(canExecute) // false

1
val ok: Boolean = true
2
val failed = false

1
val enabled = ok && !failed
2
val visible = ok || failed

1
fun isValidName(name: String?): Boolean {
2
    return name != null && name.length >= 2
3
}

1
val isLoading = true
2
val hasPermission = false
3
val canRetry = true

1
val flag = true
2
val status = false

1
val letter: Char = 'A'

1
val digit = '7'.digitToInt()   // 7

1
val digit = '7'.code - '0'.code

1
println('a'.uppercaseChar())   // A
2
println('A'.lowercaseChar())   // a
3
println('7'.isDigit())         // true
4
println('K'.isLetter())        // true
5
println(' '.isWhitespace())    // true

1
for (c in 'a'..'z') {
2
    print(c)
3
}

1
val heart = '\u2665'
2
println(heart)

1
val language = "Kotlin"
2
println(language[0]) // K

1
for (char in language) {
2
    println(char)
3
}

1
val text = " Kotlin "
2

3
println(text.length)
4
println(text.trim())
5
println(text.lowercase())
6
println(text.uppercase())
7
println(text.startsWith(" K"))
8
println(text.contains("lin"))
9
println(text.substring(1, 4))

1
val original = "Kotlin"
2
val changed = original.replace("K", "J")
3

4
println(original) // Kotlin
5
println(changed)  // Jotlin

1
val report = buildString {
2
    appendLine("Users")
3
    appendLine("-----")
4
    for (user in users) {
5
        appendLine(user.name)
6
    }
7
}

1
val name = "Alice"
2
val age = 20
3
println("$name is $age years old")
4
println("next year: ${age + 1}")

1
val fileName = "report"
2
println("${fileName}.txt")

1
println("upper = ${name.uppercase()}")

1
val line = "first\nsecond"
2
val quote = "He said \"Hello\""
3
val path = "C:\\Users\\Alice"

1
val sql = """
2
    SELECT id, name
3
    FROM users
4
    WHERE active = 1
5
""".trimIndent()

1
val json = """
2
    |{
3
    |  "name": "Alice",
4
    |  "age": 20
5
    |}
6
""".trimMargin()