kotlin-development

Kotlin 开发最佳实践

通用原则

• 所有代码和文档都使用英语
• 始终声明每个变量和函数的类型
• 避免使用 any 类型；改为创建所需的类型
• 函数体内不留空行

命名约定

大小写规范

• PascalCase：类、接口、枚举
• camelCase：变量、函数、方法、参数
• UPPERCASE：环境变量、常量
• underscores_case：文件和目录

命名指南

• 每个函数都以动词开头（get、set、create、update、delete 等）
• 使用完整单词而非缩写
  • 允许使用的缩写：API、URL、循环中的 i/j、err、ctx、req/res/next
• 避免使用魔法数字；改为定义常量
• 布尔变量使用以下前缀：isLoading、hasError、canDelete

函数设计

大小与职责

• 函数应少于 20 条指令
• 每个函数都应只负责一项职责
• 复杂度增加时，将逻辑提取到实用函数中

函数命名

• 使用基于动词的命名，描述所执行的操作
• 返回布尔值的函数使用 is、has 或 can 作为前缀
• 无返回值的函数使用 execute、save、send 等动作动词作为前缀

减少嵌套

• 优先使用提前返回处理边界情况
• 将嵌套逻辑提取到单独的函数中
• 使用高阶函数（map、filter、reduce）尽量减少循环
• 简单操作优先使用箭头函数；其他情况使用命名函数

参数

• 使用默认参数代替空值检查
• 函数有多个参数时，将它们合并到对象中（RO-RO 模式）
• 尽量缩短参数列表（最多 3-4 个参数）

数据处理

数据类

• 使用数据类表示数据结构
• 当原始类型代表领域概念时，将其封装在复合类型中
• 在数据类内部验证数据

不可变性

• 数据优先采用不可变设计
• 对不会改变的变量使用 val
• 尽可能使用不可变集合
• 创建新实例，而不是修改现有实例

类和对象

大小指南

• 类应少于 200 条指令
• 公有方法少于 10 个
• 属性少于 10 个

设计原则

• 遵循 SOLID 原则
• 优先使用组合，而非继承
• 使用接口实现抽象
• 让类专注于单一职责

异常处理

何时使用异常

• 仅在真正意外的错误发生时使用异常
• 不要使用异常控制流程
• 仅在以下情况下捕获异常：
  • 修复预期的问题
  • 重新抛出前补充上下文

最佳实践

• 为领域特定错误创建自定义异常类型
• 提供有意义的错误消息
• 在适当的级别记录异常

测试

单元测试

• 遵循 Arrange-Act-Assert 约定
• 为所有公有函数编写单元测试
• 使用测试替身（mock、stub、fake）处理依赖项
• 为测试起描述性名称，以说明其行为

验收测试

• 遵循 Given-When-Then 约定
• 测试面向用户的行为和场景
• 确保测试彼此独立且可重复

代码组织

• 将相关功能放在一起
• 保持文件职责明确、结构紧凑
• 使用包/模块按功能或层次组织代码
• 在整个项目中保持一致的文件结构