内联值类

是什么，为什么存在

内联值类（inline value class） 是没有稳定对象标识、以一个主构造函数属性承载数据的 Kotlin 类。 在 JVM 后端，声明同时使用 value 与 @JvmInline：@JvmInline value class UserId(val value: Long)。 它在 Kotlin 类型系统中是独立类型，但编译器可以在运行时用被包装的值表示实例。

值类解决的是“多个概念碰巧使用同一种基础类型”的问题。 如果用户 ID 与订单 ID 都是 Long，普通参数可以被意外对调，而且编译器无法发现。 把它们声明成 UserId 与 OrderId 后，错误会停在编译期，而存储和协议边界仍可显式访问原始 Long。

你会在标识符、计量单位、已规范化字符串和受约束标量中遇到值类。 它适合一个值就能完整表达的概念。 需要多个数据属性、可复制快照或常规对象标识时，应考虑数据类或普通类，而不是把几个字段塞进集合或字符串后再包装。

类型别名不创建新类型

typealias UserId = Long 只给 Long 增加另一个源码名称。 它与 Long 赋值兼容，另一个指向 Long 的别名也能传给 UserId 参数。 类型别名适合缩短复杂类型签名，不适合阻止相同底层类型之间的误传。

值类则创建真正的新类型。 UserId(7) 不能直接传给需要 OrderId 或 Long 的函数，反方向也不行。 这种边界是值类最可靠的收益；运行时是否装箱属于另一层问题，不应混为“类型是否真实存在”。

工作原理

声明约束

JVM 内联值类必须有且只有一个主构造函数属性。 该属性使用 val，不能是 vararg；类本身始终是 final，不能声明为 inner、data 或 enum，也不能继承普通类。 值类可以实现接口，因此可以在保留领域类型的同时加入一项行为契约。

构造函数、init 块、次构造函数、成员函数与计算属性都可以出现在值类中。 除主构造函数属性外，其他属性不能拥有后备字段，所以 lateinit 属性与委托属性不适用。 伴生对象可以提供解析或规范化入口，也不会给每个实例增加字段。

主构造函数的单个属性是 底层类型（underlying type） 的来源。 它可以是原始数值、引用类型，或带上界的类型参数。 “只有一个属性”限制的是当前内联表示，不表示被引用对象本身不可变或只有一个字段。

表示由使用位置决定

编译器为每个值类保留包装类，同时尽量在允许的位置使用底层值。 直接接收 OrderId 的 JVM 函数通常可接收它的底层 long，成员调用也可编译成处理底层值的静态方法。 这是一种编译策略，不是源码层面可以观察或依赖的对象布局契约。

实例以另一种类型使用时，通常要进行 装箱（boxing） 。 典型边界包括泛型类型参数、实现的接口、Any，以及底层值无法同时表达 null 的可空值类。 同一个源码值可能在一处使用底层表示，在另一处使用包装表示。

表示切换不会取消 Kotlin 的静态类型检查。 装箱后的 UserId 仍不是 OrderId，拆箱后返回 UserId 的泛型函数也不会把它变成 Long。 它只改变运行时承载方式，并可能改变分配与调用成本。

成员、相等性与标识

值类可以声明成员函数、实现接口方法和重写 toString()。 编译器基于唯一数据属性提供 equals() 与 hashCode()；当前规则不允许值类自行重写这两个成员。 使用 == 比较同一值类的值，语义与底层属性的值相等性一致。

值类没有可依赖的引用标识，因为同一个值可能被内联，也可能被包装为不同对象。 因此，不要用 === 或 !== 推断两个值类值是否来自同一个构造调用。 Kotlin 编译器会拒绝许多这样的比较，即使某种写法通过，其结果也不是领域语义。

val 只禁止重新赋值主构造函数属性。 如果底层值是 MutableList 或其他可变对象，其内容仍能变化，继而改变基于底层值生成的相等性和哈希。 值类不是深不可变容器。

示例

下面四个程序都是独立文件。 它们已使用 Kotlin 2.4.10 编译器编译，并在 JRE 21 上运行；紧随代码的输出来自实际执行。 代码块没有浏览器运行标记，因为本站的浏览器运行器不执行 Kotlin。

区分相同的底层类型

第一个例子让两个 Long 承担不同角色。 Order 的构造函数因此写出了字段含义，而不是依赖参数顺序和命名约定。

第二行输出说明两个包装值的原始 Long 可以相等。 它们在源码中仍属于不同类型，所以相等的位模式不会让 OrderId 自动兼容 UserId。 注释中的调用若取消注释，第二个参数会在编译期报告类型不匹配。

这个边界也让重构更安全。 字段或参数更名只能改善提示，独立类型则让编译器检查每个调用点。 在数据库、JSON 或 URL 边界解包仍是显式操作，代码审查可以看到类型安全从哪里开始、在哪里结束。

在构造边界建立不变量

值类可以让已经规范化并通过校验的字符串拥有专用类型。 私有主构造函数阻止同一模块中的普通调用点绕过 parse()。

@JvmInline
value class EmailAddress private constructor(val value: String) {
    init {
        require('@' in value) { "email must contain @" }
        require(value.none(Char::isWhitespace)) { "email must not contain whitespace" }
    }

    val domain: String
        get() = value.substringAfter('@')

    companion object {
        fun parse(raw: String): EmailAddress =
            EmailAddress(raw.trim().lowercase())
    }
}

fun main() {
    val email = EmailAddress.parse("  [email protected] ")
    println(email.value)
    println(email.domain)

    val message = runCatching { EmailAddress.parse("missing-at-sign") }
        .exceptionOrNull()
        ?.message
    println(message)
}

[email protected]
example.com
email must contain @

parse() 先修剪并统一大小写，随后由 init 检查构造结果。 成功返回 EmailAddress 后，使用方不必重复检查空白或 @。 失败仍是公开 API 的一部分；若输入错误属于正常分支，可以提供返回可空值或领域结果类型的另一个工厂。

这里的规则只是教学用的最小约束，不是完整邮箱标准。 值类不会把简单的字符串判断升级为标准验证器，也不会自动改变 JSON 或数据库格式。 真实边界仍要明确决定解析、错误报告与序列化方式。

观察装箱边界

下一个值类实现接口，并分别穿过泛型、可空和接口参数。 这些函数内部通过 JVM 类名观察到包装表示。

interface Renderable {
    fun render(): String
}

@JvmInline
value class CustomerId(val value: Long) : Renderable {
    override fun render(): String = "customer-$value"
}

fun <T : Any> describeGeneric(value: T): String =
    "${value.javaClass.simpleName}:$value"

fun describeNullable(value: CustomerId?): String =
    "${value?.javaClass?.simpleName}:$value"

fun describeInterface(value: Renderable): String =
    "${value.javaClass.simpleName}:${value.render()}"

fun main() {
    val id = CustomerId(7)

    println(id.render())
    println(describeGeneric(id))
    println(describeNullable(id))
    println(describeInterface(id))
}

customer-7
CustomerId:CustomerId(value=7)
CustomerId:CustomerId(value=7)
CustomerId:customer-7

直接的 id.render() 可以使用值类自身的表示。 另外三次调用要求值充当 T、CustomerId? 或 Renderable，运行时因此能看到名为 CustomerId 的包装类。 默认 toString() 也把类名和底层属性写进输出。

这段输出证明这些具体调用存在包装表示，却不是微基准。 JIT 仍可能消除某些临时分配，其他后端的表示规则也不同。 如果成本影响目标服务，应在相同编译选项、后端和调用形状下测量，而不是从类名推算速度。

给 Java 一个稳定入口

值类参数会参与 JVM 名称修饰。 @JvmName 可以给采用底层表示的顶层函数指定一个合法且稳定的 Java 名称。

@file:JvmName("OrderQueries")

@JvmInline
value class OrderId(val value: Long)

@JvmName("findOrderById")
fun findOrder(id: OrderId): String = "order-${id.value}"

fun main() {
    println(findOrder(OrderId(42)))
}

order-42

对编译产物运行 javap，可以看到 OrderQueries.findOrderById(long)。 Java 调用方传入 long，而 Kotlin 实现立即恢复 OrderId 的领域边界。 这种桥接适合只需传递底层表示的稳定 Java API。

Kotlin 2.4.10 还提供实验性的 @JvmExposeBoxed 与模块级 -Xjvm-expose-boxed，用于生成 Java 可访问的包装构造函数和装箱方法变体。 它们需要 ExperimentalStdlibApi 选择加入。 是否暴露装箱 API 是 ABI 设计决定，不应为了方便 Java 调用而在整个模块中无差别开启。

陷阱

修复方法： 先按类型安全设计接口，再定位实际热路径。 使用目标 Kotlin 版本的编译产物和分析器确认装箱，并用贴近生产调用形状的基准判断它是否重要。

修复方法： 作为哈希键或长期值使用时，让整条相等性对象图保持稳定。 在构造边界复制可变输入，或包装真正不可变的表示；不要把只读接口误当作没有别名的保证。

修复方法： 不变量必须统一时，限制主构造函数可见性，并让所有公开工厂经过同一校验路径。 同时测试大小写、前后空白、空值和边界值，确认每个入口产生一致结果。

修复方法： 使用 == 表达值相等，并为底层类型选择正确的相等性语义。 若业务需要独立实体标识，把标识本身放进值类，用该值比较，而不是比较包装对象引用。

修复方法： 为底层表示提供带 @JvmName 的明确桥接，或在接受实验性 ABI 后有选择地使用 @JvmExposeBoxed。 用 javap 检查发布产物，并从 Java 测试源码实际编译调用点。

修复方法： 敏感值需要明确的允许字段日志策略，而不只是重写一个显示方法。 可以重写 toString() 降低意外泄漏风险，但序列化、调试器、反射和显式属性访问仍要单独审查。

延伸阅读

• Kotlin 文档：内联值类
• Kotlin 文档：从 Java 调用 Kotlin
• Kotlin 语言规范：值类声明
• Kotlin 文档：相等性