Kotlin 2.4：把 context receivers 迁到 context parameters
2.3.20 起 context receivers no longer supported / 不再支持；2.4 起除 context arguments 与 callable references 外已稳定，一般项目不再需要 -Xcontext-parameters。若你还在用 -Xcontext-receivers，或在 Beta 阶段靠 -Xcontext-parameters 试水，升级到 Kotlin 2.4 后应尽快把声明改成带名字的 context parameters，并理清仍实验的开关与调用形态。
为何要迁
context receivers 曾让「隐式依赖」写起来像扩展接收者：调用处不必反复传 Logger、Transaction、UserService 等横切对象。代价也很明显：按类型隐式注入，类上声明，再和扩展接收者叠在一起时，可读性与重载解析都容易失控。
context parameters 保留「从周围作用域按类型解析依赖」的能力，但把依赖写成具名形参 ：声明侧一眼能看出依赖叫什么、类型是什么；函数体内通过名字使用，而不是默认当 this。从 2.3.20 起，实验性的 context receivers 不再支持，官方路径就是迁到 context parameters。到了 2.4，主路径已稳定，适合作为团队默认写法。
和「层层手传参数」比，context parameters 适合跨越一串调用、又很少变化的依赖；和 CoroutineContext 比，前者偏编译期按类型注入 ，后者偏运行时跨挂起边界传递键值。下面会分开讲，避免混用概念。
语法对照：旧 receivers → 新 parameters
旧写法（context receivers 风格，仅作对照，新工程勿再启用 -Xcontext-receivers）：
kotlin
// 旧：context(Type) ------ Type 作为隐式 receiver
context(Logger)
fun saveUser(id: Int) {
info("saving $id") // 直接当 receiver 用
}新写法（context parameters）：
kotlin
interface Logger {
fun info(msg: String)
}
class ConsoleLogger : Logger {
override fun info(msg: String) = println("INFO: $msg")
}
// 新：context(name: Type) ------ 具名 context 形参
context(logger: Logger)
fun saveUser(id: Int) {
logger.info("saving $id")
}
fun demo() {
val logger = ConsoleLogger()
context(logger) {
saveUser(42)
}
}要点：
- 声明 ：
context(logger: Logger)，每个依赖都有名字与类型。 - 使用 ：函数体里写
logger.info(...)，不再默认当隐式this。 - 提供 ：调用侧用标准库
context(value) { ... }，把值放进 context scope；它只用于解析 context 形参，不会 像with那样把值变成扩展接收者。 - 匿名名 ：不需要在本函数里点名时可用
_，例如context(_: Logger)；若仍要取值，用contextOf<Logger>()。
属性同样可声明 context parameters（有官方限制，见迁移坑）：
kotlin
context(users: UserService)
val firstUser: String
get() = users.findUserById(1)
稳定范围与编译器开关
| 能力 | 2.4 口径 | 你怎么做 |
|---|---|---|
context parameters（声明、按类型解析、context { } 提供） |
已稳定（不含下列两项） | 一般去掉 -Xcontext-parameters |
| context arguments（调用处显式传入 context 实参） | 仍实验 | 需要时加 -Xexplicit-context-arguments |
| callable references（带 context parameters 的可调用引用） | 仍未纳入本次稳定 | 优先改成 lambda / 具名包装函数 |
| context receivers | 自 2.3.20 起 不再支持 | 改声明与编译开关，勿继续依赖旧 flag |
Gradle 示例（Kotlin DSL）：主路径稳定后通常只要版本升到 2.4，不必再开 -Xcontext-parameters：
kotlin
kotlin {
compilerOptions {
// 一般可删除: freeCompilerArgs.add("-Xcontext-parameters")
// 仅当要用显式 context 实参时:
// freeCompilerArgs.add("-Xexplicit-context-arguments")
}
}显式 context arguments 典型场景：多个重载仅 context 形参类型不同，2.3.20 起重载解析更「一视同仁」，容易在调用处歧义。开启 -Xexplicit-context-arguments 后，可在调用处写 sendNotification(emailSender = defaultEmailSender) 这类具名 context 实参消歧；若同一组 context 要服务多处调用，仍更适合外层 context(...) { }，少嵌套、少重复。
记住：-Xexplicit-context-arguments 仍实验；没踩重载歧义就先别开，降低团队认知负担。
迁移步骤与常见坑
建议按模块推进，避免「半模块旧 flag、半模块新语法」长期并存。
- 升版本：Kotlin 升到 2.4 线；确认构建已切到 K2 相关默认路径。
- 换开关 ：若仍有
-Xcontext-receivers，先改为曾用过的-Xcontext-parameters（中间过渡），再在 2.4 上评估删除该 flag。 - 改声明 ：
context(Type)→context(name: Type)；函数体里所有隐式 receiver 调用改为具名访问。 - IDE 辅助：IntelliJ 有将 context receivers 替换为 context parameters 的快速修复 / 检查，可先扫一遍再人工过类声明与 DSL。
- 提供点统一 ：把「注入边界」收敛到少量
context(dep) { }（或测试夹具），业务函数只声明依赖、不手传。 - callable references ：若以前对带 context 的函数做
::foo，稳定范围之外可能仍受限，可改成{ foo() }或包一层普通函数。 - 重载歧义：仅 context 不同的重载，调用处可能报歧义：要么合并 API，要么在实验开关下用显式 context arguments，要么用更窄的类型区分。
官方限制（迁移时对照文档，勿凭感觉绕过）：
- 构造函数不能声明 context parameters。
- 带 context parameters 的属性：不能有 backing field / initializer；也不能用委托。
- context parameters 用于函数/属性等还有边界条件，迁移时以 Context parameters 为准。
类上的旧 context receivers 没有一对一的 parameters 对应物，需要按场景手工拆：把依赖提到工厂/成员、或改成函数级 context、或显式构造注入。越早拆，越少被旧写法绑住。
同类型多个值同时进入 scope 会歧义，例如 context(serviceA, serviceB) { outputMessage(...) } 且二者都是 UserService。应缩小 scope、换更具体类型，或（在实验开关下）显式传 context 实参。
与 CoroutineContext 怎么分工
不要把两套「context」当成同一个东西：
| context parameters | CoroutineContext |
|
|---|---|---|
| 时机 | 编译期按类型解析 | 运行时键值，随协程传递 |
| 典型用途 | Logger、仓库、DSL 宿主等横切依赖 | Job、Dispatcher、自定义 ThreadContextElement |
| 写法 | context(logger: Logger) fun ... |
withContext(MyElement) { ... } / coroutineContext[Key] |
| 挂起 | 不替代协程上下文 | 跨 suspend 边界传递状态的主通道 |
实践建议：
- 业务依赖注入 / DSL：优先 context parameters，调用链干净。
- 调度、取消、MDC、追踪 ID：继续放 CoroutineContext（或现有拦截器），不要指望用 context parameters「穿透」任意挂起点自动带上运行时状态。
- 可以在同一段代码里两者都出现：外层
withContext定调度与元素，内层context(service) { }定编译期依赖。职责分开，阅读成本更低。
更系统的协程上下文与结构化并发，可结合站内相关阅读一起看，避免把语言特性和 kotlinx.coroutines 混成一套口诀。
相关阅读
官方文档建议收藏：Context parameters、What's new in Kotlin 2.4.0（稳定范围与显式 context arguments）、以及 2.3.20 变更说明中「context receivers 不再支持」与重载解析调整。
小结
从 receivers 迁到 parameters，就是把隐式 receiver 换成具名 context 形参 ；从实验旗标堆砌 走到2.4 主路径稳定、特殊能力按需实验 。落地时抓住三件事：声明改名并改用点、提供边界用 context { } 收敛、callable references / 显式 context arguments 仍当实验能力对待。按上面流程图走完编译与测试后，大多数业务模块可以不再依赖 -Xcontext-parameters，把精力放回 API 边界是否清晰，而不是编译器开关本身。