内联值类

内联值类（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文档：相等性