AI 定义的 Android 开发规范，直接抄作业！

---

description: Android开发规范 - 基于项目实际技术栈 globs: /*.kt,/.java,**/.xml alwaysApply: true

Android开发规范

更新时间：2026 适用范围：项目及相关模块

一、通用开发原则

1.1 基本要求

1. 默认使用中文：所有回复、注释、文档默认使用中文
2. 任务拆解：复杂需求拆解成小任务，分步实现，每完成一个小任务后再继续
3. 代码检查：代码实现前后要仔细检查，确保类型安全、空安全处理完整、生命周期管理正确
4. 保持兼容：在已有功能基础上添加新功能时，必须确保不影响原有功能和组件复用性
5. 遵循架构：遵循项目MVVM架构设计，保持代码风格与Android编码规范一致

1.2 设计原则

• 单一职责原则：组件设计遵循单一职责，不混合多个变更
• 第一性原理：组件设计规划时，从根本需求出发思考
• KISS原则：代码实现保持简单直接
• SOLID原则：面向对象设计遵循SOLID五大原则

1.3 代码复用

• 优先使用Android Jetpack组件库和现有工具类，避免重复代码
• 不引入不必要的依赖，优先使用项目已有库
• 确保代码可读性，复杂逻辑添加注释，类和接口参数详细定义
• 代码变更范围最小化，避免修改公共组件、全局状态

二、项目技术栈

2.1 核心技术

• 开发语言：Kotlin（主）+ Java（少量遗留代码）
• UI框架：XML布局（现有）+ Jetpack Compose（新功能推荐）
• 架构模式：MVVM
• 异步处理：Kotlin Coroutines（推荐）+ RxJava2（遗留代码）
• 依赖注入：手动注入（未使用Hilt/Koin）

2.2 网络层

• HTTP客户端：Retrofit 2.9.0 + OkHttp 4.10.0
• 响应式编程：RxJava2 + RxKotlin
• JSON解析：Gson + FastJson

2.3 UI组件库

• 图片加载：Glide 4.11.0
• 视图绑定：DataBinding + ViewBinding
• Compose：Jetpack Compose（BOM 2025.01.01）+ Coil
• 列表增强：BRV（RecyclerView增强库）
• 下拉刷新：SmartRefreshLayout
• 弹窗：XPopup
• 轮播图：Banner

2.4 数据存储

• 键值存储：MMKV（替代SharedPreferences）
• 数据库：暂未使用Room（待引入）

2.5 工具库

• 协程：Kotlin Coroutines
• 生命周期：AndroidX Lifecycle
• 日志：XLog
• 工具类：Longan（Kotlin工具类集合）
• 事件总线：Channel
• 屏幕适配：AutoSize（今日头条方案）

三、Kotlin编码规范

3.1 命名规范

• 类和接口：PascalCase (UserRepository,)
• 函数和变量：camelCase (getUserById, isLoading)
• 常量和枚举值：
• 包名：全小写，使用点分隔
• 布尔变量：使用 is、has、can、should 前缀
• 文件名：PascalCase，与主要类名一致

3.2 基本原则

• 优先使用 val：保持不可变性，除非必须使用 var
• 类型推断：优先使用类型推断，必要时显式声明类型
• 空安全：使用Kotlin空安全特性，避免 !! 操作符
• 避免魔法数字：定义有意义的常量
• 使用完整单词：避免缩写，确保拼写正确（标准缩写除外：API、URL、HTTP、JSON等）

3.3 函数设计

• 编写简短且单一目的的函数（建议 ≤20 行）
• 使用表达式函数简化单行返回：fun square(x: Int) = x * x
• 函数名以动词开头，体现其行为
• 使用命名参数提高可读性：createUser(name = "John", age = 25)
• 合理使用默认参数值，减少函数重载
• 通过早期返回避免深层嵌套

3.4 类和数据结构

• 数据类：用于纯数据承载（自动生成 equals、hashCode、toString）
• 密封类：用于有限状态表示（如网络请求状态：Success、Error、Loading）
• 对象类：用于单例模式和工具类
• 优先使用组合而非继承
• 保持类的职责单一（建议 ≤200 行，≤10 个公共方法）

3.5 空安全和错误处理

• 使用 ?. 安全调用操作符
• 使用 ?: Elvis 操作符提供默认值
• 避免使用 !! 操作符，必须使用时添加注释说明
• 使用具体的异常类型而非通用异常

四、异步编程规范

4.1 协程使用（推荐）

• 优先使用协程：新功能使用Kotlin Coroutines，避免使用RxJava
• 使用 suspend 函数：处理异步操作
• 合适的作用域：
  • ViewModel中使用 viewModelScope
  • Fragment中使用 lifecycleScope
  • 避免使用 GlobalScope
• Flow使用：
  • 使用 Flow 处理数据流
  • 使用 StateFlow 管理状态
  • 使用 SharedFlow 处理事件
• 正确处理取消和异常

4.2 RxJava使用（遗留代码）

• 仅在维护遗留代码时使用RxJava
• 正确管理订阅生命周期，避免内存泄漏
• 使用 CompositeDisposable 管理多个订阅
• 在组件销毁时取消订阅

4.3 线程切换

• UI操作必须在主线程执行
• 耗时操作放在工作线程
• 协程使用 Dispatchers.IO、Dispatchers.Main、Dispatchers.Default
• RxJava使用 subscribeOn(Schedulers.io())、observeOn(AndroidSchedulers.mainThread())

五、UI开发规范

5.1 Jetpack Compose（新功能推荐）

• 优先使用Compose：新功能优先使用Jetpack Compose构建UI
• 可组合函数：
  • 使用 @Composable 注解
  • 函数名使用PascalCase
  • 保持函数简短，单一职责
• 状态管理：
  • 使用 remember 记住状态
  • 使用 rememberSaveable 保存配置更改后的状态
  • 使用 derivedStateOf 派生状态
• 副作用：
  • 使用 LaunchedEffect 执行协程
  • 使用 DisposableEffect 管理资源
  • 使用 SideEffect 发布状态到非Compose代码
• Modifier使用：
  • 合理使用Modifier进行样式和行为定制
  • Modifier链式调用顺序影响结果
• 性能优化：
  • 合理使用 key() 优化列表重组
  • 避免在Composable中创建新对象
  • 使用 remember 缓存计算结果

5.2 传统View系统（维护现有代码）

• ViewBinding：强制使用ViewBinding替代 findViewById
• 避免DataBinding：除非必要，避免使用DataBinding
• 布局优化：
  • 优先使用 ConstraintLayout 减少嵌套
  • 合理使用 RecyclerView 展示列表
  • 避免过度绘制
• 自定义View：遵循测量、布局、绘制流程

5.3 设计规范

• 遵循 Material Design 3 设计规范
• 支持深色主题
• 实现响应式布局适配不同屏幕尺寸
• 使用项目已有的屏幕适配方案（AutoSize）

六、架构规范

6.1 MVVM架构

• 严格遵循MVVM：View - ViewModel - Model
• View层：
  • Activity/Fragment/Compose
  • 只负责UI展示和用户交互
  • 不包含业务逻辑
• ViewModel层：
  • 管理UI相关数据
  • 处理业务逻辑
  • 通过 StateFlow/LiveData 暴露状态
  • 使用 viewModelScope 管理协程
  • 避免持有Context引用
• Model层：
  • Repository模式统一数据访问
  • 数据源（网络、数据库、缓存）
  • 数据模型类

6.2 Repository模式

• 实现Repository模式进行数据抽象
• Repository负责协调多个数据源
• 实现离线优先（Offline-first）策略
• 正确处理缓存失效和数据同步

6.3 依赖管理

• 当前项目使用手动依赖注入
• 在ViewModel中通过构造函数注入依赖
• 避免在Activity/Fragment中直接创建ViewModel依赖
• 未来可考虑引入Hilt进行依赖注入

七、网络层规范

7.1 Retrofit使用

• 使用Retrofit进行REST API调用
• API接口定义在 common/network/api 包下
• 使用 suspend 函数定义API接口（推荐）
• 或使用 Observable/Single 返回类型（遗留代码）

7.3 错误处理

• 实现统一的错误处理机制
• 正确处理网络异常、超时、解析错误
• 向用户展示友好的错误提示

7.4 网络状态

• 正确处理网络连接状态变化
• 实现请求去重和防抖动
• 合理设置超时时间

八、数据存储规范

8.1 MMKV使用

• 优先使用MMKV：替代SharedPreferences
• 用于存储简单键值对数据
• 注意数据类型和序列化
• 敏感数据需要加密存储

8.2 数据库（待引入）

• 未来引入Room数据库
• 用于复杂数据存储和查询
• 实现数据库迁移策略

8.3 缓存策略

• 实现多级缓存（内存缓存、磁盘缓存）
• 合理设置缓存过期时间
• 正确处理缓存失效

8.4 文件存储

• 使用 PathUtils 获取标准路径
• 注意Android 10+的分区存储
• 正确处理文件权限

九、生命周期管理

9.1 Activity/Fragment生命周期

• 正确处理Activity和Fragment生命周期
• 在 onCreate 中初始化
• 在 onDestroy 中释放资源
• 避免在组件销毁后执行异步操作

9.2 Lifecycle-aware组件

• 使用 LifecycleObserver 创建生命周期感知组件
• 在Fragment中使用 viewLifecycleOwner 观察数据
• 避免内存泄漏

9.3 ViewModel生命周期

• ViewModel在配置更改后保留
• 在ViewModel的 onCleared() 中清理资源
• 使用 viewModelScope 自动管理协程生命周期

9.4 Compose生命周期

• 使用 DisposableEffect 管理资源
• 使用 LaunchedEffect 执行副作用
• 正确处理Composable的重组

十、性能优化

10.1 内存管理

• 避免内存泄漏，正确管理对象生命周期
• 使用LeakCanary检测内存泄漏（开发环境）
• 合理使用图片加载库（Glide、Coil）
• 实现懒加载和分页加载

10.2 渲染性能

• 避免过度绘制和布局嵌套
• 正确使用 RecyclerView 的 ViewHolder 模式
• 在Compose中合理使用 key() 和 remember()
• 使用BRV库简化RecyclerView开发

10.3 启动优化

• 避免在Application中执行耗时操作
• 使用启动画面优化用户体验
• 延迟初始化非关键组件

10.4 列表优化

• 使用分页加载（项目中已实现）
• 实现上拉加载更多
• 正确处理列表滚动性能
• 使用DiffUtil优化列表更新

十一、项目特定规范

11.3 图片处理

• 使用Glide加载图片（现有代码）
• 使用Coil加载图片（Compose中）

十二、安全和权限

12.1 权限管理

• 正确实现运行时权限请求
• 使用项目中的权限管理工具类
• 向用户解释权限用途
• 处理权限被拒绝的情况

12.2 数据安全

• 敏感数据加密存储（使用AesUtil）
• 避免在日志中输出敏感信息
• 正确处理用户隐私数据
• 实现网络安全配置

12.3 代码安全

• 避免硬编码敏感信息
• 使用ProGuard/R8混淆代码
• 注意防止SQL注入、XSS等安全问题