@flyeric0212/languages-kotlin

---
description: Kotlin 开发约定和最佳实践
globs: **/*.kt
alwaysApply: false
---

## Kotlin 开发规范

### 基本原则

- 优先使用类型推断，必要时显式声明类型提高可读性
- 避免使用 `Any`，创建具体的类型定义
- 优先使用 `val` 而非 `var`，保持不可变性
- 使用 Kotlin 的空安全特性，避免显式 null 检查
- 避免魔法数字，定义有意义的常量

### 命名规范

- **类和接口**：PascalCase (`UserRepository`, `PaymentService`)
- **函数和变量**：camelCase (`getUserById`, `isValid`)
- **常量和枚举值**：UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT`)
- **包名**：全小写，使用点分隔 (`com.example.userservice`)
- **文件名**：PascalCase，与主要类名一致
- **布尔变量**：使用 `is`、`has`、`can`、`should` 前缀 (`isLoading`, `hasPermission`, `canDelete`)
- 使用完整单词而非缩写，确保拼写正确
  - 标准缩写除外：API、URL、HTTP、JSON 等
  - 常见缩写：id、ctx、req、res

### 函数设计

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

### 类和数据结构

- **数据类**：用于纯数据承载，自动生成 `equals`、`hashCode`、`toString`
- **密封类**：用于有限状态表示，替代枚举的复杂场景
- **密封接口**：Kotlin 1.5+ 用于更灵活的类型层次
- **对象类**：用于单例模式和工具类
- **内联类**：用于类型安全的原始类型包装
- 优先使用组合而非继承
- 遵循 SOLID 原则
- 保持类的职责单一，避免过大的类（建议 ≤200 行，≤10 个公共方法）
- 不要滥用原始类型，将相关数据封装在复合类型中

### 空安全和错误处理

- 使用 `?.` 安全调用操作符
- 使用 `?:` Elvis 操作符提供默认值
- 使用 `!!` 操作符需要有充分理由并添加注释
- 优先使用 `Result` 类型处理可能失败的操作
- 对于异常情况使用具体的异常类型而非通用异常
- 避免在函数中进行数据验证，使用具有内部验证的类型

### 协程和异步编程

- 使用 `suspend` 函数处理异步操作
- 在合适的作用域中启动协程 (`viewModelScope`, `lifecycleScope`, `runBlocking`)
- 使用 `Flow` 处理数据流，`StateFlow`/`SharedFlow` 处理状态
- 避免 `GlobalScope`，始终使用结构化并发
- 合理使用协程上下文和调度器
- 使用 `async`/`await` 进行并发操作
- 正确处理协程取消和异常

### 集合和函数式编程

- 优先使用不可变集合 (`listOf`, `setOf`, `mapOf`)
- 使用函数式操作：`map`、`filter`、`reduce`、`fold`
- 合理使用序列 (`Sequence`) 处理大数据集或链式操作
- 使用作用域函数：`let`、`run`、`with`、`apply`、`also`
- 使用 `takeIf`、`takeUnless` 进行条件处理
- 对简单 lambda 使用 `it` 参数，复杂情况使用命名参数

### 泛型和类型系统

- 合理使用泛型约束和变型（`in`、`out`）
- 使用 `reified` 参数访问泛型类型信息
- 利用类型别名提高代码可读性：`typealias UserId = String`
- 使用内联函数优化高阶函数性能

### 可见性和封装

- 使用最小必要的可见性修饰符
- 优先使用 `internal` 而非 `public` 用于模块内部 API
- 使用 `private` 限制类内部实现细节
- 合理使用 `protected` 用于继承场景

### 测试规范

- 测试方法使用描述性命名：`should_return_user_when_valid_id_provided`
- 遵循 Arrange-Act-Assert 模式
- 清楚命名测试变量：`given...`、`when...`、`then...` 或 `input...`、`expected...`、`actual...`
- 为每个公共函数编写单元测试
- 使用测试替身（Mock、Stub）模拟依赖
- 为每个模块编写集成测试
- 遵循 Given-When-Then 约定编写行为测试

### 代码组织和架构

- 按功能而非类型组织包结构
- 将相关的类放在同一文件中（如密封类的子类）
- 合理使用扩展函数增强现有类型
- 声明接口定义契约，面向接口编程
- 使用依赖注入提高代码可测试性
- 遵循领域驱动设计原则

### 性能和资源管理

- 使用 `inline` 关键字优化高阶函数
- 合理使用 `lazy` 延迟初始化
- 注意避免内存泄漏，特别是在协程和回调中
- 使用 `use` 函数自动管理资源




═══════════════════════════════════════════════════════════════════
═══ ENGLISH TRANSLATION ═══
═══════════════════════════════════════════════════════════════════

---
description: Languages Kotlin Development Guidelines (Translation)
---

# Languages Kotlin Guidelines - English Translation

**Note**: This package contains Chinese cursor rules for Languages Kotlin.

**Original Language**: Chinese (Simplified)

**Content Summary**: This package provides comprehensive development guidelines, best practices, and coding standards for Languages Kotlin. The rules cover code organization, naming conventions, design patterns, testing strategies, and performance optimization.

**Translation Status**: Automated translation placeholder. For accurate technical translation of specific terms and context, please:
1. Use the original Chinese content above as authoritative reference
2. Refer to official Languages Kotlin documentation in English
3. The technical patterns and code examples remain universal across languages

**How to Use**:
- Code blocks and examples use universal syntax
- Technical terms (APIs, methods, libraries) are typically in English even in Chinese text
- Structure and organization principles translate directly to English development practices

**Content Length**: 2515 characters of detailed technical guidance

For community-contributed English translation, please refer to the source repository.