16. 内联类与注解：编译时类型检查的艺术
说实话，Kotlin 的很多特性，刚接触时觉得「花里胡哨」，用久了才发现是真香。内联类（Inline Class）就是其中之一。我第一次看到它时，心想这不就是个包装类吗？跟 data class 有啥区别？
直到我在一个支付项目里，被「String 地狱」折磨得够呛——订单号、用户 ID、金额，全是 String。传参时一不小心就传反了，编译时一声不吭，运行时才炸。嗯，那时候我就意识到，类型安全不是锦上添花，而是刚需。
16.1 内联类：零开销的包装
内联类的核心思想很简单：用类型来区分含义相同的原始数据。它不像普通包装类那样在堆上创建对象，而是在编译时直接替换成底层类型。说白了，就是「编译时严格，运行时轻量」。
核心语法
@JvmInline
value class OrderId(val value: String)
@JvmInline
value class UserId(val value: String)
fun processOrder(orderId: OrderId, userId: UserId) {
// 业务逻辑
}
// 调用时，类型错误会直接编译失败
// processOrder(UserId("123"), OrderId("456")) // ❌ 编译错误
processOrder(OrderId("123"), UserId("456")) // ✅ 正确
你看，同样的 String，一旦包装成不同的内联类，编译器就能帮你拦住传参错误。我在项目中遇到过好几次因为参数顺序搞反导致的线上 bug，自从用了内联类，这类问题基本绝迹了。
16.2 内联类 + 注解：双重保险
光有内联类还不够。有时候我们需要在运行时保留一些元信息，或者做更细粒度的校验。这时候注解就派上用场了。
我个人习惯的做法是：用内联类做类型区分，用注解做行为约束。两者结合，效果 1+1 > 2。
@Target(AnnotationTarget.TYPE)
@Retention(AnnotationRetention.SOURCE)
annotation class NonEmpty
@JvmInline
value class Username @JvmOverloads constructor(
@get:NonEmpty val value: String
) {
init {
require(value.isNotBlank()) { "用户名不能为空" }
}
}
这里注解 @NonEmpty 是给开发者看的提示，而 require 是运行时保障。你想想看，如果团队里有人偷懒直接传空字符串，编译时注解虽然拦不住，但运行时 init 块会立刻抛出异常。这就是「编译时提醒 + 运行时兜底」的双保险。
16.3 编译时类型检查的艺术
为什么说这是「艺术」？因为好的类型设计，能让错误在编译期就暴露出来，而不是拖到线上。
我曾经接手过一个老项目，里面金额用 Long 表示，单位是分。结果有个同事传参时把元当成了分，导致一笔订单金额差了 100 倍。这种问题，靠 code review 很难每次都发现。
用内联类重构后，代码变成了这样：
@JvmInline
value class CentAmount(val value: Long)
@JvmInline
value class YuanAmount(val value: Long)
fun calculateTax(amount: CentAmount): CentAmount {
return CentAmount(amount.value * 6 / 100)
}
// 调用方必须明确单位
val price = CentAmount(10000) // 100元
val tax = calculateTax(price) // 编译通过
// calculateTax(YuanAmount(100)) // ❌ 编译错误
你看，编译器直接帮你区分了「分」和「元」。这种检查比任何单元测试都可靠，因为它是 100% 覆盖的。
16.4 注解处理器：自动生成校验代码
内联类 + 注解的组合，还能配合注解处理器做更多事情。比如自动生成序列化、反序列化的校验代码。
我建议你在项目里这样组织：
- 定义注解：如
@Email、@Phone、@NonEmpty - 定义内联类：如
EmailAddress、PhoneNumber - 编写注解处理器：自动生成校验逻辑
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.SOURCE)
annotation class Validate
@Validate
@JvmInline
value class EmailAddress(val value: String) {
init {
require(value.contains("@")) { "无效的邮箱格式" }
}
}
注解处理器可以在编译时扫描所有带 @Validate 的内联类，自动生成单元测试或者校验工具类。这样既保证了类型安全，又减少了重复劳动。
16.5 避坑指南
我曾经踩过的坑：
- 不要在内联类里用 == 比较不同包装：两个不同的内联类即使底层值相同，也不应该相等。Kotlin 默认会生成正确的 equals，但如果你手动重写了，要小心。
- 注意 JVM 平台的限制：内联类不能有
lateinit属性，也不能继承其他类。这是底层实现决定的。 - 注解的 Retention 要选对：如果只是编译时检查，用
SOURCE；如果需要运行时反射，用RUNTIME。别一股脑全用 RUNTIME，会影响性能。
16.6 知识体系总览
下面这张图总结了内联类与注解在编译时类型检查中的协作关系：
16.7 实战建议
如果你现在要开始用内联类 + 注解，我建议你从这几个地方入手：
- ID 字段：订单 ID、用户 ID、商品 ID，全部用内联类包装
- 金额字段：明确区分分、元、美元等不同单位
- 字符串约束：邮箱、手机号、URL 等，用注解标记格式要求
小技巧：在团队里推行时，可以先从最常出 bug 的字段开始。比如你们项目里因为金额单位搞错出过事故，那就优先把金额相关的 Long 全部换成内联类。别想着一步到位，慢慢来，大家接受度更高。
最后说一句：编译时类型检查，不是银弹。但它确实是提升代码质量、降低 bug 率最有效的手段之一。你想想看，与其花时间在 code review 里反复强调「注意参数顺序」，不如让编译器帮你记住这件事。何乐而不为呢？