诡异！String 参数在闭包里变成了 <uninitialized>，我排查了整整两天

TCA 依赖注入踩坑记：当 String 参数在闭包调用中变成 <uninitialized>

前言

这是一篇关于 Swift 并发（Concurrency）与 The Composable Architecture（TCA）依赖注入踩坑实录。问题诡异到控制台打印 agentId=(null) count=0，但日志明明显示传入的是 "developer"。排查过程历时数小时，最终发现是 actor 隔离机制与 existential dispatch 的微妙交互导致的。

---

一、问题现象

在 ProjectPilot（一个基于 SwiftUI + TCA 的 macOS AI 开发助手）中，用户点击 Agent 卡片时，会触发 selectAgent action，获取该 Agent 的能力雷达图数据。

崩溃现场：

• 控制台 agentId 显示 <uninitialized>
• Xcode debugger 中 po agentId 无法打印
• 代码在 fetchAgentCapabilities 调用时崩溃

case .selectAgent(let agent):
    state.selectedAgent = agent
    return .run { send in
        do {
            let capabilities = try await agentCore.fetchAgentCapabilities(agent.agentId)
            //                            ↑ 传入 "developer"，实际变成 <uninitialized>
            await send(.agentCapabilitiesLoaded(capabilities))
        } catch {
            await send(.agentCapabilitiesLoaded(nil))
        }
    }

---

二、架构背景

在深入分析前，先了解一下相关组件的架构：

2.1 TCA 依赖注入

TCA 使用 @DependencyClient 宏来定义依赖接口：

@DependencyClient
struct AgentCoreClient: Sendable {
    let fetchAgentCapabilities: (String) async throws -> AgentCapabilities
    // ...
}

通过 DependencyKey 扩展提供具体实现：

extension AgentCoreClient: DependencyKey {
    @MainActor
    static let liveValue: AgentCoreClient = AgentCoreClient(
        LiveAgentCore()
    )
}

在 Reducer 中这样使用：

@Reducer
struct TeamReducer {
    @Dependency(\.agentCore) var agentCore
}

2.2 相关类型定义

// 协议定义（Sendable）
protocol AgentCoreProtocol: Sendable {
    func fetchAgentCapabilities(agentId: String) async throws -> AgentCapabilities
}

// 实现类
final class LiveAgentCore: AgentCoreProtocol {
    func fetchAgentCapabilities(agentId: String) async throws -> AgentCapabilities {
        return try await service.fetchAgentCapabilities(agentId: agentId)
    }
}

2.3 AgentCoreClient 的闭包包装

init(_ core: any AgentCoreProtocol) {
    // 闭包捕获 existential
    self.fetchAgentCapabilities = { agentId in
        try await core.fetchAgentCapabilities(agentId: agentId)
    }
}

---

三、排查过程

3.1 第一步：定位问题发生的位置

在代码的多个关键位置添加日志：

// 位置 1：TeamReducer.selectAgent 入口
print("[TEAM_REDUCER] ⚡ selectAgent: agentId=\(capturedAgentId)")
// 输出：⚡ selectAgent: agentId=developer ✅ 正常

// 位置 2：.run 闭包内部
print("[TEAM_REDUCER] 📍 inside .run closure, capturedAgentId=[\(capturedAgentId)]")
// 输出：📍 inside .run closure, capturedAgentId=[developer] ✅ 正常

// 位置 3：AgentCoreClient.fetchAgentCapabilities 闭包入口
print("[CLIENT] ⚡⚡⚡ CLOSURE agentId=[\(agentId)]")
// 输出：⚡⚡⚡ CLOSURE agentId=(null) count=0 ❌ 损坏！

关键发现 ：问题发生在 AgentCoreClient 闭包入口，agentId 在传递给闭包参数时就已经损坏了。

3.2 第二步：绕过 AgentCoreClient 验证

尝试直接创建 LiveAgentCore 实例调用：

case .selectAgent(let agent):
    let capturedAgentId = agent.agentId
    return .run { [capturedAgentId] send in
        do {
            // 绕过 AgentCoreClient，直接调用
            let liveCore = LiveAgentCore()
            let capabilities = try await liveCore.fetchAgentCapabilities(agentId: capturedAgentId)
            await send(.agentCapabilitiesLoaded(capabilities))
        } catch {
            await send(.agentCapabilitiesLoaded(nil))
        }
    }

结果 ：直接调用 LiveAgentCore() 完全正常！

[TEAM_REDUCER] ⚡ selectAgent: agentId=developer
[TEAM_REDUCER] 📍 inside .run closure, capturedAgentId=[developer]
[TEAM_REDUCER] [SERVICE] ⚡ fetchAgentCapabilities ENTRY: agentId=developer ✅

3.3 第三步：尝试各种修复方案

方案	做法	结果
1	移除 LiveAgentCore 的 @MainActor	❌ 无效
2	移除 AgentCoreClient 的 Sendable	❌ 无效
3	使用 LiveAgentCore.shared 单例	❌ 无效
4	直接创建 LiveAgentCore() 调用	✅ 临时有效
5	给 AgentCoreClient 加 @MainActor	✅ 最终有效

---

四、根本原因分析

4.1 Swift Actor 隔离回顾

Swift 的 actor 模型要求：

• Actor 内部的所有代码都在 actor 的上下文中执行
• 从外部访问 actor 的属性/方法需要跨 actor 边界

// Actor 内部方法是 isolated
actor MyActor {
    func foo() { }  // 只能在 MyActor 的 actor 上下文中调用
}

4.2 @MainActor 的特殊性

@MainActor 是一个特殊的 actor，表示主线程的上下文。当类型标记为 @MainActor 时：

• 所有实例方法和属性都在主线程执行
• 类的所有实例都在主线程创建

@MainActor
class MyViewModel {
    func update() { }  // 主线程执行
}

4.3 any Existential 的 dispatch 问题

当通过 any Protocol（existential）调用方法时：

protocol P: Sendable {
    func foo(x: String) async
}

class C: P {
    @MainActor
    func foo(x: String) async { }
}

// 问题场景：
func callFoo(p: any P) async {
    await p.foo(x: "hello")  // 跨 actor 边界传递
}

当 p 引用一个 @MainActor class 实例时，通过 any P 调用会触发特殊的 dispatch 机制。

4.4 问题的本质

在 AgentCoreClient 中：

init(_ core: any AgentCoreProtocol) {  // core 是 existential
    self.fetchAgentCapabilities = { agentId in
        // 这个闭包在创建时捕获了 core
        try await core.fetchAgentCapabilities(agentId: agentId)
        //                                          ↑ 参数在跨 actor 调用时可能损坏
    }
}

关键点：

1. AgentCoreClient 本身是 Sendable（无 actor 隔离）
2. LiveAgentCore 也是隐式 Sendable（因为它遵循 AgentCoreProtocol: Sendable）
3. 但 LiveAgentCore 实例本身可能在主线程创建（@MainActor static let liveValue）
4. 当闭包从非主线程执行并通过 existential 调用时，参数传递可能出问题

4.5 为什么 @MainActor 能解决问题

@MainActor  // ← 关键修改
@DependencyClient
struct AgentCoreClient: Sendable {
    // ...
}

当 AgentCoreClient 标记为 @MainActor 后：

• TCA 在访问 agentCore 依赖时，会在主线程上执行
• 闭包的创建和调用都在同一个主线程上下文
• 避免了跨 actor 的 existential dispatch 问题

---

五、最终解决方案

@MainActor  // 关键：让 TCA 在主线程上访问这个依赖
@DependencyClient
struct AgentCoreClient: Sendable {
    let fetchAgentCapabilities: (String) async throws -> AgentCapabilities

    init(_ core: any AgentCoreProtocol) {
        self.fetchAgentCapabilities = { agentId in
            try await core.fetchAgentCapabilities(agentId: agentId)
        }
    }
}

extension AgentCoreClient: DependencyKey {
    @MainActor
    static let liveValue: AgentCoreClient = AgentCoreClient(
        LiveAgentCore()
    )
}

这样 TCA 的 \.agentCore 访问会自动在主线程上运行，闭包调用不再跨 actor 边界。

---

六、经验总结

6.1 调试技巧

1. 日志定位法：在调用链的多个关键位置添加日志，逐步缩小问题范围
2. 绕过验证法：绕过疑似有问题的层，直接调用下一层，定位问题所在
3. 枚举尝试法：尝试多种解决方案，观察哪些有效、哪些无效

6.2 Swift 并发要点

1. Sendable 不等于线程安全 ：一个类型是 Sendable 并不意味着它可以在任意 actor 上下文中安全使用
2. Existential dispatch 有开销 ：通过 any Protocol 调用比直接调用有额外的运行时开销
3. Actor 隔离是编译时检查：Swift 在编译时强制执行 actor 隔离，但 existential 可能绕过某些检查

6.3 TCA 依赖注入注意事项

1. 依赖的 actor 特性 ：如果依赖包含 @MainActor 类型，要注意闭包捕获的 actor 上下文
2. 闭包的 Sendable 约束 ：TCA 要求依赖闭包是 Sendable，但这不保证跨 actor 调用时参数安全
3. 一致性原则：如果一个依赖涉及 actor，最好在整个调用链上保持一致性

---

七、相关文档

• Swift Concurrency - Actors
• TCA DependencyKey Documentation
• SE-0308: Sendable and @MainActor

---

结语

这个问题排查了很久，关键在于理解 Swift 的 actor 隔离机制、any Existential 的 dispatch 特性，以及 TCA 依赖注入的工作原理。@MainActor 看似只是一个修饰符，但它改变了整个调用链的 actor 上下文，对依赖注入的行为有深远影响。

希望这篇分享能帮助到有类似问题的开发者。如果有任何疑问，欢迎在评论区交流！