Android Kotlin

Android Kotlin 开发技能

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

技术栈强制约束

• 使用 Kotlin 作为主要开发语言
• 最低 SDK 版本：API 24（Android 7.0），目标 SDK 版本：API 34+
• 使用 Jetpack 组件（ViewModel、Flow、Navigation、Room）
• 使用 Gradle Kotlin DSL 构建脚本
• UI 开发优先使用 Jetpack Compose

命名规范

• 类名：PascalCase（UserViewModel、OrderRepository）
• 函数/变量：camelCase（getUserById、userName）
• 常量：UPPER_SNAKE_CASE（MAX_RETRY_COUNT）或 PascalCase（顶层常量）
• 包名：小写点分隔（com.example.app.feature.user）
• 布局文件：snake_case（activity_main.xml、fragment_user_list.xml、item_order.xml）
• 资源文件：
  • drawable：ic_{名称}（图标）、bg_{名称}（背景）
  • values：colors.xml、strings.xml、dimens.xml、styles.xml
• 命名语义化，禁止拼音、无意义缩写

Kotlin 惯用语法

• 优先使用 val，仅在需要重新赋值时使用 var
• 使用数据类（data class）承载数据
• 使用密封类（sealed class）表示有限状态集
• 使用扩展函数增强已有类功能
• 使用作用域函数：let、run、with、apply、also
• 使用 when 表达式替代多重 if-else
• 使用字符串模板（"Hello, $name"）替代字符串拼接
• 使用解构声明（val (name, age) = person）

架构规范

• 推荐架构：MVVM + Clean Architecture
• 分层结构：
  • ui/：Activity、Fragment、Compose Screen、ViewModel
  • domain/：UseCase、Repository 接口、Entity
  • data/：Repository 实现、Remote DataSource、Local DataSource、DTO
  • di/：依赖注入模块
• 禁止跨层调用，UI 层不直接访问 Data 层
• 依赖注入使用 Hilt

Jetpack 组件规范

• ViewModel：持有 UI 状态，禁止持有 View 引用
• StateFlow / SharedFlow：替代 LiveData 进行状态管理
• Navigation：页面导航使用 Navigation Component，禁止手动管理 Fragment 事务
• Room：本地数据库使用 Room，DAO 方法返回 Flow 实现数据观察
• DataStore：替代 SharedPreferences 存储键值对
• WorkManager：后台任务使用 WorkManager，禁止直接使用 Service
• Paging 3：分页加载使用 Paging 库

Jetpack Compose 规范

• 组件函数使用 @Composable 注解
• 状态提升原则：无状态组件 + 状态参数
• 组件拆分：单个 Composable 函数不超过 100 行
• 预览使用 @Preview 注解
• 主题系统：Material Theme 自定义颜色、字体、形状
• 列表使用 LazyColumn / LazyRow，禁止 Column + forEach

协程与 Flow 规范

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

网络请求规范

• 使用 Retrofit + OkHttp
• OkHttp 拦截器：
  • 请求拦截器：添加 Token、TraceId
  • 响应拦截器：统一错误处理
• 协程 + Flow 处理异步请求
• 返回结果封装：Result<T> 或 ApiResult<T>，包含 code、message、data，成功码固定为 0，失败使用5位分段编码
• JSON 解析使用 kotlinx.serialization 或 Moshi
• 网络状态监听使用 ConnectivityManager

空安全规范

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

注释规范

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

格式规范

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

代码质量强制要求

• 禁止空指针：使用 Kotlin 空安全特性，禁止 !!
• 禁止魔法值：硬编码常量必须定义为命名常量
• 集合操作前必须判空，使用 isEmpty() / isNotEmpty()
• 禁止在主线程执行 IO 操作，使用协程 Dispatchers.IO
• 协程必须处理异常和取消
• 禁止内存泄漏：Activity/Fragment 销毁时取消协程和回调
• 字符串资源统一放入 strings.xml，禁止硬编码
• 优先使用不可变集合（listOf、mapOf），仅在需要修改时使用可变集合
• 使用 ktlint + detekt 进行静态检查

性能优化

• 布局优化：减少嵌套层级，使用 ConstraintLayout
• 图片加载使用 Coil 或 Glide，禁止手动解码
• 列表使用 DiffUtil 或 Paging 优化刷新
• 避免在 onDraw 中创建对象
• 使用 Baseline Profile 优化启动
• Compose 性能：使用 remember、derivedStateOf、key 避免不必要的重组

测试规范

• 单元测试使用 JUnit 5 + MockK（Kotlin 原生 Mock 框架）
• UI 测试使用 Compose Testing
• 测试命名：should_{期望行为}_when_{条件}
• ViewModel 测试使用 Turbine 验证 Flow
• Repository 测试使用 MockWebServer
• 协程测试使用 runTest

最佳实践

• 使用协程 + Flow 替代 RxJava 和回调
• 使用 Hilt 管理依赖注入
• 使用 Navigation Component 管理页面导航
• 使用 Jetpack Compose 构建 UI
• 使用 LeakCanary 检测内存泄漏
• 使用 R8 混淆和优化
• 使用 value class 包装基础类型增强类型安全