用 Task Local Values 构建 Swift 里的依赖容器：一种更轻量的依赖注入思路

大家好，我是展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

前言

Swift 并发体系这两年一直在快速进化，除了我们熟悉的async/await、TaskGroup、Actor之外，其实还悄悄加入了一个非常有意思、但讨论不算多的能力：Task Local Values。

乍一看，它好像只是一个“任务级别的全局变量”，但一旦你理解了它的设计初衷，就会发现它非常适合用来做一些以前很难优雅实现的事情，比如：

• 在并发任务中传递上下文信息（requestId、traceId）
• 做统一日志、埋点
• 甚至，用来构建一个隐式的依赖注入容器

这篇文章会从最基础的 Task Local Values 讲起，然后一步步带你实现一个基于 Task Local 的依赖容器，并结合真实业务和测试场景分析它到底适不适合你。

Task Local Values 是什么？解决的到底是什么问题？

一句话概括：
Task Local Values 是一种“随 Task 传播的共享状态”，对子任务自动可见，而且同时支持同步和异步访问。

它解决的是并发环境下一个非常现实的问题：

在一堆 async / await、子任务、任务组中，我怎么优雅地把“上下文信息”一路传下去？

比如下面这些场景你一定遇到过：

• 一个网络请求需要生成 requestId，然后在多个并发子任务里都要用
• 日志系统需要在任何 async 方法中都能拿到当前请求的标识
• 测试时希望“偷偷”替换某些依赖，但不想层层传参数

以前你可能会选择：

• 手动把参数一层层传下去（非常烦）
• 用全局变量（线程不安全）
• 用 ThreadLocal（Swift 没有）

Task Local Values 就是 Apple 给出的标准答案。

一个最基础的 Task Local 示例

我们先从一个最简单、也最经典的场景开始：请求上下文传递。

structRequest:Identifiable{letid=UUID()}

这里我们定义了一个Request，内部只有一个UUID，模拟真实世界里的 requestId。

接下来是关键代码：

extensionRequest{@TaskLocalstaticvarcurrent=Request()}

这行代码做了几件非常重要的事情：

• @TaskLocal只能用在static 属性上
• 它定义了一个“当前 Task 可见的共享值”
• 必须有默认值（或者定义成 Optional）

你可以把Request.current理解成：

当前并发任务树中，大家默认能看到的那个 Request

这个设计和 SwiftUI 的Environment非常像，只不过作用域从“视图树”变成了“任务树”。

在 async 场景中使用 Task Local

下面我们来看一个稍微真实一点的例子。

funcfetchData()asyncthrows->Data?{letnewRequest=Request()returntryawaitRequest.$current.withValue(newRequest){tryawaitwithThrowingTaskGroup(of:Data.self){groupingroup.addTask{leturl=URL(string:"https://example.com/api/\(Request.current.id.uuidString)")!let(data,_)=tryawaitURLSession.shared.data(from:url)returndata}group.addTask{// 在任何子任务里都可以直接访问 Request.currentprint("Current request id:",Request.current.id)returnData()}fortryawait dataingroup{returndata}}}}

这里有几个关键点一定要注意：

1. Task Local 是只读的

你不能直接写：

Request.current=newRequest// ❌ 不允许

唯一正确的方式是使用：

Request.$current.withValue(newValue){// 在这个闭包作用域内生效}

2. withValue 的作用范围是整个 async 调用链

只要是在这个 closure 里面启动的 async 操作、子任务、TaskGroup，都能自动拿到这个值。

这点非常关键，也是 Task Local 的核心价值。

这个能力在真实项目里有什么用？

到这里你可能会想：

好像挺酷，但我真的会用到吗？

其实你可能已经在用类似的东西，只是方式更笨一点。

常见应用场景包括：

• 请求级日志上下文（requestId、userId）
• 性能追踪、链路追踪
• A/B 实验参数
• 灰度发布标识

而这些数据都有一个共同特点：

• 不适合写成全局变量
• 不想每个函数都传参数
• 生命周期和一次请求/任务绑定

Task Local 正好卡在这个位置。

用 Task Local 构建一个依赖容器

接下来进入这篇文章最有意思的部分：用 Task Local 做依赖注入。

为什么要这么做？

在 Swift 项目里，依赖注入通常有几种方式：

• 构造函数注入（很啰嗦）
• 全局单例（测试困难）
• Service Locator（容易失控）

Task Local 提供了一种折中的思路：

在一个 async 任务作用域里，隐式切换依赖实现

定义依赖容器

我们先定义一个依赖集合：

structDependencies{letfetchStatistics:(DateInterval)asyncthrows->[HKStatistics]}

这里为了简化，只放了一个方法。真实项目中你可能会有：

• 网络请求
• 数据库
• 本地缓存
• Feature flag
• 权限判断

生产环境依赖

extensionDependencies{staticvarproduction:Dependencies{letstore=HKHealthStore()return.init(fetchStatistics:{intervalinletquery=HKStatisticsCollectionQueryDescriptor(predicate:.quantitySample(type:HKQuantityType(.bodyMass)),options:.discreteAverage,anchorDate:interval.start,intervalComponents:DateComponents(day:1))returntryawait query.result(for:store).statistics()})}}

这是一个真实的生产实现，会调用系统 API。

Mock 版本依赖

extensionDependencies{staticvarmock:Dependencies{letmockedStatistics:[HKStatistics]=[// 构造假的数据]return.init(fetchStatistics:{_inmockedStatistics})}}

Mock 版本不会访问系统、不依赖权限，非常适合测试。

用 Task Local 管理“当前依赖”

extensionDependencies{@TaskLocalstaticvaractive:Dependencies=.production}

这一行是整个设计的核心。

它意味着：

• 默认情况下，所有代码用的都是 production
• 但在某个 Task 作用域里，你可以悄悄换成 mock

在测试中使用 Mock 依赖

@TestfuncverifySomething()asyncthrows{awaitDependencies.$active.withValue(.mock){letinterval:DateInterval=// 构造测试区间letstatistics=tryawaitDependencies.active.fetchStatistics(interval)#expect(statistics.count==1)}}

这里有几个非常爽的点：

• 不需要改任何业务代码
• 不需要传 mock 参数
• 不需要全局开关
• 并发安全

测试代码只负责“在这个 Task 里，用 mock 版本”。

这种方式适合你吗？

说实话，这不是银弹。

适合的场景

• 以 async/await 为主的现代 Swift 项目
• 强调并发安全
• 想要轻量 DI，而不是完整框架
• 测试中需要大量 mock

不适合的场景

• 同步代码占比极高
• 依赖关系非常复杂、层级很深
• 团队对隐式依赖不熟悉（可读性风险）

总结

Task Local Values 表面看是并发的小功能，但本质上提供了一种新的“上下文传播模型”。

当你用它来做：

• 请求上下文
• 日志追踪
• 依赖注入

你会发现它比传统方案：

• 更安全
• 更简洁
• 更贴合 Swift Concurrency 的设计哲学

如果你正在构建一个以 async/await 为核心的新项目，非常值得认真考虑这种模式。