委托属性

是什么，为什么存在

委托属性（delegated property） 是使用 by 声明的属性。属性仍有普通的名称和静态类型，但 getter 与 setter 的实现来自 by 右侧的 属性委托（property delegate） 。调用方只看到 settings.theme，无需知道值是延迟计算、从映射读取，还是经过验证后保存。

它解决的是重复访问逻辑，而不是把属性本身移到别处。延迟初始化、变更通知、赋值拦截、键值存储和规范化输入都可以封装成委托。例如，规范化规则只需实现一次，不必散落在每个表单类的 setter 中。

你会在 val report by lazy { ... }、var name by Delegates.observable(...)、val id: String by map 以及自定义库 API 中遇到它。by 也能把旧属性转发到新属性，适合在重命名期间保留源码兼容性。

属性委托不同于类委托。class Repository(store: Store) : Store by store 转发的是接口成员；val token by loader 只改变一个属性的访问方式。本主题讨论后者。

委托会改变初始化时机、状态所有权和线程语义。一次看似普通的属性读取也可能执行代码。选择委托前，要先能说清楚访问是否有副作用，以及委托实例由谁持有。

工作原理

by 与操作符约定

只读属性 val value: T by delegate 要求委托提供 operator fun getValue(...)。可变属性 var value: T by delegate 还要求 operator fun setValue(...)。委托不必实现某个接口，但标准库的 ReadOnlyProperty 与 ReadWriteProperty 能让签名和类型意图更清楚。

getValue() 接收属性所有者 thisRef 和描述属性的 KProperty<*>。setValue() 再接收新值。成员属性通常把当前对象作为 thisRef；顶层属性和局部委托没有所属实例，因此相应接收者为 null。

这两个操作符的类型约束会在编译期检查。getValue() 的返回类型必须能作为属性类型，setValue() 的值参数必须能接收属性值。thisRef 可以使用所有者类型或其超类型，这让委托能够限制自己只能绑定到某类对象。

委托表达式与状态

成员声明右侧的委托表达式会在所属对象初始化时求值。写成 var name by NormalizedText() 时，每次创建所属对象都会创建新的 NormalizedText；同一对象中的两个这样的声明也得到两个委托实例。状态自然按对象、按属性隔离。

如果右侧引用一个单例或共享变量，隔离就不再成立。委托把值保存在自身字段中时，所有绑定到该实例的属性都会读写同一字段。共享可以是设计目标，但必须显式建模，不能依赖调用方猜测。

委托通常让编译器生成一个保存委托对象的隐藏字段。这个字段不是属性的普通 幕后字段（backing field） ；它保存的是委托，实际值是否存在、存在哪里，由委托决定。某些优化情形会省略这个隐藏字段，深层部分会说明边界。

标准库委托

lazy 为 val 保存首次成功计算的结果。默认的 SYNCHRONIZED 模式保证一个线程执行初始化，并把结果发布给其他线程。初始化抛出异常时，值仍未初始化；下次访问会再次尝试。

Delegates.observable(initial) 在值已经写入后调用回调。回调适合发出轻量通知或记录变化，但它不能否决赋值。回调抛出异常也不会自动恢复旧值。

Delegates.vetoable(initial) 在写入前调用谓词。返回 true 才保存新值，返回 false 时属性保持旧值。赋值表达式不会告诉调用方是否被拒绝，因此需要反馈的业务验证通常更适合显式方法。

映射与属性引用

Map<String, Any?> 已提供适合只读属性的委托操作符，键就是属性名；MutableMap 还能支持 var。这种写法适合已经以键值形式存在且经过验证的数据。缺键或值类型不符会在运行时失败，所以它不能代替边界解析与校验。

属性也能委托给另一个属性，例如 var oldName by this::newName。读写旧名称会直接访问新名称。它常与 @Deprecated 和 ReplaceWith 配合，用于平滑重命名；两个名称不是两份状态。

属性引用委托经过编译器专门处理，不需要保存普通的 $delegate 字段。属性引用表达的是别名关系，而不是一个任意对象的 getValue() 或 setValue() 策略。审查时应把它当作 API 迁移入口，检查旧名称何时可以删除。

示例

首次读取才计算

Catalog 构造时不会加载列表。第一次读取 featured 才执行初始化器，后续读取返回同一个结果。

两次读取 featured 只产生一次 loading catalog。缓存的是 Lazy 实例中的结果，不是调用表达式文本。如果每个 Catalog 都使用声明中的 lazy { ... }，每个实例各自拥有一份缓存。

这段初始化器有可见输出，便于观察时机。实际初始化器若执行网络写入、扣费或发送消息，失败后的自动重试可能重复副作用；应把这类动作移到有显式幂等策略的服务方法中。

观察写入与否决写入

observable 的回调看到已经接受的优惠码。vetoable 在商品数量写入前运行，所以负数尝试会打印检查过程，但最终值仍是 3。

import kotlin.properties.Delegates

class Cart {
    var coupon: String by Delegates.observable("none") {
        property, oldValue, newValue ->
        println("${property.name}: $oldValue -> $newValue")
    }

    var itemCount: Int by Delegates.vetoable(1) {
        property, oldValue, newValue ->
        println("try ${property.name}: $oldValue -> $newValue")
        newValue >= 0
    }
}

fun main() {
    val cart = Cart()
    cart.coupon = "SAVE10"
    cart.itemCount = 3
    cart.itemCount = -1
    println(cart.itemCount)
}

coupon: none -> SAVE10
try itemCount: 1 -> 3
try itemCount: 3 -> -1
3

observable 即使新旧值相等也会收到赋值通知；是否忽略相等值由回调决定。vetoable 的谓词适合很小的本地不变量，但复杂验证需要错误信息、异步检查或多字段原子更新时，普通方法更清楚。

两个回调都在发起赋值的线程中同步运行。它们不会自动切换到 UI 线程，也不会提供锁。并发访问需要在更高层定义同步策略。

映射存储与兼容别名

映射委托按属性名访问键。name 再委托到 displayName，所以通过旧名称写入后，映射中的 displayName 也立即变化。

class Profile(private val values: MutableMap<String, Any?>) {
    var displayName: String by values
    var loginCount: Int by values

    @Deprecated("Use displayName", ReplaceWith("displayName"))
    var name: String by this::displayName

    fun snapshot(): Map<String, Any?> = values.toSortedMap()
}

fun main() {
    val profile = Profile(
        mutableMapOf(
            "displayName" to "Ada",
            "loginCount" to 2,
        ),
    )

    profile.name = "Ada Lovelace"
    profile.loginCount += 1

    println(profile.displayName)
    println(profile.snapshot())
}

Ada Lovelace
{displayName=Ada Lovelace, loginCount=3}

如果把 displayName 重命名，映射键也随之改变，旧数据不会自动迁移。生产代码应先把外部载荷解析成经过校验的类型，或为旧键写明确的迁移规则，而不是把任意 JSON 映射直接暴露为领域对象。

旧属性的 setter、getter 和新属性使用同一份状态。@Deprecated 只产生迁移提示，不会限制运行时访问；删除旧名称前仍要检查下游源码和二进制兼容性要求。

在绑定时检查自定义委托

TextFields 是委托提供者，不直接保存文本。每次属性绑定都会调用 provideDelegate()，校验名称后返回一个独立的 NormalizedText，因此 name 与 city 不会共享值。

import kotlin.properties.ReadWriteProperty
import kotlin.reflect.KProperty

class NormalizedText(initial: String) : ReadWriteProperty<Any?, String> {
    private var value = normalize(initial)

    override fun getValue(thisRef: Any?, property: KProperty<*>): String = value

    override fun setValue(
        thisRef: Any?,
        property: KProperty<*>,
        value: String,
    ) {
        this.value = normalize(value)
    }

    private fun normalize(input: String): String =
        input.trim().replace(Regex("\\s+"), " ")
}

class TextFields(private val allowed: Set<String>) {
    operator fun provideDelegate(
        thisRef: Any?,
        property: KProperty<*>,
    ): ReadWriteProperty<Any?, String> {
        require(property.name in allowed) {
            "unsupported field: ${property.name}"
        }
        return NormalizedText("")
    }
}

class ContactForm {
    private val textFields = TextFields(setOf("name", "city"))
    var name: String by textFields
    var city: String by textFields
}

fun main() {
    val form = ContactForm()
    form.name = "  Ada   Lovelace "
    form.city = " New   York "
    println("${form.name}|${form.city}")
}

Ada Lovelace|New York

provideDelegate() 在对象初始化、属性与委托建立关系时运行，不会在每次读取时再次运行。若属性名不在集合中，构造 ContactForm 就失败。该时机适合检查绑定配置，不适合依赖稍后才准备好的对象状态。

返回类型使用 ReadWriteProperty<Any?, String>，所以委托能绑定到任意所有者。若规范化规则只适用于 ContactForm，可以把接收者类型收紧为 ContactForm，让错误绑定直接无法编译。

陷阱

修复方法： 为每个所有者、每个属性创建委托实例，或在确实需要共享的实现中按 thisRef 与 property 显式索引状态。测试时交错写入两个属性和两个所有者，不能只测一个快乐路径。

修复方法： 让观察回调短小且不承担事务一致性。需要先验证、持久化并原子提交时，使用返回成功或失败的显式方法，把属性更新放在该流程的确定位置。

修复方法： 仅把 vetoable 用于无需反馈的局部约束。业务操作若必须报告原因，改用 setQuantity(newValue): Result<Unit> 之类的 API，并让调用方处理失败。

修复方法： 在输入边界一次性检查必需键、类型与版本，再构造强类型模型。若映射本身就是协议，集中定义键常量和迁移规则，并为缺键、空值、错误类型与旧键写测试。

修复方法： 先写明初始化发生在哪个线程、初始化器是否纯粹，以及重复执行是否安全。没有可靠的单线程所有权时使用默认模式；使用 PUBLICATION 时让初始化器可重复执行且无外部副作用。

延伸阅读

以下链接指向 Kotlin 官方文档及标准库源码。文档页面说明语言规则，源码则给出标准委托与接口在当前分支中的准确契约。

• Kotlin 文档源文件：委托属性
• Kotlin 标准库源码：Delegates
• Kotlin 标准库源码：属性委托接口
• Kotlin 标准库源码：Lazy 与线程模式