内联类（value class）

本文档对标 MIT 6.005、Stanford CS193P、CMU 15-410 教学水准，系统讲解 Kotlin 内联类（@JvmInline value class）从设计哲学到 JVM 字节码实现的完整链路。内容覆盖 Kotlin 1.3 inline class 实验性、1.5 value class 稳定化，以及与 C# struct、Scala AnyVal、Rust struct 的跨语言对比。

目录

1. 学习目标
2. 历史动机与发展脉络
3. 形式化定义
4. 理论推导与原理解析
5. 代码示例
6. 对比分析
7. 常见陷阱与最佳实践
8. 工程实践
9. 案例研究
10. 习题
11. 参考文献
12. 延伸阅读

1. 学习目标

本章节遵循 Bloom 教育目标分类学（Bloom’s Taxonomy）的六个认知层级，由低阶到高阶逐层递进。

1.1 Remember（记忆）

完成本章节后，学习者应能够准确记忆以下知识点：

• 复述 Kotlin 内联类的语法形式 @JvmInline value class ClassName(val property: Type)。
• 列举内联类的三个核心约束：单一属性、不能继承、JVM 平台必须加 @JvmInline。
• 背诵 Kotlin 1.5 是 value class 稳定化的版本，1.3 是 inline class 引入的版本。
• 列举内联类的底层表示：基础类型直接替换、装箱场景的退化。
• 记忆 UInt、ULong、UByte、UShort 等无符号整型是基于 value class 实现的。

1.2 Understand（理解）

完成本章节后，学习者应能够解释以下概念：

• 用自己的语言解释”零开销抽象”（Zero-cost Abstraction）的语义含义与实现机制。
• 描述内联类在编译期被”展开”为底层类型的过程，并能画出编译前后的对比图。
• 解释 equals、hashCode、toString 在内联类中的自动生成规则。
• 阐述内联类与 data class 在内存表示、性能、API 设计上的核心差异。
• 理解内联类在泛型、可空、集合等”装箱场景”中退化为对象类型的根本原因（JVM 类型擦除）。

1.3 Apply（应用）

完成本章节后，学习者应能够在以下场景中应用内联类：

• 为业务领域建模创建类型安全的标识符，如 UserId(val id: Long)、OrderId(val id: String)，避免类型混淆。
• 为度量值建模创建零开销的物理量类型，如 Meter(val value: Double)、Kilogram(val value: Double)。
• 替代 data class Wrapper(val value: T)，消除装箱开销。
• 在 Android 项目中为 Int、Long 等基础类型添加语义化包装。
• 在 KMP 项目中使用内联类统一跨平台的类型表示。

1.4 Analyze（分析）

完成本章节后，学习者应能够进行以下分析：

• 反编译一段 Kotlin 代码，分析内联类编译后的字节码结构，识别装箱点（Boxing Site）。
• 对比同一问题在”内联类方案”、“data class 方案”、” typealias 方案”下的字节码体积与运行时性能。
• 分析 kotlin-stdlib 中 UInt、Duration 等内联类的实现源码，总结其设计模式。
• 解构内联类在 when 表达式、is 检查、智能转换中的行为差异。

1.5 Evaluate（评价）

完成本章节后，学习者应能够评价以下设计决策：

• 评价 JetBrains 在 Kotlin 1.5 将 inline class 重命名为 value class 的设计权衡。
• 评价 Kotlin 内联类与 C# struct、Scala AnyVal 在内存模型与性能上的差异。
• 评价内联类在库设计中作为公共 API 的风险：装箱退化、二进制兼容性、序列化。
• 评价内联类限制（单一属性、不能继承）对表达能力的影响。

1.6 Create（创造）

完成本章节后，学习者应能够创造以下作品：

• 设计并实现一个零开销的物理量库，覆盖长度、质量、时间、温度等维度，支持单位转换与运算。
• 设计一个类型安全的 ID 系统，为不同业务实体（User、Order、Product）创建互不混淆的 ID 类型。
• 实现一个货币类型，结合 value class 与运算符重载，提供类型安全的金额计算。
• 撰写一份内联类在团队代码规范中的使用指南，明确”何时使用内联类、何时使用 data class”的决策树。

2. 历史动机与发展脉络

2.1 问题背景：装箱开销与类型安全矛盾

在 Kotlin 1.3 之前，若开发者希望为基本类型（如 Long、String）添加语义化包装，面临两难：

方案一：使用 typealias

typealias UserId = Long
typealias OrderId = Long

fun findUser(id: UserId): User
fun findOrder(id: OrderId): Order

// 问题：UserId 与 OrderId 实际是同一类型 Long，可以互换
val userId: UserId = 42L
findOrder(userId)  // 编译通过，但语义错误

方案二：使用 data class 包装

data class UserId(val id: Long)
data class OrderId(val id: Long)

fun findUser(id: UserId): User
fun findOrder(id: OrderId): Order

val userId = UserId(42L)
findOrder(userId)  // 编译错误，类型安全

// 问题：每次使用都会创建对象，存在装箱开销
val list = listOf(UserId(1), UserId(2), UserId(3))  // 三个 Long 装箱为三个 UserId 对象

typealias 牺牲了类型安全，data class 引入了装箱开销。Kotlin 团队希望找到”既类型安全又零开销”的方案，这就是内联类的诞生背景。

2.2 学术背景：Value Types 研究

内联类的理论基础来自编程语言理论中的值类型（Value Types）研究：

• Project Valhalla（OpenJDK）：Java 的值类型提案，引入 value class 实现摊平对象。
• Scala AnyVal（Scala 2.10+）：Scala 的值类，与 Kotlin 内联类设计高度相似。
• C# struct（C# 1.0）：值类型 struct，栈分配，无装箱（除非装箱到 object）。
• Swift Value Types：Swift 的 struct 与 enum，值语义，无引用计数开销。

Kotlin 内联类借鉴了 Scala AnyVal 的设计，但通过 @JvmInline 注解显式标记，避免 Scala 隐式解析的复杂性。

2.3 Kotlin 1.3（2018 年 10 月）：inline class 实验性引入

Kotlin 1.3 引入了 inline class 作为实验性特性：

// Kotlin 1.3
inline class UserId(val id: Long)

@OptIn(ExperimentalUnsignedTypes::class)
inline class UInt(val data: Int)

此时的 inline class 已经具备了核心语义：

1. 编译期为底层类型的别名。
2. 在需要时（泛型、可空、装箱场景）退化为对象。
3. 自动生成 equals、hashCode、toString。

但作为实验性特性，存在诸多限制：

• 不能有 init 块（1.4.30+ 解除）。
• 不能实现普通接口（1.4.30+ 部分支持）。
• 不能有 var 属性。
• 不能有多个构造属性。

2.4 Kotlin 1.4（2020 年 8 月）：Beta 与 init 块支持

Kotlin 1.4 将 inline class 提升为 Beta，并引入：

1. init 块支持：允许在内联类中添加初始化逻辑。

inline class Percentage(val value: Int) {
    init {
        require(value in 0..100) { "Percentage must be 0..100, was $value" }
    }
}

2. 接口实现：允许内联类实现接口。

interface Printable {
    fun print(): String
}

inline class Name(val value: String) : Printable {
    override fun print(): String = "Name: $value"
}

2.5 Kotlin 1.4.30（2021 年 2 月）：value class 引入

Kotlin 1.4.30 引入了 value class 关键字作为 inline class 的替代：

// 旧
inline class UserId(val id: Long)

// 新
@JvmInline
value class UserId(val id: Long)

value class 的设计目标：

1. 未来扩展：为非 JVM 平台的值类型预留语法（如 Kotlin/Native 的真正栈分配）。
2. 平台无关：value 是语言关键字，@JvmInline 是平台特定注解。
3. 语义清晰：value 强调”值语义”，inline 强调”编译期展开”，前者更准确。

2.6 Kotlin 1.5（2021 年 5 月）：value class GA

Kotlin 1.5 将 value class 提升为稳定状态（Stable，GA）：

• @JvmInline value class 在 JVM 平台完全稳定。
• inline class 关键字被废弃，但仍可用（迁移期）。
• 无符号整型 UInt、ULong、UByte、UShort 稳定化。
• Duration、Result 等标准库类型基于 value class 重构。

2.7 Kotlin 1.6-1.9（2021-2023 年）：稳定演进

Kotlin 1.6 至 1.9 期间，value class 持续完善：

1. K2 编译器适配：K2 对 value class 的 IR 优化更激进。
2. KMP 一致性：JVM、JS、Native、Wasm 平台行为一致。
3. 序列化支持：kotlinx.serialization 对 value class 完整支持。
4. Compose 集成：Compose Multiplatform 对 value class 友好。

2.8 Kotlin 2.0（2024 年 5 月）：K2 与 value class

Kotlin 2.0 的 K2 编译器对 value class 进行以下优化：

1. 更激进的展开：K2 在 IR 阶段更激进地展开 value class，减少装箱点。
2. 互操作改进：与 Java 的互操作更平滑，支持 Java 调用 Kotlin value class。
3. 诊断质量：更明确的装箱退化警告。
4. 跨平台一致：JVM、JS、Native、Wasm 行为完全一致。

2.9 JetBrains 的设计哲学

JetBrains 在设计 value class 时遵循了以下哲学：

1. 零开销优先：在不退化场景下，必须与底层类型性能一致。
2. 渐进式增强：从 inline class 到 value class，平滑迁移。
3. 平台无关：value class 是语言概念，@JvmInline 是平台实现。
4. 类型安全：编译期检查类型隔离，运行时退化但语义保留。
5. 最小惊讶：value class 的 equals、hashCode、toString 行为与 data class 一致。

2.10 时间线总览

2018  Kotlin 1.3 — inline class 实验性引入
2020  Kotlin 1.4 — inline class Beta，init 块支持
2021  Kotlin 1.4.30 — value class 引入，inline class 废弃
2021  Kotlin 1.5 — value class GA，无符号整型稳定
2022  Kotlin 1.7 — K2 预览，value class IR 优化
2023  Kotlin 1.9 — K2 Beta，value class 互操作改进
2024  Kotlin 2.0 — K2 GA，value class 性能大幅提升

3. 形式化定义

3.1 Kotlin 语言规范（Kotlin Language Specification）

根据 Kotlin 官方语言规范，value class 的形式化语法定义如下：

其中：

• $\text{modifiers?}$：可选的修饰符，如 public、private、internal。
• $\text{``@JvmInline''?}$：JVM 平台必须的注解，标记为内联类。
• $\text{ClassName}$：类名，遵循 Kotlin 标识符命名规则。
• $\text{PrimaryConstructor}$：主构造函数，必须且仅能有一个 val 属性。
• $\text{ClassBody?}$：可选的类体，可包含方法、init 块、计算属性。

3.2 主构造函数约束

value class 的主构造函数必须满足以下约束：

1. 单一属性：必须且仅能有一个 val 属性（不能是 var）。
2. 属性类型：可以是任何类型，包括基础类型、引用类型、泛型类型参数。
3. 可见性：默认 public，可改为 internal 或 private（Kotlin 1.6+）。

@JvmInline
value class UserId(val id: Long)  // 合法

@JvmInline
value class User(val name: String, val age: Int)  // 编译错误：多个属性

@JvmInline
value class Counter(var count: Int)  // 编译错误：var 属性

3.3 内联类的语义（Semantics）

对于 @JvmInline value class V(val v: T)，其语义可形式化定义为：

1. 类型层：V 与 T 是不同的类型，编译器拒绝直接赋值。
2. 表示层：在 JVM 运行时，V 的实例在”非装箱场景”中被表示为 T。
3. 行为层：V 的 equals、hashCode、toString 默认基于 v。

形式化地：

3.4 装箱规则（Boxing Rules）

当 value class 实例需要被当作对象处理时，会发生装箱（Boxing）。装箱场景包括：

1. 可空类型：V? 退化为 V 对象（因为 null 需要单独表示）。
2. 泛型类型参数：T 是 V 时，擦除为 Object。
3. 集合元素：List<V> 中的元素装箱。
4. 数组元素：Array<V> 中的元素装箱（使用 VArray 可避免，但目前实验性）。
5. Any 类型：转换为 Any 时装箱。

形式化地，装箱规则可以表示为：

3.5 JVM 字节码规范

在 JVM 平台上，value class 编译为 final 类，带有特殊标记。其字节码结构：

@JvmInline
public final class UserId {
    private final long id;

    public UserId(long id) {
        this.id = id;
    }

    public long getId() { return id; }

    // 装箱方法
    public static UserId box(long id) { return new UserId(id); }

    // 拆箱方法
    public static long unbox(UserId userId) { return userId.id; }

    // equals/hashCode/toString
    public boolean equals(Object o) { /* 基于 id */ }
    public int hashCode() { return Long.hashCode(id); }
    public String toString() { return String.valueOf(id); }
}

关键方法：

• box(long)：将底层类型装箱为 UserId 对象。
• unbox(UserId)：将 UserId 对象拆箱为底层 long。
• equals、hashCode、toString：基于底层值自动生成。

3.6 元数据注解

Kotlin 编译器在 value class 的字节码中添加特殊元数据：

• @kotlin.Metadata：标记为 Kotlin 类，包含 value class 信息。
• @JvmInline：标记为内联类，提示 JVM 后端进行优化。
• @SinceKotlin：标记引入版本。

3.7 与 data class 的形式化对比

4. 理论推导与原理解析

4.1 编译期转换（Compilation Transformation）

考虑以下 Kotlin value class：

@JvmInline
value class UserId(val id: Long)

fun findUser(id: UserId): User {
    // ...
}

编译器在非装箱场景下将其转换为底层类型：

// 编译后等价的 Kotlin 伪代码
fun findUser(id: Long): User {
    // ...
}

// 调用处
val user = findUser(42L)  // 直接传递 Long，无对象创建

转换过程的代数表示：

其中 $T_V$ 是 $V$ 的底层类型。

4.2 装箱点分析

考虑以下场景：

@JvmInline
value class UserId(val id: Long)

// 场景一：非装箱
fun findUser(id: UserId): User = ...  // 编译为 findUser(id: Long): User

// 场景二：可空装箱
fun findUserOrNull(id: UserId?): User? = ...  // 编译为 findUserOrNull(id: UserId): User?（对象）

// 场景三：泛型装箱
fun <T> identity(x: T): T = x
val result = identity(UserId(42L))  // 装箱为 UserId 对象

// 场景四：集合装箱
val list = listOf(UserId(1), UserId(2), UserId(3))  // 每个都装箱

形式化地，装箱点可以表示为：

4.3 equals 与 hashCode 的推导

value class 的 equals 和 hashCode 默认基于底层属性：

@JvmInline
value class UserId(val id: Long)

val a = UserId(42L)
val b = UserId(42L)
println(a == b)  // true，基于 id 比较
println(a.hashCode() == b.hashCode())  // true，基于 id 计算

字节码等价：

public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof UserId)) return false;
    return this.id == ((UserId) o).id;
}

public int hashCode() {
    return Long.hashCode(this.id);
}

形式化地：

4.4 自定义 equals 与 hashCode

value class 可以重写 equals 和 hashCode：

@JvmInline
value class Email(val value: String) {
    override fun equals(other: Any?): Boolean {
        if (other !is Email) return false
        return value.equals(other.value, ignoreCase = true)
    }

    override fun hashCode(): Int = value.lowercase().hashCode()
}

注意：自定义 equals 时，装箱不可避免（因为 equals 接收 Any?）。

4.5 init 块的执行时机

value class 的 init 块在构造时执行：

@JvmInline
value class Percentage(val value: Int) {
    init {
        require(value in 0..100) { "Percentage must be 0..100, was $value" }
    }
}

字节码层面，init 块的检查被编译为静态方法：

public static long constructorCheck(int value) {
    if (value < 0 || value > 100) {
        throw new IllegalArgumentException("Percentage must be 0..100, was " + value);
    }
    return value;  // 返回底层类型
}

形式化地，init 块可以表示为：

4.6 接口实现

value class 可以实现接口：

interface Comparable<T> {
    operator fun compareTo(other: T): Int
}

@JvmInline
value class Score(val value: Int) : Comparable<Score> {
    override fun compareTo(other: Score): Int = value.compareTo(other.value)
}

字节码层面，value class 实现接口时，需要生成桥接方法：

public final class Score implements Comparable<Score> {
    private final int value;

    // 非装箱调用
    public static int compareTo(int receiver, int other) {
        return Integer.compare(receiver, other);
    }

    // 装箱调用（接口分发）
    @Override
    public int compareTo(Score other) {
        return compareTo(this.value, other.value);
    }
}

4.7 与内联函数的协同

value class 与 inline 函数结合，可以进一步消除装箱：

@JvmInline
value class UserId(val id: Long)

inline fun <T> withUserId(userId: UserId, block: (UserId) -> T): T {
    return block(userId)
}

// 调用
val result = withUserId(UserId(42L)) { it.id }
// 内联展开后，UserId 不被装箱

形式化地：

4.8 K2 编译器的 IR 优化

Kotlin 2.0 的 K2 编译器在 IR 阶段对 value class 进行以下优化：

1. 装箱消除：识别不必要的装箱点，直接使用底层类型。
2. 方法内联：value class 的方法被内联到调用处。
3. 桥接方法消除：减少接口分发的桥接方法。
4. 逃逸分析：识别不逃逸的对象，栈上分配。

数学上，K2 的 IR 优化可以建模为：

4.9 二进制兼容性

value class 的二进制兼容性需要注意：

• 添加新方法：兼容。
• 修改底层类型：不兼容（如 Long 改为 String）。
• 添加接口：可能不兼容（字节码变化）。
• 添加 init 块：兼容（运行时检查变化）。

形式化地：

4.10 反射与 value class

value class 在反射中的行为：

@JvmInline
value class UserId(val id: Long)

val kClass = UserId::class
println(kClass.isValue)  // true (Kotlin 1.5+)
println(kClass.primaryConstructor?.parameters?.first()?.type)  // Long

注意：反射操作通常会触发装箱。

5. 代码示例

5.1 基础示例：类型安全 ID

package com.example.ids

/**
 * 类型安全的用户 ID，避免与 OrderId 混淆
 */
@JvmInline
value class UserId(val id: Long) {
    override fun toString(): String = "User($id)"
}

@JvmInline
value class OrderId(val id: Long) {
    override fun toString(): String = "Order($id)"
}

@JvmInline
value class ProductId(val id: String) {
    override fun toString(): String = "Product($id)"
}

fun findUser(id: UserId): String = "User ${id.id}"
fun findOrder(id: OrderId): String = "Order ${id.id}"

fun main() {
    val userId = UserId(42L)
    val orderId = OrderId(100L)

    println(findUser(userId))    // "User 42"
    println(findOrder(orderId))  // "Order 100"

    // findUser(orderId)  // 编译错误：类型不匹配
    // findOrder(userId)  // 编译错误：类型不匹配
}

5.2 物理量建模

package com.example.physics

/**
 * 物理量建模，零开销的类型安全
 */
@JvmInline
value class Meter(val value: Double) {
    operator fun plus(other: Meter): Meter = Meter(value + other.value)
    operator fun minus(other: Meter): Meter = Meter(value - other.value)
    fun toKilometer(): Double = value / 1000.0
    fun toCentimeter(): Double = value * 100.0
}

@JvmInline
value class Kilogram(val value: Double) {
    operator fun plus(other: Kilogram): Kilogram = Kilogram(value + other.value)
    fun toGram(): Double = value * 1000.0
}

@JvmInline
value class Second(val value: Double) {
    fun toMillisecond(): Double = value * 1000.0
}

fun main() {
    val d1 = Meter(10.0)
    val d2 = Meter(5.5)
    val total = d1 + d2
    println(total.value)  // 15.5
    println(total.toKilometer())  // 0.0155
}

5.3 init 块验证

package com.example.validation

/**
 * 使用 init 块进行参数验证
 */
@JvmInline
value class Percentage(val value: Int) {
    init {
        require(value in 0..100) { "Percentage must be 0..100, was $value" }
    }
}

@JvmInline
value class Email(val value: String) {
    init {
        require(value.contains('@')) { "Invalid email: $value" }
        require(value.length <= 255) { "Email too long: ${value.length}" }
    }
}

@JvmInline
value class PositiveInt(val value: Int) {
    init {
        require(value > 0) { "Value must be positive, was $value" }
    }
}

fun main() {
    val p = Percentage(50)  // OK
    // val p2 = Percentage(150)  // IllegalArgumentException

    val email = Email("test@example.com")  // OK
    // val email2 = Email("invalid")  // IllegalArgumentException
}

5.4 接口实现

package com.example.interfaces

interface Measurable {
    val amount: Double
    fun toBaseUnit(): Double
}

interface Comparable<T> {
    operator fun compareTo(other: T): Int
}

@JvmInline
value class Celsius(val value: Double) : Measurable {
    override val amount: Double get() = value
    override fun toBaseUnit(): Double = value + 273.15  // Kelvin
}

@JvmInline
value class Score(val value: Int) : Comparable<Score> {
    override fun compareTo(other: Score): Int = value.compareTo(other.value)
}

fun main() {
    val c = Celsius(25.0)
    println(c.toBaseUnit())  // 298.15

    val s1 = Score(80)
    val s2 = Score(90)
    println(s1 < s2)  // true
}

5.5 与扩展函数协同

package com.example.ext

@JvmInline
value class UserId(val id: Long)

// 扩展函数
fun UserId.isValid(): Boolean = id > 0
fun UserId.toDisplayString(): String = "#${id.toString(16)}"

@JvmInline
value class Meter(val value: Double)

fun Meter.format(precision: Int = 2): String = "${"%.${precision}f".format(value)}m"

fun main() {
    val userId = UserId(42L)
    println(userId.isValid())  // true
    println(userId.toDisplayString())  // "#2a"

    val m = Meter(3.14159)
    println(m.format())  // "3.14m"
}

5.6 无符号整型（标准库实现）

package com.example.unsigned

// Kotlin 标准库中的 UInt 等就是 value class 实现
// 实际定义：
// @JvmInline
// value class UInt(val data: Int)

fun main() {
    val a: UInt = 42u
    val b: ULong = 100UL
    val c: UByte = 255u.toUByte()
    val d: UShort = 65535u.toUShort()

    println(a + 10u)  // 52
    println(b * 2UL)  // 200

    // 无符号整型的优势：避免负数
    val bytes = 4_294_967_295u  // 0xFFFFFFFF
    println(bytes)  // 4294967295（而非 -1）
}

5.7 Duration 类型（标准库）

package com.example.duration

// kotlin.time.Duration 实际上是基于 value class 实现
import kotlin.time.Duration
import kotlin.time.Duration.Companion.seconds
import kotlin.time.Duration.Companion.milliseconds

fun main() {
    val d1 = 5.seconds
    val d2 = 500.milliseconds

    val total = d1 + d2
    println(total.inWholeMilliseconds)  // 5500
    println(total.inWholeSeconds)  // 5
}

5.8 企业级 Gradle 配置

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.0.0"
    `maven-publish`
    kotlin("plugin.serialization") version "2.0.0"
}

dependencies {
    implementation(kotlin("stdlib"))
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3")
    testImplementation(kotlin("test"))
}

kotlin {
    jvmToolchain(17)
    compilerOptions {
        freeCompilerArgs.add("-opt-in=kotlin.RequiresOptIn")
        freeCompilerArgs.add("-Xinline-classes")
    }
}

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
    kotlinOptions {
        jvmTarget = "17"
    }
}

5.9 序列化支持

package com.example.serialization

import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json

@Serializable
data class UserDto(
    val id: UserId,
    val email: Email,
    val name: String
)

@JvmInline
@Serializable
value class UserId(val value: Long)

@JvmInline
@Serializable
value class Email(val value: String)

fun main() {
    val user = UserDto(UserId(42), Email("test@example.com"), "Alice")
    val json = Json.encodeToString(UserDto.serializer(), user)
    println(json)  // {"id":42,"email":"test@example.com","name":"Alice"}

    val decoded = Json.decodeFromString(UserDto.serializer(), json)
    println(decoded == user)  // true
}

5.10 货币类型（生产级示例）

package com.example.money

import java.math.BigDecimal

@JvmInline
value class Money(val amount: BigDecimal) : Comparable<Money> {
    operator fun plus(other: Money): Money = Money(amount.add(other.amount))
    operator fun minus(other: Money): Money = Money(amount.subtract(other.amount))
    operator fun times(factor: Int): Money = Money(amount.multiply(BigDecimal(factor)))
    operator fun times(factor: Double): Money = Money(amount.multiply(BigDecimal(factor)))
    operator fun compareTo(other: Money): Int = amount.compareTo(other.amount)

    fun format(currency: String = "CNY"): String {
        return "$currency ${amount.toPlainString()}"
    }
}

@JvmInline
value class Currency(val code: String) {
    init {
        require(code.length == 3) { "Currency code must be 3 letters: $code" }
    }
}

class Wallet {
    private val balances = mutableMapOf<Currency, Money>()

    fun deposit(currency: Currency, amount: Money) {
        balances[currency] = (balances[currency] ?: Money(BigDecimal.ZERO)) + amount
    }

    fun withdraw(currency: Currency, amount: Money): Boolean {
        val current = balances[currency] ?: return false
        if (current < amount) return false
        balances[currency] = current - amount
        return true
    }

    fun balance(currency: Currency): Money = balances[currency] ?: Money(BigDecimal.ZERO)
}

fun main() {
    val wallet = Wallet()
    val cny = Currency("CNY")
    wallet.deposit(cny, Money(BigDecimal("100.00")))
    wallet.deposit(cny, Money(BigDecimal("50.50")))
    println(wallet.balance(cny).format())  // "CNY 150.50"

    wallet.withdraw(cny, Money(BigDecimal("30.00")))
    println(wallet.balance(cny).format())  // "CNY 120.50"
}

5.11 测试 value class

package com.example.test

import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith
import kotlin.test.assertTrue

class UserIdTest {
    @Test
    fun `UserId should be equal when id is same`() {
        val a = UserId(42L)
        val b = UserId(42L)
        assertEquals(a, b)
        assertEquals(a.hashCode(), b.hashCode())
    }

    @Test
    fun `UserId should not be equal when id differs`() {
        assertNotEquals(UserId(1L), UserId(2L))
    }

    @Test
    fun `Percentage should reject values outside 0-100`() {
        assertFailsWith<IllegalArgumentException> { Percentage(-1) }
        assertFailsWith<IllegalArgumentException> { Percentage(101) }
    }
}

@JvmInline
value class UserId(val id: Long)

@JvmInline
value class Percentage(val value: Int) {
    init {
        require(value in 0..100)
    }
}

5.12 KMP 跨平台使用

// commonMain
@JvmInline
value class PlatformInfo(val value: String)

expect fun getPlatformInfo(): PlatformInfo

// jvmMain
actual fun getPlatformInfo() = PlatformInfo("JVM ${System.getProperty("java.version")}")

// jsMain
actual fun getPlatformInfo() = PlatformInfo("JavaScript ${js("typeof navigator !== 'undefined' ? navigator.userAgent : 'Node.js'")}")

// iosMain
actual fun getPlatformInfo() = PlatformInfo("iOS")

5.13 运算符重载

package com.example.operators

@JvmInline
value class Vector2(val x: Double) {
    // 注：实际 Vector2 需要 x 和 y，value class 仅支持单一属性
    // 这里演示概念，实际应使用 data class
}

// 正确用法：单维度值
@JvmInline
value class Radians(val value: Double) {
    operator fun plus(other: Radians): Radians = Radians(value + other.value)
    operator fun minus(other: Radians): Radians = Radians(value - other.value)
    operator fun times(scalar: Double): Radians = Radians(value * scalar)

    fun toDegrees(): Double = Math.toDegrees(value)
    fun sin(): Double = Math.sin(value)
    fun cos(): Double = Math.cos(value)
}

fun main() {
    val angle = Radians(Math.PI / 4)
    println(angle.sin())  // 0.7071...
    println(angle.toDegrees())  // 45.0
}

5.14 与 sealed class 协同

package com.example.sealed

sealed class Event {
    abstract val timestamp: Long
}

@JvmInline
value class ClickEvent(val elementId: String) : Event() {
    override val timestamp: Long = System.currentTimeMillis()
}

@JvmInline
value class ScrollEvent(val deltaY: Int) : Event() {
    override val timestamp: Long = System.currentTimeMillis()
}

// 注意：value class 不能继承 sealed class（在 Kotlin 1.5+ 中有限支持）
// 上述代码仅为概念演示，实际可能需要调整

5.15 完整生产级示例：领域建模

package com.example.domain

import java.math.BigDecimal
import java.time.Instant

// 类型安全的标识符
@JvmInline
value class UserId(val value: Long) {
    override fun toString() = "User($value)"
}

@JvmInline
value class ProductId(val value: String) {
    override fun toString() = "Product($value)"
}

@JvmInline
value class OrderId(val value: String) {
    override fun toString() = "Order($value)"
}

// 类型安全的度量
@JvmInline
value class Quantity(val value: Int) {
    init {
        require(value >= 0) { "Quantity must be non-negative" }
    }
    operator fun plus(other: Quantity) = Quantity(value + other.value)
    operator fun minus(other: Quantity) = Quantity(value - other.value)
}

@JvmInline
value class Price(val amount: BigDecimal) {
    init {
        require(amount >= BigDecimal.ZERO) { "Price must be non-negative" }
    }
    operator fun times(quantity: Quantity): Price = Price(amount.multiply(BigDecimal(quantity.value)))
    operator fun plus(other: Price): Price = Price(amount.add(other.amount))
}

// 领域模型
data class Order(
    val id: OrderId,
    val userId: UserId,
    val items: List<OrderItem>,
    val createdAt: Instant
)

data class OrderItem(
    val productId: ProductId,
    val quantity: Quantity,
    val unitPrice: Price
) {
    val subtotal: Price get() = unitPrice * quantity
}

class OrderService {
    fun calculateTotal(order: Order): Price {
        return order.items.fold(Price(BigDecimal.ZERO)) { acc, item ->
            acc + item.subtotal
        }
    }
}

fun main() {
    val order = Order(
        id = OrderId("ORD-001"),
        userId = UserId(42L),
        items = listOf(
            OrderItem(ProductId("P-1"), Quantity(2), Price(BigDecimal("10.00"))),
            OrderItem(ProductId("P-2"), Quantity(3), Price(BigDecimal("5.50")))
        ),
        createdAt = Instant.now()
    )

    val service = OrderService()
    val total = service.calculateTotal(order)
    println("Total: ${total.amount}")  // 36.50
}

6. 对比分析

6.1 与 data class 的对比

// value class
@JvmInline
value class UserIdV(val id: Long)

// data class
data class UserIdD(val id: Long)

6.2 与 typealias 的对比

typealias UserIdT = Long

@JvmInline
value class UserIdV(val id: Long)

6.3 与 C# struct 的对比

// C# struct
public struct UserId
{
    public long Value { get; }

    public UserId(long value)
    {
        Value = value;
    }
}

6.4 与 Scala AnyVal 的对比

// Scala AnyVal
class UserId(val id: Long) extends AnyVal

6.5 与 Rust struct 的对比

// Rust struct
struct UserId(i64);

impl UserId {
    fn new(id: i64) -> Self {
        UserId(id)
    }
}

6.6 跨语言对比总表

7. 常见陷阱与最佳实践

7.1 陷阱一：误以为完全没有装箱

误解：value class 完全没有装箱开销。

事实：value class 在以下场景会装箱：

1. 可空类型 V?。
2. 泛型类型参数 T 接收 V。
3. 集合 List<V>、Set<V>、Map<K, V> 中的元素。
4. 数组 Array<V>。
5. 转换为 Any。

@JvmInline
value class UserId(val id: Long)

fun main() {
    val a = UserId(1)  // 不装箱
    val b: UserId? = UserId(2)  // 装箱
    val list = listOf(UserId(3), UserId(4))  // 装箱
    val any: Any = UserId(5)  // 装箱
}

7.2 陷阱二：泛型方法中的装箱

错误代码：

@JvmInline
value class UserId(val id: Long)

fun <T> process(value: T): T = value  // T 会擦除为 Object，UserId 装箱

fun main() {
    val userId = UserId(42)
    val result = process(userId)  // 装箱
}

解决方案：使用 inline 函数 + reified 类型参数。

inline fun <reified T> processInline(value: T): T = value

fun main() {
    val userId = UserId(42)
    val result = processInline(userId)  // 内联展开，不装箱
}

7.3 陷阱三：集合中的装箱

问题：

@JvmInline
value class UserId(val id: Long)

val list = listOf(UserId(1), UserId(2), UserId(3))  // 每个元素都装箱

解决方案：使用原生数组或 LongArray。

// 方案一：使用 LongArray 直接存储
val ids = longArrayOf(1, 2, 3)

// 方案二：使用 inline 函数包装
inline fun List<Long>.asUserIdList(): List<UserId> = this.map { UserId(it) }

7.4 陷阱四：可空类型的装箱

问题：

@JvmInline
value class UserId(val id: Long)

fun findUser(id: UserId?): User?  // 参数 id 会装箱

原因：可空类型需要表示 null，而 Long 不能为 null，因此退化为对象。

解决方案：使用哨兵值或 Long? 替代。

// 方案一：使用 Long 直接
fun findUser(id: Long): User?

// 方案二：使用包装类
data class UserIdBox(val value: UserId?)

7.5 陷阱五：修改底层类型不兼容

问题：

// 库 v1.0
@JvmInline
value class UserId(val id: Long)

// 库 v2.0
@JvmInline
value class UserId(val id: String)  // 二进制不兼容

调用方在运行时报 NoSuchMethodError。

最佳实践：使用 @Deprecated 渐进式迁移。

7.6 陷阱六：与反射结合的装箱

问题：

@JvmInline
value class UserId(val id: Long)

fun main() {
    val kClass = UserId::class
    val userId = UserId(42)
    // 反射调用通常会触发装箱
}

原因：反射 API 接收 Any?，强制装箱。

7.7 陷阱七：序列化兼容性

问题：默认 Java 序列化可能不正确处理 value class。

解决方案：使用 kotlinx.serialization，它对 value class 有完整支持。

@Serializable
@JvmInline
value class UserId(val value: Long)

@Serializable
data class User(val id: UserId, val name: String)

7.8 陷阱八：与 Java 互操作

问题：Java 代码调用 Kotlin value class 时，可能需要显式装箱。

// Java 代码
UserId userId = UserId.box-impl(42L);  // 装箱
long id = UserId.unbox-impl(userId);  // 拆箱

最佳实践：在公共 API 中避免直接暴露 value class，或使用 @JvmName 优化。

7.9 陷阱九：init 块的副作用

问题：init 块在每次构造时执行，可能有性能影响。

@JvmInline
value class ValidatedString(val value: String) {
    init {
        // 复杂的验证逻辑
        require(value.matches(Regex("^[a-zA-Z0-9]+$")))
    }
}

最佳实践：将验证逻辑保持在最简，或将验证移到构造工厂方法。

7.10 陷阱十：value class 的递归

问题：value class 不能递归引用自身。

@JvmInline
value class Recursive(val inner: Recursive)  // 编译错误

原因：递归会导致无限展开。

7.11 最佳实践总结

1. 优先使用 value class 替代 typealias：当需要类型安全时。
2. 避免在泛型场景使用：泛型场景会装箱。
3. 谨慎使用可空类型：会触发装箱。
4. 使用 inline 函数避免装箱：结合 reified 类型参数。
5. 考虑二进制兼容性：不轻易修改底层类型。
6. 使用 kotlinx.serialization：替代 Java 默认序列化。
7. 避免在公共 API 暴露：Java 互操作复杂。
8. 文档化装箱场景：明确说明何时会装箱。

8. 工程实践

8.1 构建配置

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.0.0"
    kotlin("plugin.serialization") version "2.0.0"
}

kotlin {
    jvmToolchain(17)
    compilerOptions {
        freeCompilerArgs.add("-opt-in=kotlin.RequiresOptIn")
        freeCompilerArgs.add("-Xinline-classes")
    }
}

8.2 性能基准测试

package com.example.benchmark

import org.openjdk.jmh.annotations.*
import java.util.concurrent.TimeUnit

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.NANOSECONDS)
@State(Scope.Benchmark)
open class ValueClassBenchmark {

    @JvmInline
    value class UserId(val id: Long)

    @Benchmark
    fun benchmarkValueClass(): Long {
        val userId = UserId(42)
        return userId.id
    }

    @Benchmark
    fun benchmarkDataClass(): Long {
        val userId = UserIdData(42)
        return userId.id
    }

    @Benchmark
    fun benchmarkPrimitive(): Long {
        return 42L
    }
}

data class UserIdData(val id: Long)

8.3 调试 value class

在 IntelliJ IDEA 中调试 value class：

1. 在 value class 的方法或 init 块中打断点。
2. 调试器会显示 value class 实例的底层值。
3. 使用 Evaluate Expression 查看表达式。

8.4 Kotlin/Native 中的 value class

// Kotlin/Native 中 value class 的内存模型
// - 完全栈分配（无对象头）
// - 无 GC 压力
// - 与 C ABI 兼容

// commonMain
@JvmInline
value class NativeString(val value: String)

// nativeMain
fun processString(s: NativeString) {
    // 直接使用底层 String
}

8.5 KMP（Kotlin Multiplatform）中的 value class

// commonMain
@JvmInline
value class PlatformInfo(val value: String)

expect fun getPlatform(): PlatformInfo

// jvmMain
actual fun getPlatform() = PlatformInfo("JVM")

// jsMain
actual fun getPlatform() = PlatformInfo("JS")

// iosMain
actual fun getPlatform() = PlatformInfo("iOS")

8.6 代码生成与注解处理

// 使用 KSP 生成 value class
@GenerateValueClass
annotation class MyAnnotation

@MyAnnotation
data class MyData(val id: Long)

// KSP 生成：
// @JvmInline
// value class MyDataId(val value: Long)

8.7 序列化策略

import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json

@Serializable
@JvmInline
value class UserId(val value: Long)

@Serializable
data class User(val id: UserId, val name: String)

fun main() {
    val user = User(UserId(42), "Alice")
    val json = Json.encodeToString(User.serializer(), user)
    println(json)  // {"id":42,"name":"Alice"}

    val decoded = Json.decodeFromString(User.serializer(), json)
    println(decoded)
}

8.8 测试策略

package com.example.test

import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith

class ValueClassTest {
    @Test
    fun `UserId equality`() {
        assertEquals(UserId(1), UserId(1))
        assertNotEquals(UserId(1), UserId(2))
    }

    @Test
    fun `Percentage validation`() {
        assertFailsWith<IllegalArgumentException> { Percentage(-1) }
        assertFailsWith<IllegalArgumentException> { Percentage(101) }
        Percentage(0)
        Percentage(100)
    }
}

@JvmInline
value class UserId(val id: Long)

@JvmInline
value class Percentage(val value: Int) {
    init {
        require(value in 0..100)
    }
}

9. 案例研究

9.1 案例一：kotlin-stdlib 中的 UInt

// kotlin-stdlib 源码
@JvmInline
value class UInt(val data: Int) : Comparable<UInt> {
    override fun compareTo(other: UInt): Int = data.compareTo(other.data)

    operator fun plus(other: UInt): UInt = UInt(data + other.data)
    operator fun minus(other: UInt): UInt = UInt(data - other.data)
    operator fun times(other: UInt): UInt = UInt(data * other.data)

    // ...
}

设计要点：

1. 单一属性 data: Int，零开销。
2. 实现 Comparable<UInt>，支持比较。
3. 重载运算符，提供自然语法。

9.2 案例二：kotlin.time.Duration

// kotlin.time.Duration 实际定义（简化）
@JvmInline
value class Duration(val rawValue: Long) : Comparable<Duration> {
    val inWholeSeconds: Long get() = rawValue / 1_000_000_000
    val inWholeMilliseconds: Long get() = rawValue / 1_000_000

    operator fun plus(other: Duration): Duration = Duration(rawValue + other.rawValue)
    operator fun minus(other: Duration): Duration = Duration(rawValue - other.rawValue)

    // ...
}

设计要点：

1. 使用 Long 存储纳秒值，零开销。
2. 提供多种单位转换（秒、毫秒、微秒）。
3. 支持运算符重载，自然语法。

9.3 案例三：Arrow-kt 的类型类

// Arrow-kt 库中使用 value class 实现类型安全
@JvmInline
value class NonEmptyString(val value: String) {
    init {
        require(value.isNotEmpty()) { "String must not be empty" }
    }
}

@JvmInline
value class PositiveInt(val value: Int) {
    init {
        require(value > 0) { "Int must be positive" }
    }
}

9.4 案例四：领域驱动设计（DDD）

// DDD 中的值对象
@JvmInline
value class EmailAddress(val value: String) {
    init {
        require(value.matches(Regex("^[^@]+@[^@]+\\.[^@]+$"))) { "Invalid email" }
    }
}

@JvmInline
value class PhoneNumber(val value: String) {
    init {
        require(value.matches(Regex("^\\+?[0-9]{10,15}$"))) { "Invalid phone" }
    }
}

@JvmInline
value class Address(val value: String)

data class User(
    val email: EmailAddress,
    val phone: PhoneNumber,
    val address: Address
)

9.5 案例五：Spring Boot 集成

package com.example.spring

import org.springframework.data.jpa.repository.JpaRepository
import org.springframework.stereotype.Service
import javax.persistence.Entity
import javax.persistence.Id

@JvmInline
value class UserId(val value: Long)

@Entity
data class UserEntity(
    @Id val id: Long,
    val name: String,
    val email: String
)

interface UserRepository : JpaRepository<UserEntity, Long>

@Service
class UserService(private val repo: UserRepository) {
    fun findById(id: UserId): UserEntity? {
        return repo.findById(id.value).orElse(null)
    }
}

10. 习题

10.1 选择题

题目 1：以下关于 Kotlin value class 的描述，哪一项是错误的？

A. value class 必须有且仅有一个 val 属性 B. value class 不能继承其他类 C. value class 在所有场景下都零开销 D. value class 在 JVM 平台需要 @JvmInline 注解

答案：C

解析：value class 在装箱场景（可空、泛型、集合、数组、Any）会退化为对象，存在装箱开销。

题目 2：以下代码的输出是？

@JvmInline
value class UserId(val id: Long)

fun main() {
    val a = UserId(42)
    val b = UserId(42)
    println(a == b)
    println(a.hashCode() == b.hashCode())
}

A. true, true B. false, false C. true, false D. false, true

答案：A

解析：value class 的 equals 和 hashCode 默认基于底层属性，因此 a == b 为 true，hashCode 相同。

题目 3：Kotlin 1.5 将 inline class 重命名为 value class 的主要原因是？

A. inline class 关键字过长 B. 为非 JVM 平台的真正值类型预留语法 C. inline 关键字被废弃 D. 性能优化

答案：B

解析：value class 是语言关键字，@JvmInline 是 JVM 平台特定注解。这种分离为 Kotlin/Native 等平台实现真正的栈分配值类型预留了空间。

题目 4：以下哪种场景会触发 value class 的装箱？

A. 直接传递 value class 实例 B. value class 作为可空参数 C. value class 的方法调用 D. value class 的属性访问

答案：B

解析：可空类型 V? 需要表示 null，而底层类型（如 Long）不能为 null，因此退化为对象，触发装箱。

题目 5：Kotlin 标准库中的 UInt 实现基于？

A. typealias B. data class C. value class D. sealed class

答案：C

解析：UInt、ULong、UByte、UShort 都是 @JvmInline value class，包装对应的有符号整型。

10.2 填空题

题目 1：value class 必须有且仅有 ________ 个 val 属性。

答案：一

解析：value class 的核心约束是单一属性，不能有多个属性。

题目 2：value class 在 JVM 平台需要 ________ 注解标记。

答案：@JvmInline

解析：@JvmInline 是 JVM 平台特定的注解，提示编译器进行内联优化。

题目 3：Kotlin ________ 版本将 value class 提升为稳定状态。

答案：1.5

解析：Kotlin 1.5 将 value class 提升为 GA（Stable）。

题目 4：value class 不能继承其他类，但可以实现 ________。

答案：接口

解析：value class 可以实现接口，但不能继承其他类。

题目 5：value class 的 equals 和 hashCode 默认基于 ________。

答案：底层属性（单一属性）

解析：value class 的 equals 比较底层属性，hashCode 基于底层属性计算。

10.3 编程题

题目 1：实现一个类型安全的温度类型，支持摄氏度与华氏度转换。

参考答案：

@JvmInline
value class Celsius(val value: Double) {
    fun toFahrenheit(): Double = value * 9 / 5 + 32
    fun toKelvin(): Double = value + 273.15

    operator fun plus(other: Celsius): Celsius = Celsius(value + other.value)
    operator fun minus(other: Celsius): Celsius = Celsius(value - other.value)

    override fun toString(): String = "${value}°C"
}

@JvmInline
value class Fahrenheit(val value: Double) {
    fun toCelsius(): Celsius = Celsius((value - 32) * 5 / 9)
}

fun main() {
    val c = Celsius(25.0)
    println(c.toFahrenheit())  // 77.0
    println(c.toKelvin())  // 298.15
    println(c + Celsius(10.0))  // 35.0°C
}

题目 2：实现一个类型安全的 URL 类型，带验证。

参考答案：

@JvmInline
value class Url(val value: String) {
    init {
        require(value.startsWith("http://") || value.startsWith("https://")) {
            "URL must start with http:// or https://"
        }
    }

    fun toHttps(): Url = Url(value.replace("http://", "https://"))
    fun domain(): String = value.substringAfter("://").substringBefore("/")
}

fun main() {
    val url = Url("https://example.com/path")
    println(url.domain())  // "example.com"

    val httpUrl = Url("http://test.com")
    println(httpUrl.toHttps().value)  // "https://test.com"
}

题目 3：实现一个分数类型，支持加减乘除。

参考答案：

@JvmInline
value class Fraction(val value: Double) {
    operator fun plus(other: Fraction): Fraction = Fraction(value + other.value)
    operator fun minus(other: Fraction): Fraction = Fraction(value - other.value)
    operator fun times(other: Fraction): Fraction = Fraction(value * other.value)
    operator fun div(other: Fraction): Fraction = Fraction(value / other.value)

    fun toPercentage(): Double = value * 100
    override fun toString(): String = value.toString()
}

fun main() {
    val a = Fraction(0.5)
    val b = Fraction(0.25)
    println(a + b)  // 0.75
    println(a * b)  // 0.125
    println(a.toPercentage())  // 50.0
}

10.4 思考题

题目 1：讨论 value class 与 data class 的适用场景，何时使用哪个？

参考答案：

使用 value class 的场景：

1. 类型安全包装（ID、标识符）。
2. 单一值的语义化（货币、温度、长度）。
3. 性能敏感场景（大量实例）。
4. 不需要 copy、解构声明。

使用 data class 的场景：

1. 多属性的数据载体。
2. 需要 copy、解构声明。
3. 不在意装箱开销。
4. 需要继承（开放类）。

题目 2：value class 在装箱场景中退化为对象，这是否违背了”零开销”承诺？

参考答案：

不违背。“零开销”指的是”在非装箱场景下零开销”，而非”所有场景零开销”。JetBrains 的设计哲学是”在不退化的场景下，性能与底层类型一致”。装箱场景的退化是 JVM 类型系统的限制（类型擦除），是不可避免的。

题目 3：Kotlin 2.0 的 K2 编译器对 value class 有哪些改进？

参考答案：

1. 更激进的装箱消除：K2 在 IR 阶段更激进地识别不必要的装箱点。
2. 方法内联：value class 的方法被内联到调用处。
3. 桥接方法消除：减少接口分发的桥接方法。
4. 逃逸分析：识别不逃逸的对象，栈上分配。
5. 诊断质量：更明确的装箱退化警告。

题目 4：value class 在 KMP 项目中的优势是什么？

参考答案：

1. 跨平台一致：JVM、JS、Native、Wasm 行为一致。
2. 零开销：在 Kotlin/Native 中真正栈分配。
3. 类型安全：编译期检查类型隔离。
4. API 统一：跨平台公共 API 使用 value class。
5. 与 C ABI 兼容：Kotlin/Native 中 value class 与 C struct 互操作友好。

题目 5：分析以下代码并指出问题：

@JvmInline
value class User(val name: String, val age: Int)

@JvmInline
value class Container(val inner: Container?)

参考答案：

问题：

1. User 有两个属性，违反 value class 单一属性约束。
2. Container 递归引用自身，会导致无限展开。

改进：

// 方案一：使用 data class
data class User(val name: String, val age: Int)

// 方案二：将 name 和 age 合并为单一属性
@JvmInline
value class User(val data: String) {
    val name: String get() = data.substringBefore(":")
    val age: Int get() = data.substringAfter(":").toInt()
}

题目 6：value class 在序列化时需要注意什么？

参考答案：

1. 使用 kotlinx.serialization：它对 value class 有完整支持。
2. 避免 Java 默认序列化：可能不正确处理 value class。
3. 装箱场景：序列化时会装箱（因为需要反射）。
4. 自定义序列化器：对于复杂 value class，可自定义序列化器。
5. 版本兼容：序列化格式应考虑二进制兼容性。

题目 7：value class 与 inline 函数如何协同避免装箱？

参考答案：

inline 函数 + reified 类型参数可以在编译期展开，避免泛型类型擦除导致的装箱：

@JvmInline
value class UserId(val id: Long)

// 普通 fun：会装箱
fun <T> process(value: T): T = value

// inline + reified：不装箱
inline fun <reified T> processInline(value: T): T = value

fun main() {
    val userId = UserId(42)

    // 装箱：T 擦除为 Object
    val result1 = process(userId)

    // 不装箱：内联展开，T 替换为 UserId
    val result2 = processInline(userId)
}

题目 8：讨论 value class 在领域驱动设计（DDD）中的角色。

参考答案：

在 DDD 中，value class 用于实现值对象（Value Object）：

1. 类型安全：不同值对象类型不混淆。
2. 不变性：value class 是 final，不可变。
3. 验证：init 块保证构造时验证。
4. 零开销：性能与底层类型一致。
5. 领域语义：EmailAddress、PhoneNumber、Money 等。

注意：value class 仅支持单一属性，多属性值对象仍需使用 data class。

题目 9：分析 value class 在 JVM 字节码中的 box 和 unbox 方法。

参考答案：

JVM 字节码中，value class 编译为 final 类，带有 box 和 unbox 静态方法：

public final class UserId {
    private final long id;

    // 装箱：long -> UserId
    public static UserId box(long id) {
        return new UserId(id);
    }

    // 拆箱：UserId -> long
    public static long unbox(UserId userId) {
        return userId.id;
    }
}

box 在装箱场景（可空、泛型、集合）调用，unbox 在拆箱场景调用。K2 编译器会尽可能消除不必要的 box/unbox 调用。

题目 10：value class 在反射中的行为如何？

参考答案：

1. KClass.isValue：Kotlin 1.5+ 提供 KClass.isValue 属性判断是否为 value class。
2. 装箱：反射操作通常触发装箱（因为接收 Any?）。
3. 构造：通过 primaryConstructor?.call() 会装箱。
4. 属性访问：通过 KProperty.get() 会装箱。
5. 性能：反射操作性能差，应避免在热点代码使用。

@JvmInline
value class UserId(val id: Long)

fun main() {
    val kClass = UserId::class
    println(kClass.isValue)  // true

    // 反射构造会装箱
    val userId = kClass.primaryConstructor?.call(42L)
}

10.5 综合应用题

题目 1：设计一个类型安全的 HTTP 状态码库。

参考答案：

@JvmInline
value class HttpStatusCode(val code: Int) {
    init {
        require(code in 100..599) { "HTTP status code must be 100-599" }
    }

    val isSuccess: Boolean get() = code in 200..299
    val isRedirect: Boolean get() = code in 300..399
    val isClientError: Boolean get() = code in 400..499
    val isServerError: Boolean get() = code in 500..599

    override fun toString(): String = "$code ${description()}"

    fun description(): String = when (code) {
        200 -> "OK"
        201 -> "Created"
        204 -> "No Content"
        301 -> "Moved Permanently"
        400 -> "Bad Request"
        401 -> "Unauthorized"
        403 -> "Forbidden"
        404 -> "Not Found"
        500 -> "Internal Server Error"
        503 -> "Service Unavailable"
        else -> "Unknown"
    }
}

object HttpCodes {
    val OK = HttpStatusCode(200)
    val Created = HttpStatusCode(201)
    val BadRequest = HttpStatusCode(400)
    val Unauthorized = HttpStatusCode(401)
    val NotFound = HttpStatusCode(404)
    val InternalServerError = HttpStatusCode(500)
}

fun main() {
    val status = HttpCodes.OK
    println(status.isSuccess)  // true
    println(status)  // "200 OK"
}

题目 2：实现一个支持多种货币的金额计算库。

参考答案：

package com.example.money

import java.math.BigDecimal

@JvmInline
value class Amount(val value: BigDecimal) : Comparable<Amount> {
    operator fun plus(other: Amount): Amount = Amount(value.add(other.value))
    operator fun minus(other: Amount): Amount = Amount(value.subtract(other.value))
    operator fun times(factor: Int): Amount = Amount(value.multiply(BigDecimal(factor)))
    operator fun compareTo(other: Amount): Int = value.compareTo(other.value)

    override fun toString(): String = value.toPlainString()
}

@JvmInline
value class Currency(val code: String) {
    init {
        require(code.length == 3 && code.all { it.isUpperCase() }) {
            "Currency code must be 3 uppercase letters"
        }
    }
}

class MultiCurrencyWallet {
    private val balances = mutableMapOf<Currency, Amount>()

    fun deposit(currency: Currency, amount: Amount) {
        balances[currency] = (balances[currency] ?: Amount(BigDecimal.ZERO)) + amount
    }

    fun withdraw(currency: Currency, amount: Amount): Boolean {
        val current = balances[currency] ?: return false
        if (current < amount) return false
        balances[currency] = current - amount
        return true
    }

    fun balance(currency: Currency): Amount = balances[currency] ?: Amount(BigDecimal.ZERO)
}

fun main() {
    val wallet = MultiCurrencyWallet()
    val usd = Currency("USD")
    val cny = Currency("CNY")

    wallet.deposit(usd, Amount(BigDecimal("100.00")))
    wallet.deposit(cny, Amount(BigDecimal("700.00")))

    println(wallet.balance(usd))  // 100.00
    println(wallet.balance(cny))  // 700.00

    wallet.withdraw(usd, Amount(BigDecimal("30.00")))
    println(wallet.balance(usd))  // 70.00
}

题目 3：分析以下代码并指出所有问题：

@JvmInline
value class Money(val amount: Double, val currency: String)

@JvmInline
value class Recursive(val inner: Recursive?)

@JvmInline
value class UserId(val id: Long) {
    var cachedName: String? = null
}

参考答案：

问题：

1. Money 有两个属性，违反单一属性约束。
2. Recursive 递归引用自身，会导致无限展开。
3. UserId 有 var 属性，违反 value class 不可变约束。

改进：

// 方案一：使用 data class
data class Money(val amount: Double, val currency: String)

// 方案二：将 currency 和 amount 编码为单一字符串
@JvmInline
value class Money(val data: String) {
    val amount: Double get() = data.substringBefore(":").toDouble()
    val currency: String get() = data.substringAfter(":")
}

// Recursive 不能用 value class，使用普通类
data class Recursive(val inner: Recursive?)

// UserId 移除 var 属性
@JvmInline
value class UserId(val id: Long)

11. 参考文献

11.1 Kotlin 官方文档

[1] JetBrains. 2024. Inline classes. https://kotlinlang.org/docs/inline-classes.html

[2] JetBrains. 2024. Inline value classes. https://kotlinlang.org/docs/inline-value-classes.html

[3] JetBrains. 2024. Kotlin Release Notes. https://kotlinlang.org/docs/releases.html

11.2 学术论文

[4] Wadler, P. 1998. The Expression Problem. https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt

[5] Odersky, M. and Zenger, M. 2005. Scalable Component Abstractions. In Proceedings of OOPSLA ‘05. ACM, 41-58. https://doi.org/10.1145/1094811.1094815

[6] Bacon, D. F. and Sweeney, P. F. 1996. Fast Static Analysis of C++ Virtual Function Calls. In Proceedings of OOPSLA ‘96. ACM, 324-341. https://doi.org/10.1145/236337.236371

[7] Click, C. 2005. The 5-Minute Mainstream. In Java One Conference.

11.3 书籍

[8] Jemerov, D. and Isakova, S. 2017. Kotlin in Action. Manning Publications. ISBN 978-1617293280.

[9] Skeet, J. 2019. C# in Depth (4th ed.). Manning Publications. ISBN 978-1617294532.

[10] Odersky, M., Spoon, L., and Venners, B. 2019. Programming in Scala (5th ed.). Artima Press. ISBN 978-0981531687.

[11] Moskala, M. 2020. Effective Kotlin. Kt. Academy. ISBN 978-8395478316.

11.4 在线资源

[12] JetBrains. 2024. KEEP - Inline Classes. https://github.com/Kotlin/KEEP/blob/master/proposals/inline-classes.md

[13] JetBrains. 2024. Value Classes. https://github.com/Kotlin/KEEP/blob/master/proposals/value-classes.md

[14] Oracle. 2024. Project Valhalla. https://openjdk.org/projects/valhalla/

[15] ECMA International. 2017. Standard ECMA-334: C# Language Specification. https://www.ecma-international.org/publications-and-standards/standards/ecma-334/

11.5 标准与规范

[16] Oracle. 2023. Java Virtual Machine Specification, Java 21 Edition. https://docs.oracle.com/javase/specs/jvms/se21/html/

[17] Oracle. 2023. Java Language Specification, Java 21 Edition. https://docs.oracle.com/javase/specs/jls/se21/html/

12. 延伸阅读

12.1 书籍推荐

1. 《Kotlin in Action》 - Dmitry Jemerov, Svetlana Isakova

   • JetBrains 工程师撰写，包含 value class 章节。

2. 《Effective Kotlin》 - Marcin Moskala

   • Kotlin 最佳实践，包含 value class 使用规范。

3. 《Programming in Scala》 - Martin Odersky

   • Scala AnyVal 与 Kotlin value class 对比。

4. 《C# in Depth》 - Jon Skeet

   • C# struct 与 Kotlin value class 对比。

12.2 论文推荐

1. 《The Expression Problem》 - Philip Wadler

   • 类型与操作的可扩展性，理解 value class 的理论根基。

2. 《Scalable Component Abstractions》 - Odersky, Zenger

   • Scala AnyVal 设计，对比 Kotlin value class。

12.3 在线课程

1. MIT 6.005 - Software Construction

   • 软件构造原理，包含抽象数据类型。

2. Stanford CS193P - iOS Application Development with Swift

   • Swift struct 与 Kotlin value class 对比。

3. JetBrains Academy - Kotlin Developer Track

   • 官方 Kotlin 学习路径，包含 value class 专题。

12.4 开源项目

1. kotlin-stdlib - https://github.com/JetBrains/kotlin/tree/master/libraries/stdlib

   • Kotlin 标准库源码，包含 UInt、Duration 等 value class 实现。

2. Arrow-kt - https://github.com/arrow-kt/arrow

   • 函数式编程库，使用 value class 实现类型安全。

3. kotlinx.serialization - https://github.com/Kotlin/kotlinx.serialization

   • 序列化库，对 value class 完整支持。

12.5 社区与博客

1. Kotlin Blog - https://blog.jetbrains.com/kotlin/

   • 官方博客，发布 value class 新版本。

2. Roman Elizarov’s Blog - https://medium.com/@elizarov

   • Kotlin 语言设计者博客，讨论 value class 设计哲学。

3. KEEP (Kotlin Evolution and Enhancement Process)

   • Kotlin 语言演进提案。

12.6 视频资源

1. KotlinConf 2024 - Value Classes in Practice

   • value class 实战应用。

2. JetBrains TV - Inline Classes Deep Dive

   • value class 内部实现讲解。

12.7 工具与插件

1. Kotlin Plugin for IntelliJ IDEA

   • 官方 IDE 插件，提供 value class 智能提示。

2. kotlinx.serialization

   • 序列化库，支持 value class。

3. kotlinx.binary-compatibility-validator

   • 二进制兼容性检查，用于 value class 库版本管理。

附录 A：value class 速查表

A.1 语法速查

// 基础 value class
@JvmInline
value class ClassName(val property: Type)

// 带验证的 value class
@JvmInline
value class Validated(val value: Type) {
    init {
        require(condition) { "message" }
    }
}

// 实现接口的 value class
@JvmInline
value class Comparable(val value: Type) : Interface {
    override fun method(): ReturnType { /* ... */ }
}

// 带运算符重载的 value class
@JvmInline
value class Numeric(val value: Double) {
    operator fun plus(other: Numeric): Numeric = Numeric(value + other.value)
}

// 序列化支持的 value class
@Serializable
@JvmInline
value class Serializable(val value: Type)