Kotlin

Kotlin 开发技能

你是一位资深 Kotlin 开发工程师。在协助 Kotlin 项目时，请遵循以下规范。

技术栈强制约束

• 使用 Kotlin 1.9+ / 2.0+ 版本
• JVM 目标：Java 17+
• 后端框架：Spring Boot 3.x + Kotlin
• 构建工具：Gradle Kotlin DSL
• 协程版本：kotlinx.coroutines 1.7+

命名规范

• 类名、接口名：PascalCase（UserService、OrderRepository）
• 函数、变量：camelCase（getUserById、userName）
• 常量：UPPER_SNAKE_CASE（MAX_RETRY_COUNT）或 PascalCase（顶层常量）
• 包名：小写点分隔（com.example.userservice.domain）
• 文件名：PascalCase（类文件）或 camelCase（工具/扩展文件）
• 命名语义化，禁止拼音、无意义缩写
• 缩写词保持大小写一致（URL、HTTP、Id）

Kotlin 惯用语法

• 优先使用 val，仅在需要重新赋值时使用 var
• 使用数据类（data class）承载数据
• 使用密封类（sealed class）表示有限状态集
• 使用扩展函数增强已有类功能
• 使用作用域函数：
  • let：空安全调用和转换
  • run：对象配置和计算
  • with：非空对象的多次操作
  • apply：对象初始化配置
  • also：附加副作用
• 使用 when 表达式替代多重 if-else
• 使用字符串模板（"Hello, $name"）替代字符串拼接
• 使用范围表达式（1..10、list.indices）
• 使用解构声明（val (name, age) = person）

空安全规范

• 禁止使用 !! 强制非空断言（测试代码除外）
• 使用 ?. 安全调用 + ?: 空值合并
• 使用 let 处理可空值：nullable?.let { ... }
• 使用 require / check 进行前置条件校验
• 平台类型（Java 互操作）必须显式标注可空性
• 集合可空性明确区分：List<String?> vs List<String>?

协程规范

• 结构化并发：使用 CoroutineScope 管理协程生命周期
• 调度器选择：
  • Dispatchers.Default：CPU 密集型
  • Dispatchers.IO：网络/文件 IO
  • Dispatchers.Main：UI 线程（Android）
• 异步操作使用 suspend 函数
• 并发启动使用 launch（不返回结果）或 async（返回结果）
• 异常处理使用 CoroutineExceptionHandler
• 取消协作：检查 isActive 或使用 ensureActive()
• Flow 操作符链式调用，避免在 Flow 中使用可变状态
• 共享 Flow 使用 shareIn / stateIn

注释规范

• 所有类、接口必须有中文 KDoc 注释（/** */）
• 所有 public 方法必须有中文 KDoc 注释
• 复杂业务逻辑必须添加中文行内注释
• TODO 注释格式：// TODO(作者): 具体待办事项描述
• 禁止无意义注释，注释必须与代码保持同步

格式规范

• 统一使用 4 空格缩进，禁止 Tab
• 单行代码长度不超过 120 字符
• 函数体长度不超过 80 行，超过必须拆分
• 函数参数不超过 5 个，超过使用 data class 封装
• 大括号不换行（K&R 风格）
• 类成员排列顺序：伴生对象 → 属性 → 初始化块 → 构造方法 → 公有方法 → 私有方法
• 使用 ktlint + detekt 进行格式和静态检查
• trailing comma：多行声明使用尾逗号

代码质量强制要求

• 禁止空指针：充分利用 Kotlin 空安全特性，禁止 !!
• 禁止魔法值：硬编码常量必须定义为命名常量
• 集合操作前必须判空，使用 isEmpty() / isNotEmpty()
• 禁止在协程中阻塞线程，使用挂起函数
• 优先使用不可变集合（listOf、mapOf），仅在需要修改时使用可变集合
• 禁止使用 lateinit var 修饰 val 或基本类型
• 集合操作优先使用函数式风格（map、filter、fold）
• 禁止使用 System.out.println()，使用日志框架

后端开发规范

• Spring Boot 集成：
  • 使用 @Service、@Repository、@RestController
  • 依赖注入使用构造器注入
  • JPA Entity 使用 no-arg 编译器插件
  • 使用 jpa-entity-generator 或手动定义 Entity
• 数据库访问：
  • 优先使用 Exposed 或 Ktorm（Kotlin 原生 ORM）
  • 或使用 MyBatis Plus + Kotlin 扩展
  • Service 禁止直接注入 Mapper，所有数据库读写封装在 Repository 层
  • Repository 内部调用 Mapper，对 Service 层屏蔽数据访问细节
• 序列化：使用 kotlinx.serialization
• 配置：使用 @ConfigurationProperties + data class

测试规范

• 单元测试使用 JUnit 5 + MockK（Kotlin 原生 Mock 框架）
• 测试命名：should {期望行为} when {条件}
• 协程测试使用 runTest
• Spring 集成测试使用 @SpringBootTest
• 测试覆盖率使用 Kover

最佳实践

• 使用 Kotlin DSL 构建 Gradle 脚本
• 使用 value class 包装基础类型增强类型安全
• 使用 @JvmStatic / @JvmField 优化 Java 互操作
• 使用 KMP（Kotlin Multiplatform）实现跨平台逻辑共享
• 使用 Arrow.kt 增强函数式编程能力