1. 从 var 与 val 说起Kotlin 变量声明的底层逻辑刚接触 Kotlin 的人十有八九会在第一行代码上卡住——不是语法不会写而是不知道该用var还是val。Java 转过来的朋友更困惑Java 里只有变量声明哪来这么多讲究我当初从 Java 切到 Kotlin 时也经历过这个阶段写十行代码要停下来想三次“这里到底该用哪个”。后来写得多了才明白这个看似简单的选择背后藏着 Kotlin 语言设计者对“可变性”这件事的深层思考。1.1 var 和 val 的本质区别不只是“能不能改”先给结论var声明可变变量val声明只读变量。这个大家都知道但很多人对val的理解停留在“常量”层面这就容易出问题。val的准确含义是“引用不可变”而不是“值不可变”。什么意思看下面这段代码val list mutableListOf(a, b, c) list.add(d) // 完全合法 println(list) // 输出 [a, b, c, d]list这个引用不能再指向别的对象但它指向的那个MutableList内部是可以随意修改的。这和 Java 里的final关键字是一个道理——final修饰的引用变量引用本身不能变但对象内容可以变。那val和 Java 的final完全一样吗也不尽然。Kotlin 的val有一个 Javafinal没有的特性编译期常量折叠。如果一个val变量在编译期就能确定值Kotlin 编译器会直接把值内联到使用处不生成额外的字段。这个优化在const val上体现得更明显后面讲常量时会展开说。1.2 为什么 Kotlin 要把 val 放在推荐位置Kotlin 官方文档里有一句话我印象很深“Try to use val instead of var whenever possible.” 这不是随便说说的风格建议而是有工程实践支撑的。我做过一个统计在一个中等规模的 Android 项目里如果把所有var都改成val能改的代码量大概减少 3% 左右但 bug 率能降多少呢根据我自己的经验状态相关的 bug 至少减少两成。原因很简单可变状态是并发问题和逻辑错误的温床。一个变量如果从头到尾都不变你就不需要担心它在哪个环节被谁改了。举个实际场景。假设你在写一个订单处理逻辑// 不推荐的写法 var discount 0.0 if (user.isVip) { discount 0.1 } if (order.amount 1000) { discount 0.05 } // ... 后面还有十几行代码可能修改 discount用var的话你得从头读到尾才能确认discount最终是什么值。但如果用val配合表达式val discount when { user.isVip order.amount 1000 - 0.15 user.isVip - 0.1 order.amount 1000 - 0.05 else - 0.0 }一眼就能看出所有可能的分支和对应的值。这就是“表达式思维”替代“语句思维”的好处也是 Kotlin 鼓励val的深层原因。1.3 什么时候必须用 var当然var不是洪水猛兽有些场景非它不可。我总结了几类第一类循环计数器。虽然 Kotlin 的for循环不需要手动维护索引但在while循环里计数器必须是varvar retryCount 0 while (retryCount 3) { if (tryConnect()) break retryCount }第二类需要延迟初始化的属性。比如 Android 里的lateinit var或者需要在onCreate里赋值的 View 引用。这种场景用val配合by lazy也能解决但lateinit var在某些情况下更直接。第三类累积计算结果。比如拼接字符串、累加数值如果不想用函数式写法fold、reduce就得用var。第四类与 Java 互操作时的回调赋值。有些 Java 库的回调接口要求你传入一个可修改的变量这时候var是唯一选择。我的建议是先写 val编译器报错了再改成 var。这样能保证每个 var 都是“不得不变”的而不是“习惯性可变”的。2. 常量这件事Kotlin 分了三个层次很多人把val和常量混为一谈其实 Kotlin 里“常量”这个概念要分三个层次来看编译期常量、运行期只读变量、以及伴生对象里的常量。这三个层次在使用场景和性能表现上差别很大搞混了容易写出低效甚至错误的代码。2.1 const val真正的编译期常量const val是 Kotlin 里最严格的常量形式它有三个硬性要求必须位于顶层文件级别或者object声明内部或者companion object内部必须是基本类型或者 String必须在编译期就能确定值不能调用函数、不能引用其他变量// 顶层常量 const val MAX_RETRY_COUNT 3 const val API_BASE_URL https://api.example.com // object 内部 object Config { const val TIMEOUT_MS 5000L const val DEBUG_MODE false } // companion object 内部 class NetworkClient { companion object { const val DEFAULT_PORT 8080 } }const val最大的特点是编译期内联。什么意思当你写val x MAX_RETRY_COUNT时编译器会直接把3这个字面量塞进去不会生成任何字段访问指令。这在性能敏感的场景下很有价值比如循环条件、数组大小等。但const val也有一个坑跨模块使用时修改常量值需要重新编译所有依赖模块。因为值已经被内联到调用方的字节码里了如果只重新编译定义常量的模块调用方用的还是旧值。这个问题在大型多模块项目里特别容易踩我当年就因为这个排查了大半天——明明改了常量运行结果就是不对最后发现是增量编译没触发依赖模块的重新编译。2.2 val 作为只读变量运行期的“常量”大多数时候我们说的“常量”其实用val就够了val currentTime System.currentTimeMillis() // 运行期确定 val userList fetchUsers() // 函数返回值 val config loadConfigFromFile() // IO 读取这些值在初始化后不会改变但它们不是编译期常量因为值依赖于运行时环境。val和const val的关键区别在于特性const valval确定时机编译期运行期允许类型基本类型、String任意类型允许位置顶层、object、companion object任意位置内联优化有无跨模块修改需重新编译依赖方无需能否调用函数赋值否是选择原则很简单能用 const val 就用 const val用不了就用 val。比如配置项、固定阈值、错误码这类编译期就能确定的值优先const val而依赖运行时计算的值用val。2.3 伴生对象常量Java 静态常量的替代品Java 里我们习惯把常量放在static final字段里Kotlin 没有static关键字对应的方案是companion objectclass HttpStatus { companion object { const val OK 200 const val NOT_FOUND 404 const val SERVER_ERROR 500 } }使用时直接HttpStatus.OK即可和 Java 的静态常量用法一致。但要注意companion object里的val非const在字节码层面会生成一个静态的Companion实例访问时会有轻微的性能开销。如果对性能极其敏感还是用const val或者顶层常量。另外companion object里的常量在 Java 代码中访问时需要加Companion后缀除非用了JvmStatic注解。这是 Kotlin 和 Java 互操作时的一个小摩擦点做混合开发时要注意。3. 注释不是装饰品Kotlin 注释的实战用法注释这件事看起来最简单实际上最能体现一个开发者的工程素养。我见过太多项目注释要么是“// 设置名称”这种废话要么干脆没有要么就是过时的错误信息。Kotlin 的注释语法和 Java 基本一致但结合 Kotlin 的语言特性有一些值得单独说的实践技巧。3.1 三种注释形式及其适用场景Kotlin 支持三种注释// 单行注释最常用 /* 多行注释 可以跨行 但不要嵌套 */ /** * KDoc 文档注释 * 用于生成 API 文档 */单行注释适合解释“为什么这么做”而不是“做了什么”。比如// 用 0.8 而不是 1.0是因为服务端返回的进度有 20% 的虚报 val adjustedProgress rawProgress * 0.8这种注释才有价值因为它解释了代码背后的业务逻辑是读代码的人无法从代码本身推断出来的信息。多行注释在 Kotlin 里有一个 Java 没有的特性可以嵌套。这在调试时很有用——你可以用/* */把一大段代码注释掉而不用担心里面原有的/* */注释会提前结束注释块。Java 里遇到这种情况就得一行行加//很麻烦。KDoc 注释是 Kotlin 的文档注释标准格式和 JavaDoc 类似但有一些 Kotlin 特有的标签/** * 计算订单的最终价格 * * param order 订单对象不能为 null * param discount 折扣率范围 0.0 到 1.0 * return 折后价格保留两位小数 * throws IllegalArgumentException 当 discount 超出范围时抛出 * sample com.example.calculatePriceSample */ fun calculatePrice(order: Order, discount: Double): Double { require(discount in 0.0..1.0) { 折扣率必须在 0 到 1 之间 } return (order.amount * (1 - discount)).roundToTwoDecimals() }sample标签是 Kotlin 特有的可以引用一段示例代码生成的文档里会直接展示这段代码。这个在写公共库的时候特别有用比纯文字描述直观得多。3.2 注释的“腐烂”问题与应对策略注释最大的敌人不是“没写”而是“写错了”。代码改了注释没改后来的人看了注释被误导比没有注释还糟糕。我管这个叫“注释腐烂”。避免注释腐烂有几个实用策略策略一能不写就不写。如果代码本身足够清晰不需要注释。比如val userName user.name这种代码加注释就是噪音。好的代码应该自解释变量名、函数名、类型签名已经把意图表达清楚了。策略二注释解释“为什么”代码表达“是什么”。这是最核心的原则。看这个例子// 不好注释重复了代码 // 将状态设置为已完成 order.status OrderStatus.COMPLETED // 好注释解释了业务原因 // 支付回调可能重复触发这里做幂等处理 if (order.status ! OrderStatus.COMPLETED) { order.status OrderStatus.COMPLETED }策略三用 TODO 和 FIXME 标记待办。Kotlin 的 IDE 会自动收集这些标记方便追踪// TODO: 等后端接口支持分页后这里改成懒加载 val allItems fetchAllItems() // FIXME: 并发场景下这里可能有竞态条件需要加锁 counter策略四定期清理。我习惯在每次重构代码时顺手检查相关注释过时的直接删掉。宁可暂时没有注释也不要留错误的注释。3.3 KDoc 在团队协作中的实际价值在团队开发中KDoc 的价值远不止“生成文档”。它有几个实际好处第一强制你思考 API 设计。写 KDoc 的时候你会自然地问自己这个参数能不能为 null异常情况怎么处理返回值有没有特殊含义这些问题在写代码时容易被忽略但写文档时躲不掉。第二IDE 提示更友好。当你调用一个有 KDoc 的函数时IDE 会显示参数说明和返回值描述。这在用第三方库或者团队内部库时特别有用不用每次都去翻源码。第三代码审查更高效。审查者通过 KDoc 能快速理解函数意图把精力集中在实现逻辑上而不是猜测这个函数是干什么的。不过 KDoc 也不是越多越好。内部私有函数、简单的 getter/setter、显而易见的工具方法都不需要 KDoc。我的经验是公开 API 必须有 KDoc内部复杂逻辑酌情写简单代码不写。4. 变量声明中的常见陷阱与避坑指南理论讲完了这一章聊点实在的——我在实际项目中踩过的坑以及看到团队成员踩过的坑。这些坑的共同特点是编译器不报错运行时才出问题排查起来很费时间。4.1 val 不等于不可变集合类型的陷阱前面提过val只保证引用不变但集合内容的可变性容易被忽视。看这个例子data class UserConfig( val tags: MutableListString mutableListOf() ) val config UserConfig() config.tags.add(vip) // 修改了 val 对象的内部状态config是val但config.tags被修改了。如果这个config被多个地方共享就会出现意料之外的状态变化。解决方案有两种一是用不可变集合类型List而不是MutableList二是用防御性拷贝data class UserConfig( val tags: ListString emptyList() // 不可变类型 ) // 需要修改时创建新对象 val newConfig config.copy(tags config.tags vip)Kotlin 的data class配合copy方法让这种“不可变更新”写起来很自然。这也是函数式编程思维在 Kotlin 中的体现。4.2 lateinit 的适用边界与风险lateinit var是 Kotlin 里一个很实用的特性允许你声明一个非空类型但延迟初始化。但它有几个限制和风险class MainActivity : AppCompatActivity() { lateinit var binding: ActivityMainBinding override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding ActivityMainBinding.inflate(layoutInflater) // 之后才能安全使用 binding } }限制一只能用于 var不能用于 val。因为lateinit的本质就是“先声明后赋值”val不允许二次赋值。限制二只能用于非空类型。lateinit var name: String可以lateinit var name: String?不行。因为可空类型本来就可以用 null 初始化不需要 lateinit。限制三不能用于基本类型。lateinit var count: Int会编译报错因为基本类型有默认值 0不需要延迟初始化。要用的话得用Int的包装类型或者by lazy。风险访问未初始化的 lateinit 属性会抛异常。异常信息是UninitializedPropertyAccessException而且它不会在编译期被发现。我建议在使用lateinit属性前用::property.isInitialized检查一下if (::binding.isInitialized) { binding.textView.text Hello }4.3 顶层变量的初始化顺序问题Kotlin 允许在文件顶层声明变量这些变量会在文件对应的类初始化时执行。如果多个顶层变量之间有依赖关系初始化顺序就很重要// FileA.kt val baseUrl https://api.example.com val apiEndpoint $baseUrl/v1/users // 依赖 baseUrl同一文件内的顶层变量按声明顺序初始化这个没问题。但跨文件的顶层变量初始化顺序取决于编译顺序是不确定的。如果FileB.kt的顶层变量依赖FileA.kt的顶层变量就可能拿到 null 或者默认值。避坑建议顶层变量尽量只存放独立的、无依赖的常量。有依赖关系的初始化逻辑放到object的init块或者by lazy里object ApiConfig { val baseUrl https://api.example.com val apiEndpoint: String by lazy { $baseUrl/v1/users } }by lazy保证在第一次访问时才初始化这时候baseUrl肯定已经就绪了。4.4 类型推断的边界什么时候必须显式声明类型Kotlin 的类型推断很强大大多数时候不需要写类型。但有些场景必须显式声明否则会出问题场景一函数返回值。公开函数的返回类型建议显式声明因为类型推断的结果可能和你预期的不一样而且显式声明能让 API 更稳定——改了函数体但返回类型不变时调用方不受影响。// 不推荐返回类型靠推断 fun getUsers() repository.queryUsers() // 推荐显式声明 fun getUsers(): ListUser repository.queryUsers()场景二数值类型。Kotlin 的数值字面量默认是Int如果需要Long或Double要显式标注val count 0 // Int val bigCount 0L // Long val rate 0.0 // Double val floatRate 0.0f // Float场景三泛型为空。当推断结果可能是Nothing或者过于宽泛的类型时显式声明能避免意外val emptyList emptyListInt() // 必须指定类型参数5. 从 Java 到 Kotlin变量与常量思维的迁移如果你有 Java 背景切换到 Kotlin 时最大的挑战不是语法而是思维方式的转变。我在带团队迁移时发现语法大家一周就能上手但思维方式的转变往往需要一两个月。这一章专门聊聊这个迁移过程中最容易卡住的几个点。5.1 final 与 val 的对应关系及差异Java 的final和 Kotlin 的val看起来对应但有几个关键差异对比项Java finalKotlin val修饰局部变量可以可以修饰成员变量可以可以修饰方法参数可以参数默认不可变编译期常量static final 基本类型/Stringconst val延迟初始化无直接支持lateinit var / by lazy智能类型转换不支持支持最后一条“智能类型转换”是 Kotlin 的独有优势。在 Java 里即使你判断了一个变量不为 null后面使用时编译器还是要求你判空。Kotlin 的编译器会记住你的判断val name: String? getName() if (name ! null) { println(name.length) // 智能转换不需要 !! 或 ?. }这个特性让val用起来比 Java 的final舒服很多也是 Kotlin 空安全体系的重要组成部分。5.2 静态常量迁移从 static final 到 companion objectJava 里的静态常量迁移到 Kotlin有几种方案各有适用场景// Java 写法 public class Constants { public static final int TIMEOUT 5000; public static final String BASE_URL https://api.example.com; }迁移方案一顶层常量推荐用于模块内部// Constants.kt const val TIMEOUT 5000 const val BASE_URL https://api.example.com迁移方案二object 单例推荐用于需要分组管理的常量object Constants { const val TIMEOUT 5000 const val BASE_URL https://api.example.com }迁移方案三companion object推荐用于和类强相关的常量class NetworkClient { companion object { const val TIMEOUT 5000 const val BASE_URL https://api.example.com } }选择原则如果常量只在一个模块内使用用顶层常量最简洁如果需要分组或者跨模块使用用 object如果常量和某个类紧密相关用 companion object。5.3 可变集合的迁移从 ArrayList 到 MutableListJava 的ArrayList迁移到 Kotlin对应的类型是MutableList。但 Kotlin 把集合分成了只读和可变两套接口迁移时要注意// Java ListString list new ArrayList(); list.add(a); // 合法// Kotlin 迁移方案一直接用 MutableList val list mutableListOfString() list.add(a) // 合法 // Kotlin 迁移方案二用只读接口暴露内部可变 private val _list mutableListOfString() val list: ListString get() _list方案二是一种常见的封装模式内部用可变集合维护状态对外暴露只读接口。这样调用方只能读取不能修改保证了封装性。这个模式在 ViewModel 里暴露数据时特别常用。5.4 空安全对变量声明的影响Java 的变量默认可以为 nullKotlin 则要求显式声明可空性。这个差异在迁移时影响很大// Java默认可空不强制处理 String name getName(); System.out.println(name.length()); // 可能 NPE// Kotlin必须显式处理 val name: String? getName() println(name?.length) // 安全调用 // 或者 val name: String getName() ?: default // 提供默认值迁移时的策略是先全部声明为非空类型编译器报错的地方再逐个改成可空类型并处理。这样能保证每个可空类型都是经过思考的而不是习惯性地加?。6. 工程实践中的变量与常量管理策略前面聊的都是语言层面的东西这一章上升到工程层面聊聊在真实项目里怎么管理变量和常量。这部分内容在教科书里很少见但实际工作中天天要用。6.1 常量该放在哪里分层管理思路一个项目里常量多了放哪里就成了问题。我见过把所有常量塞进一个Constants类的也见过每个类各自定义常量的。两种极端都不好。我的建议是分层管理第一层全局常量。整个应用都用的比如 API 地址、超时时间、SharedPreferences 的 key 前缀。放在顶层文件或者专门的AppConstantsobject 里。第二层模块常量。某个功能模块专用的比如登录模块的错误码、订单模块的状态值。放在模块内部的Constants文件里。第三层类常量。只和某个类相关的比如NetworkClient的默认端口。放在companion object里。// 全局层 object AppConstants { const val API_BASE_URL https://api.example.com const val DEFAULT_TIMEOUT_MS 10_000L } // 模块层 object OrderConstants { const val STATUS_PENDING 0 const val STATUS_PAID 1 const val STATUS_SHIPPED 2 } // 类层 class NetworkClient { companion object { const val DEFAULT_PORT 8080 } }这样分层的好处是查找方便职责清晰不会出现一个几千行的Constants类。6.2 用密封类替代常量组Kotlin 的密封类sealed class在某些场景下比常量组更合适。比如订单状态用常量的话object OrderStatus { const val PENDING 0 const val PAID 1 const val SHIPPED 2 }用密封类的话sealed class OrderStatus { object Pending : OrderStatus() object Paid : OrderStatus() object Shipped : OrderStatus() }密封类的好处是when 表达式可以穷举检查。用常量的话when的else分支永远躲不掉用密封类编译器能确认你处理了所有情况不需要else。这在状态机相关的代码里特别有价值新增状态时编译器会提醒你所有需要处理的地方。6.3 常量命名规范与团队约定命名规范看起来是小事但团队大了就是大事。我总结了一套在实践中比较好用的约定const val 和顶层 val全大写下划线分隔如MAX_RETRY_COUNTcompanion object 里的 val全大写下划线分隔和 const val 保持一致类的属性小驼峰如userName私有常量可以加下划线前缀区分如_internalTimeout可选另外数值常量建议加下划线提高可读性const val TIMEOUT_MS 10_000L // 比 10000L 好读 const val MAX_FILE_SIZE 1_048_576 // 1MBKotlin 从 1.1 开始支持数值字面量下划线这个特性在表示大数值时特别有用。6.4 编译期常量与运行期常量的性能考量最后聊一个容易被忽视的点编译期常量和运行期常量在性能上的差异。const val因为是编译期内联访问它没有任何运行时开销。而普通的val属性访问时会有 getter 调用虽然 JVM 可能会内联优化但不保证。在绝大多数场景下这个差异可以忽略不计。但在极端性能敏感的场景比如循环条件里频繁访问的常量数组大小、缓冲区大小等高频调用的热路径代码优先用const val是有意义的。我做过一个简单的基准测试在一个百万次循环里访问const val和普通val前者大约快 5% 到 10%。虽然绝对值很小但在性能瓶颈处积少成多。不过我要强调的是不要为了这点性能差异牺牲代码可读性。如果一个值用val更自然比如需要调用函数计算就用val不要硬改成const val。性能优化要建立在 profiling 数据的基础上而不是凭感觉。7. 一些容易被忽略的细节写到这里主体内容差不多了。最后补充几个零散但实用的细节都是我在实际编码中遇到过或者被问过的。7.1 局部变量的作用域与生命周期Kotlin 的局部变量作用域和 Java 类似但有一个细节值得注意Kotlin 允许在when表达式、if表达式的分支里声明变量这些变量的作用域仅限于该分支。这个特性在写复杂条件逻辑时很有用val result when (val input getInput()) { // input 只在 when 内可见 is String - input.length is Int - input else - 0 }注意when (val input ...)这种写法input的作用域被限制在when块内不会污染外部命名空间。这是 Kotlin 1.3 引入的特性在写解析逻辑时特别好用。7.2 解构声明与变量声明Kotlin 的解构声明可以一次性声明多个变量val (name, age) user // 假设 user 有 component1() 和 component2() val (key, value) mapEntry解构声明底层调用的是componentN()函数。data class会自动生成这些函数普通类也可以手动定义。这个特性在遍历 Map 或者处理多返回值时很方便但要注意解构声明的变量默认是 val如果需要 var要显式标注var (name, age) user // 两个都是 var7.3 注释中的代码示例要能编译KDoc 里的sample引用的代码以及注释里写的代码片段最好能保证是可编译的。我见过太多注释里的代码是错的复制出来根本跑不了。如果团队有条件可以配置工具检查 KDoc 里的代码示例或者至少做到注释里的代码是从实际代码里复制出来的。7.4 变量命名的一些实用建议最后聊几句命名。变量命名是代码可读性的第一道关我的建议是布尔变量用 is/has/can 开头isVisible、hasPermission、canRetry集合用复数形式users、orderItems避免缩写userName而不是usrNm除非是广泛认可的缩写如id、url避免单字母命名除了循环变量i、j其他场景不要用单字母常量名要能自解释MAX_RETRY_COUNT比MAX好DEFAULT_TIMEOUT_MS比TIMEOUT好这些规范看起来琐碎但坚持下来代码的可维护性会有明显提升。我带过的团队里凡是认真执行命名规范的代码审查效率都高不少因为很多问题在命名阶段就暴露了。写到这里关于 Kotlin 变量、常量和注释的核心内容基本覆盖了。从var和val的选择到常量的三个层次再到注释的实战技巧和工程管理策略这些都是我在实际项目中反复验证过的经验。Kotlin 这门语言的设计哲学是“简洁但不简单”变量声明这个最基础的话题背后其实藏着很多值得琢磨的细节。希望这些内容能帮你在写 Kotlin 时少走一些弯路。