Swift并发模型引入之后，Sendable协议成了绕不开的话题。很多开发者写了多年的泛型容器，比如缓存、队列、结果包装类型，在迁移到Swift 6严格并发检查时突然发现一堆警告和报错：这个类型不能跨并发域传递。问题的根源往往不是容器本身，而是泛型类型参数没有声明Sendable约束，导致编译器无法确认容器内部持有的元素是否可以安全共享。本文就来详细聊聊如何为泛型集合类型正确添加Sendable约束。
Sendable协议到底约束了什么
Sendable不是一个普通的协议，它没有任何方法或属性要求，而是一个标记协议，作用是向编译器承诺：这个类型的实例可以安全地跨越并发域传递，也就是从一个执行上下文传到另一个执行上下文而不会引发数据竞争。编译器会根据这个承诺做静态检查，在Swift 6语言模式下，违反Sendable约束的代码会直接编译失败，而不是像以前那样只给出警告。
对于具体类型，Sendable的遵循规则比较直观：值类型（struct、enum）只要所有存储属性都是Sendable的，就可以无条件遵循；final class则要求所有存储属性都是可变的并且是Sendable的，或者所有可变状态都被隔离保护；actor天然是Sendable的；而非final的类、包含非Sendable成员的类型默认都不能自动获得这个能力。
但泛型类型的情况要特殊一些。一个struct Box<T>，它的存储属性类型是T，编译器并不知道T是不是Sendable，所以Box<T>本身不能无条件声明遵循Sendable。这时候就必须借助带条件约束的遵循写法。
为泛型类型参数添加Sendable约束的三种方式
第一种也是最常用的方式，是在类型声明的遵循列表里直接写条件扩展：
struct Cache<Value> {
var storage: [String: Value] = [:]
mutating func insert(_ value: Value, forKey key: String) {
storage[key] = value
}
}
// 只有当 Value 是 Sendable 时，Cache 才遵循 Sendable
extension Cache: Sendable where Value: Sendable { }
这种写法的语义非常清晰：Cache本身是值类型，它的安全性完全取决于内部元素Value的安全性。当Value满足Sendable时，编译器自动认可Cache是Sendable的；当Value不满足时，Cache也不满足，跨任务传递它就会被拦截。这正是我们想要的行为，约束既不宽松也不苛刻。
第二种方式是在定义泛型参数时就直接要求约束，这种方式约束更强，适用于容器天生就应该并发安全的场景：
// 定义时直接约束，所有使用处都要求 Value 是 Sendable
final class ConcurrentBox<Value: Sendable>: Sendable {
private let lock = NSLock()
private var _value: Value
init(_ value: Value) {
self._value = value
}
var value: Value {
lock.lock()
defer { lock.unlock() }
return _value
}
func update(_ newValue: Value) {
lock.lock()
defer { lock.unlock() }
_value = newValue
}
}
注意上面的例子是引用类型，因为用了锁保护可变状态，所以即使包含var存储属性，也可以安全声明Sendable，但前提是类必须是final的。第三种方式是在函数签名级别用where子句做局部约束，比如一个异步函数只想接收可共享的集合：
func process<T: Sequence>(_ items: T) async throws
where T.Element: Sendable, T: Sendable
{
for item in items {
// 每个元素都可以安全地在并发上下文中使用
await handle(item)
}
}
函数级别的约束灵活性最高，它把选择权交给了调用方：传一个元素为非Sendable的集合进来，编译器会在调用处报错，而不是在函数内部埋下隐患。
实现一个并发安全的泛型队列：完整示例与常见坑
下面把前面的知识点串起来，实现一个可以在多个任务间共享的线程安全泛型队列。核心思路是用actor提供隔离，同时给泛型参数加Sendable约束：
actor AsyncQueue<Element: Sendable> {
private var items: [Element] = []
private var waiters: [CheckedContinuation<Element, Never>] = []
func enqueue(_ element: Element) {
if !waiters.isEmpty {
waiters.removeFirst().resume(returning: element)
} else {
items.append(element)
}
}
func dequeue() async -> Element {
if !items.isEmpty {
return items.removeFirst()
}
return await withCheckedContinuation { continuation in
waiters.append(continuation)
}
}
var count: Int { items.count }
}
// 使用示例
let queue = AsyncQueue<Int>()
Task {
await queue.enqueue(42)
}
Task {
let value = await queue.dequeue()
print("取出: \(value)")
}
这里有一个非常容易踩的坑：如果把Element的Sendable约束去掉，泛型参数本身不报错，但在跨任务传递包含该元素的值时，严格并发检查会失败。很多人会顺手写一个@unchecked Sendable来绕过检查，这是相当危险的做法，它等于告诉编译器别管了，出了数据竞争自己负责。只有在完全确认类型的内部同步机制（比如锁、队列调度）足够严密时才应该用它，并且最好写明注释解释为什么是安全的。
另一个坑是闭包。泛型容器的操作方法如果接收闭包参数，闭包默认是不Sendable的。Swift 5.7之后可以标记@Sendable闭包：
extension AsyncQueue {
// 闭包也必须声明为 @Sendable 才能跨隔离域使用
func dequeue(where predicate: @Sendable (Element) -> Bool) async -> Element? {
return items.first(where: predicate)
}
}
总结一下实践原则：值类型的泛型容器优先用条件遵循（where Value: Sendable），保持API的适用范围最大化；引用类型或actor容器在定义处直接约束泛型参数，语义更明确；永远不要用@unchecked Sendable掩盖你不确定的问题，而是把约束声明清楚，让编译器替你把关。这样写出来的泛型集合在Swift 6严格并发模式下可以放心地在任意任务间共享，并发安全由类型系统静态保证，而不是靠运行时的祈祷。
Swift Sendable泛型类型参数并发安全修改时间：2026-09-07 17:14:40