moai-lang-kotlin

快速参考（30 秒）

Kotlin 2.0+ 专家级支持——K2 编译器、协程、Ktor、Compose Multiplatform，并集成 Context7。

自动触发条件：Kotlin 文件（.kt、.kts）、Gradle Kotlin DSL（build.gradle.kts、settings.gradle.kts）

核心能力：

• Kotlin 2.0：K2 编译器、协程、Flow、密封类、值类
• Ktor 3.0：异步 HTTP 服务端/客户端、WebSocket、JWT 身份验证
• Exposed 0.55：支持协程的 Kotlin SQL 框架
• Spring Boot（Kotlin）：符合 Kotlin 惯用风格并支持 WebFlux 的 Spring
• Compose Multiplatform：桌面、iOS、Web、Android UI
• 测试：用于 Flow 测试的 JUnit 5、MockK、Kotest、Turbine

---

实现指南（5 分钟）

Kotlin 2.0 功能

协程和 Flow：使用 coroutineScope 和 async 执行并行操作。使用 async 创建延迟值，然后对每个值调用 await 以获取结果。将结果合并到数据类中。对于响应式流，在 flow 代码块中创建 emit 调用，并将其放在 while 循环内。使用 delay 设置时间间隔，并使用 flowOn 指定调度器。

密封类和值类：定义带有泛型类型参数的密封接口。为成功情况创建数据类实现，为无状态情况（如 Loading）创建 data object。使用 @JvmInline 注解创建封装原始类型的值类。添加包含 require 的 init 代码块进行验证。

Ktor 3.0 服务端

应用设置：调用 embeddedServer，并传入 Netty、端口和主机参数。在 lambda 中，调用 Koin、安全、路由和内容协商配置函数。调用 start，并将 wait 设为 true。

配置 Koin 时，安装 Koin 插件，并使用 single 声明定义单例模块。配置安全时，安装 Authentication 插件，并使用 realm、verifier 和 validate 回调配置 JWT。配置内容协商时，安装 ContentNegotiation，并配置 json。

带身份验证的路由：在 Application 上定义路由函数。在 routing 代码块中，使用 route 指定路径前缀。使用 post 创建未经身份验证的端点，并通过 call.receive 接收请求体。对受保护的路由使用带有 verifier 名称的 authenticate 代码块。在 route 代码块内，使用 call.parameters 获取路径/查询参数，并定义 get 端点。使用 call.respond 返回状态码和响应体。

Exposed SQL 框架

表和实体：定义继承自 LongIdTable 的对象，并指定表名。使用 varchar、enumerationByName 和 timestamp 函数声明列。使用 uniqueIndex() 和 defaultExpression 设置默认值。

创建继承自 LongEntity 的实体类，并创建继承自 LongEntityClass 的 companion object。使用 by 语法和表列引用声明属性。创建 toModel 函数，将实体映射为领域模型。

支持协程的仓库：创建一个接收 Database 参数的仓库实现。实现 suspend 函数，并通过 dbQuery 辅助函数封装 Exposed 操作。使用 findById 查找单个实体。使用 Entity.new 插入数据。使用 IO 调度器和 newSuspendedTransaction 定义私有 dbQuery 函数。

使用 Kotlin 的 Spring Boot

WebFlux 控制器：使用 @RestController 和 @RequestMapping 注解类。使用 @GetMapping 和 @PostMapping 为端点创建 suspend 函数。对于集合，返回使用 map 转换实体的 Flow。返回带有状态码的 ResponseEntity。使用 @Valid 验证请求。

---

高级模式

Compose Multiplatform

共享 UI 组件：创建一个接收 ViewModel 和回调参数的 @Composable 函数。使用 collectAsState 将 uiState 收集为状态。使用 when 表达式处理密封状态，分别为 Loading、Success 和 Error 显示不同的可组合项。

对于列表项，创建带有 Modifier.fillMaxWidth 和 clickable 的 Card 可组合项。使用带有内边距的 Row、通过 CircleShape 裁剪的 AsyncImage 头像，以及用于文本内容的 Column，并使用 MaterialTheme.typography 设置样式。

使用 MockK 进行测试

创建测试类，并使用 mockk 模拟依赖项。在声明时使用模拟对象初始化服务。协程测试使用 runTest 和 @Test。异步模拟使用 coEvery 和 coAnswers，并添加延迟。使用 assertThat 进行断言。测试 Flow 时，使用 toList 收集发出的值，并断言其数量和内容。

Gradle 构建配置

在 plugins 块中使用带版本字符串的 kotlin("jvm") 和 kotlin("plugin.serialization")。添加 ktor.plugin 的 id。在 kotlin 块中配置 jvmToolchain。在 dependencies 块中添加 Ktor 服务端模块、kotlinx 协程、Exposed 模块和 PostgreSQL 驱动程序。添加 mockk、coroutines-test 和 turbine 作为测试依赖项。

---

Context7 集成

最新文档的库映射：

• /ktorio/ktor - Ktor 3.0 服务端／客户端文档
• /jetbrains/exposed - Exposed SQL 框架
• /JetBrains/kotlin - Kotlin 2.0 语言参考
• /Kotlin/kotlinx.coroutines - 协程库
• /jetbrains/compose-multiplatform - Compose Multiplatform
• /arrow-kt/arrow - Arrow 函数式编程

用法：调用 mcp__context7__get_library_docs，并提供 context7CompatibleLibraryID、用于指定领域的 topic 字符串，以及用于设置响应大小的 tokens 参数。

---

何时使用 Kotlin

在以下情况使用 Kotlin：

• 开发 Android 应用（官方语言）
• 使用 Ktor 构建现代服务端应用
• 偏好简洁、富有表现力的语法
• 使用协程和 Flow 构建响应式服务
• 创建多平台应用（iOS、桌面端、Web）
• 需要与 Java 完全互操作

考虑替代方案的情况：

• 需要尽量少改动的旧版 Java 代码库
• 大数据流水线（优先考虑搭配 Spark 使用的 Scala）

---

配合使用效果良好

• moai-lang-java - Java 互操作和 Spring Boot 模式
• moai-domain-backend - REST API、GraphQL、微服务架构
• moai-domain-database - JPA、Exposed、R2DBC 模式
• moai-quality-testing - JUnit 5、MockK、TestContainers 集成
• moai-infra-docker - JVM 容器优化

---

故障排查

K2 编译器：在 gradle.properties 中添加 kotlin.experimental.tryK2=true。清除 .gradle 目录以执行完整重建。

协程：避免在挂起上下文中使用 runBlocking。对阻塞操作使用 Dispatchers.IO。

Ktor：确保已安装 ContentNegotiation。检查 JWT 验证器配置。验证路由层级。

Exposed：确保所有数据库操作都在事务上下文中运行。注意在事务之外进行延迟实体加载的情况。

---

高级文档

如需完整的参考资料：

• reference.md - 完整的生态系统、Context7 映射、测试模式和性能
• examples.md - 可用于生产环境的代码示例、Ktor、Compose、Android 模式

---

最后更新：2026-01-11 状态：可用于生产环境（v1.1.0）