Jekyll2026-07-16T01:30:50+08:00https://sunsetwan.github.io/feed.xml日落大道Sunset Wan 的 Swift、iOS 与软件设计技术博客。Sunset Wan初识 The Composable Architecture（二）2026-02-04T21:37:39+08:002026-02-04T21:37:39+08:00https://sunsetwan.github.io/2026/02/04/tca-101-p2本文延续上一节对 TCA 的建模思路，聚焦「副作用」该如何在 reducer 中显式表达与测试。我们会把原本隐式的 I/O 操作抽象为 Effect，让 reducer 返回副作用，并进一步调整 combine/pullback 以支持一组 effect 的组合。通过 Favorite Primes 的保存/读取示例，展示从「纯函数」到「可追踪副作用」的演化过程。

Reducer 的副作用

同步副作用

我们在 FavoritePrimesAction 中新增一个 action：saveButtonTapped。

public enum FavoritePrimesAction {
  case deleteFavoritePrimes(IndexSet)
  case loadedFavoritePrimes([Int])
  case saveButtonTapped // 新增 action
}

// 在原本的 reducer 中新增对这个 action 的处理
...
case .saveButtonTapped:
  let data = try! JSONEncoder().encode(state)
  let documentsPath = NSSearchPathForDirectoriesInDomains(
    .documentDirectory, .userDomainMask, true
  )[0]
  let documentsUrl = URL(fileURLWithPath: documentsPath)
  try! data.write(
    to: documentsUrl.appendingPathComponent("favorite-primes.json")
  )
...

可以发现：favoritePrimesReducer 已经不再是纯函数了。它不只是根据输入（state + action）计算输出，而是隐式依赖外部世界（JSONEncoder 等），并且产生隐式输出（写数据至硬盘），这些都没有体现在函数签名里。换句话说，这个 reducer 在收到 action saveButtonTapped 时执行了副作用：把 favoritePrimes 数组写入硬盘。当你第一眼看到这个 reducer 时，很难看出它除了更新 state 之外还会写数据到硬盘。为这个 reducer 写测试会受外部状态影响（比如写入前磁盘已满），导致测试不稳定且成本高。

在 reducer 里直接执行副作用，会让函数有隐藏输入/输出，破坏可理解性与可测试性。

我们看一个简单的例子：

func compute(_ x: Int) -> Int {
  let computation = x * x + 1
  print("Computed \(computation)")
  return computation
}

compute 函数在计算完成后会返回结果。这样看来，它似乎满足纯函数的定义，但它的副作用是打印出计算结果，这种行为不可测试、也没体现在函数签名里。我们可以让 compute 函数返回「需要打印的内容」，由调用者决定是否真的打印，这样副作用就变成了显式输出。

func computeAndPrint(_ x: Int) -> (Int, [String]) {
  let computation = x * x + 1
  return (computation, ["Computed \(computation)"])
}

回看 Reducer 的函数签名：

public typealias Reducer<Value, Action> = (inout Value, Action) -> Void

我们需要定义一个结构体 Effect，代表 reducer 所执行的副作用，并显式返回这个副作用。

public typealias Effect = () -> Void
public typealias Reducer<Value, Action> = (inout Value, Action) -> Effect

更新 favoritePrimesReducer，这样写入硬盘的副作用就被显式返回。

case .saveButtonTapped:
  let state = state
  return {
    let data = try! JSONEncoder().encode(state)
    let documentsPath = NSSearchPathForDirectoriesInDomains(
      .documentDirectory, .userDomainMask, true
    )[0]
    let documentsUrl = URL(fileURLWithPath: documentsPath)
    try! data.write(
      to: documentsUrl.appendingPathComponent("favorite-primes.json")
    )
  }

如果我们往 FavoritePrimesAction 里新增一个 action loadButtonTapped 呢？在点击 Load 按钮后，从硬盘读取保存的 favoritePrimes 数组，再通过 action loadedFavoritePrimes 把结果发送回 store 中：

public enum FavoritePrimesAction {
  case deleteFavoritePrimes(IndexSet)
  case loadButtonTapped
  case loadedFavoritePrimes([Int])
  case saveButtonTapped
}

...
case .loadButtonTapped:
  return {
    let documentsPath = NSSearchPathForDirectoriesInDomains(
      .documentDirectory, .userDomainMask, true
    )[0]
    let documentsUrl = URL(fileURLWithPath: documentsPath)
    let favoritePrimesUrl = documentsUrl
      .appendingPathComponent("favorite-primes.json")
    guard
      let data = try? Data(contentsOf: favoritePrimesUrl),
      let favoritePrimes = try? JSONDecoder()
        .decode([Int].self, from: data)
      else { return }
    self.store.send(.loadedFavoritePrimes(favoritePrimes)) // Error: Use of unresolved identifier 'self'
  }

我们发现一个问题：reducer 里没有 self 或 store，副作用完成后无法把结果送回去更新状态。在视图里时，副作用可以直接 send action；但在 reducer 里，Effect 只是 () -> Void，只能「做完事就消失」，结果无法影响后续 state。因此需要调整模型：让 Effect 返回一个 Action，把副作用的结果封装成 action，再交给 reducer 处理。这样 effect 只负责最小工作量，状态更新仍由 reducer 完成，更清晰也更可测试。

并不是所有 effect 都需要回传数据。例如把 favoritePrimes 写入磁盘这种「一次性」的操作，并没有新的 action 要交给系统。因此更合理的做法是让 effect 返回一个可选的 action：需要回传时返回具体 action，不需要时返回 nil，由 store 忽略即可：

public typealias Effect<Action> = () -> Action?
public typealias Reducer<Value, Action> = (inout Value, Action) -> Effect<Action>

回看 combine 函数：

public func combine<Value, Action>(
  _ reducers: Reducer<Value, Action>...
) -> Reducer<Value, Action> {
  return { value, action in
    let effects = reducers.map { $0(&value, action) }
    return {
      for effect in effects {
        effect() // Warning: Result of call to function returning ‘Action?’ is unused
      }
    }
    ...
  }
}

假设这里是要组合三个 reducer，那么 combine 后得出的新 reducer 在收到一个 action 后，至多会产生三个副作用，这就无法只返回一个副作用。因此更合理的方案是让 reducer 返回多个 effect，这样组合 reducer 时就能把所有副作用完整保留：

public typealias Reducer<Value, Action> = (inout Value, Action) -> [Effect<Action>]

再看看 pullback 函数应如何更新：

public func pullback<LocalValue, GlobalValue, LocalAction, GlobalAction>(
  _ reducer: @escaping Reducer<LocalValue, LocalAction>,
  value: WritableKeyPath<GlobalValue, LocalValue>, // GlobalValue -> LocalValue
  action: WritableKeyPath<GlobalAction, LocalAction?> // GlobalAction -> LocalAction?
) -> Reducer<GlobalValue, GlobalAction> {
  return { globalValue, globalAction in
    guard let localAction = globalAction[keyPath: action] else { return [] }
    let localEffects = reducer(&globalValue[keyPath: value], localAction)
    return localEffects.map { localEffect in
      return {
        guard let localAction = localEffect() else { return nil }
        var globalAction = globalAction
        globalAction[keyPath: action] = localAction
        return globalAction
      }
    }
  }
}

pullback 函数接受一个局部 reducer 和两个 WritableKeyPath，返回一个全局 reducer。而返回的全局 reducer 需要返回一个副作用数组（[Effect<GlobalAction>]）。目标是返回 [Effect<GlobalAction>]，我们拥有的信息是 [Effect<LocalAction>] 和 WritableKeyPath<GlobalAction, LocalAction?>。不难想到：利用该 WritableKeyPath 和 localEffect() 得出的 localAction 来计算出 globalEffect 所需的 globalAction。

pullback 的实现虽然代码不少，但逻辑其实很清晰：它把「处理局部 state / action 的 reducer」提升为「处理全局 state / action 的 reducer」。之所以能做到这一点，是因为我们用 enum property 生成了 WritableKeyPath，可以从全局取出局部、再把局部改动写回全局。具体流程是：当全局 state 和 action 进入时，先用 WritableKeyPath 提取出局部 state / action，交给局部 reducer 处理，然后把更新后的局部 state 写回全局 state。

同时，局部 reducer 会产生一组局部 effect，这些 effect 可能会返回局部 action。我们再用 key path 把局部 action 嵌回全局 action，从而把局部 effect 变成全局 effect，并对数组逐个转换完成整个过程。

更新 favoritePrimesReducer：

public enum FavoritePrimesAction {
  case deleteFavoritePrimes(IndexSet)
  case loadButtonTapped
  case loadedFavoritePrimes([Int])
  case saveButtonTapped
}

public func favoritePrimesReducer(state: inout [Int], action: FavoritePrimesAction) -> [Effect<FavoritePrimesAction>] {
  switch action {
  case let .deleteFavoritePrimes(indexSet):
    for index in indexSet {
      state.remove(at: index)
    }
    return []

  case let .loadedFavoritePrimes(favoritePrimes):
    state = favoritePrimes
    return []

  case .saveButtonTapped:
    return [saveEffect(favoritePrimes: state)]

  case .loadButtonTapped:
    return [loadEffect]
  }
}

private func saveEffect(favoritePrimes: [Int]) -> Effect<FavoritePrimesAction> {
  return {
    let data = try! JSONEncoder().encode(favoritePrimes)
    let documentsPath = NSSearchPathForDirectoriesInDomains(
      .documentDirectory, .userDomainMask, true
    )[0]
    let documentsUrl = URL(fileURLWithPath: documentsPath)
    let favoritePrimesUrl = documentsUrl
      .appendingPathComponent("favorite-primes.json")
    try! data.write(to: favoritePrimesUrl)
    return nil // 不需要回传数据给 store，直接返回 nil
  }
}

private let loadEffect: Effect<FavoritePrimesAction> = {
  let documentsPath = NSSearchPathForDirectoriesInDomains(
    .documentDirectory, .userDomainMask, true
  )[0]
  let documentsUrl = URL(fileURLWithPath: documentsPath)
  let favoritePrimesUrl = documentsUrl
    .appendingPathComponent("favorite-primes.json")
  guard
    let data = try? Data(contentsOf: favoritePrimesUrl),
    let favoritePrimes = try? JSONDecoder().decode([Int].self, from: data)
    else { return nil }
  return .loadedFavoritePrimes(favoritePrimes) // 需要回传数据 favoritePrimes 数组
}

单向数据流

从上文的 loadButtonTapped 可以看出，导致状态变化的过程为：先运行 reducer、收集 effect，再执行 effect，把产出的 action 重新送回 reducer。这就是所谓的单向数据流：状态只能通过 action 进入 reducer 来改变。如果副作用想影响状态，也必须先生成新的 action，再由 reducer 统一处理。这种模式的优点是非常可理解——状态的变化只有一个入口；代价是需要额外的 action 来回传副作用结果。

异步副作用

如果想要 Effect<Action> 支持异步运行，我们还得修改它的函数签名。可以对比 URLSession 的 API 设计，从中汲取灵感：

func dataTask(
  with url: URL,
  completionHandler: @escaping (Data?, URLResponse?, (any Error)?) -> Void
) -> URLSessionDataTask

public typealias Effect<Action> = () -> Action? // 旧

public typealias Effect<Action> = (@escaping (Action) -> Void) -> Void // 新

在异步方法中持有这个闭包 (@escaping (Action) -> Void) -> Void，组装好 action 时，通过调用这个闭包把 action 传递出去。

再看看 pullback 函数应如何更新：

它需要把局部 effect 转换成全局 effect：做法是先执行局部 effect 拿到局部 action，再用回调把这个局部 action 嵌入到全局 action 中，从而得到可在全局环境里执行的 effect。

public func pullback<LocalValue, GlobalValue, LocalAction, GlobalAction>(
  _ reducer: @escaping Reducer<LocalValue, LocalAction>,
  value: WritableKeyPath<GlobalValue, LocalValue>,
  action: WritableKeyPath<GlobalAction, LocalAction?>
) -> Reducer<GlobalValue, GlobalAction> {
  return { globalValue, globalAction in
    guard let localAction = globalAction[keyPath: action] else { return [] }
    let localEffects = reducer(&globalValue[keyPath: value], localAction)
    return localEffects.map { localEffect in
      { callback in
        localEffect { localAction in
          var globalAction = globalAction
          globalAction[keyPath: action] = localAction
          callback(globalAction)
        }
      }
    }
  }
}

使用 Combine 优化

能不能把 Effect 变成一个 Publisher，利用 Combine 来实现异步副作用呢？答案是可以的！

public struct Effect<Output>: Publisher {
  public typealias Failure = Never

  let publisher: AnyPublisher<Output, Failure>

  public func receive<S>(
    subscriber: S
  ) where S: Subscriber, Failure == S.Failure, Output == S.Input {
    self.publisher.receive(subscriber: subscriber)
  }
}

我们接着更新 Store 中的 send 方法：

private var effectCancellables: Set<AnyCancellable> = []
...

public func send(_ action: Action) {
  let effects = self.reducer(&self.value, action)
  effects.forEach { effect in
    var effectCancellable: AnyCancellable!
    effectCancellable = effect.sink(
      receiveCompletion: { [weak self] _ in
        self?.effectCancellables.remove(effectCancellable)
      },
      receiveValue: self.send
    )
    self.effectCancellables.insert(effectCancellable)
  }
}
  1. 当 effect 收到结果时，继续调用 self.send，把副作用结果传递出去。
  2. 当 effect 停止发送元素时，移除掉之前保存下来的订阅 token（AnyCancellable）。
  3. 当 effect 订阅完毕后，保存订阅 token 至 effectCancellables。

乍一看这个逻辑似乎没问题，但当遇到没有副作用的 action 时，就会有问题了！我们先来看个小例子：

import Combine

let pub: AnyPublisher = Empty<Void, Never>(completeImmediately: true).eraseToAnyPublisher()
var set: Set<AnyCancellable> = []
var cancellable: AnyCancellable!

cancellable = pub.sink { _ in
  print("Received Completion")
  set.remove(cancellable) // 崩溃发生在此处
} receiveValue: { _ in
  print("Do nothing!")
}

print("insert cancellable")
set.insert(cancellable)

// Received Completion
// __lldb_expr_3/MyPlayground.playground:11: Fatal error: Unexpectedly found nil while implicitly unwrapping an Optional value

当我们订阅一个立即结束的 Publisher 时，在 sink 函数返回之前，Combine 就会触发 receiveCompletion 闭包。所以可以考虑把 cancellable 改为显式可选值 AnyCancellable?：

var effectCancellable: AnyCancellable?
effectCancellable = effect.sink(
  receiveCompletion: { [weak self] _ in
    guard let effectCancellable = effectCancellable else { return }
    self?.effectCancellables.remove(effectCancellable)
  },
  receiveValue: self.send
)
if let effectCancellable = effectCancellable {
  effectCancellables.insert(effectCancellable)
}

这样又带来另一个问题：当我们订阅一个立即结束的 Publisher 时，先调用 receiveCompletion，并不会移除当前订阅 token，因为 sink 函数还没返回。当 sink 函数执行完后，我们把当前订阅 token 加入 effectCancellables 中。不难发现：我们没有移除这个订阅 token 的时机了！我们还得新增一个 flag didComplete 来标记当前 effect 是否结束：

var effectCancellable: AnyCancellable?
var didComplete = false
effectCancellable = effect.sink(
  receiveCompletion: { [weak self] _ in
    didComplete = true
    guard let effectCancellable = effectCancellable else { return }
    self?.effectCancellables.remove(effectCancellable)
  },
  receiveValue: { [weak self] in self?.send($0) }
)
if !didComplete, let effectCancellable = effectCancellable { // 在当前 effect 未结束时，且有对应的订阅 token，才把它加入 effectCancellables 中
  effectCancellables.insert(effectCancellable)
}

但这里还有 1 处内存泄漏：effectCancellable 是 sink 的返回值，因此它强引用订阅者（Subscribers.Sink）。Subscribers.Sink 又强引用传入的 receiveCompletion / receiveValue 闭包；而这些闭包捕获了 effectCancellable 本身，于是形成了 AnyCancellable → Subscribers.Sink → 闭包 → AnyCancellable 的强引用环。

我们现在的做法是用 effectCancellable 自己本身来定位在集合 effectCancellables 中的位置，因为 AnyCancellable 遵循 Hashable 协议。换个思路，我们可以给每个 effectCancellable 创建独一无二的 UUID，这样 receiveCompletion 闭包就不需要强引用 effectCancellable 本身，从而达到删除 effectCancellable 的目的！把 effectCancellables 的类型从 Set<AnyCancellable> 改为 [UUID: AnyCancellable] 即可：

private var effectCancellables: [UUID: AnyCancellable] = [:]

public func send(_ action: Action) {
  let effects = self.reducer(&self.value, action)
  effects.forEach { effect in
    var didComplete = false
    let uuid = UUID()

    let effectCancellable = effect.sink(
      receiveCompletion: { [weak self] _ in
        didComplete = true
        self?.effectCancellables[uuid] = nil
      },
      receiveValue: { [weak self] in self?.send($0) }
    )

    if !didComplete {
      self.effectCancellables[uuid] = effectCancellable
    }
  }
}

结语

下次再聊 TCA 中的 Dependency Injection 与 Testing。

]]>Sunset Wan初识 The Composable Architecture（一）2026-01-26T15:22:14+08:002026-01-26T15:22:14+08:00https://sunsetwan.github.io/2026/01/26/tca-101-p1Reducer 
public enum CounterAction {
  case decrTapped
  case incrTapped
}

func counterReducer(
  state: AppState, action: CounterAction
) -> AppState {
  var copy = state
  switch action {
  case .decrTapped:
    copy.count -= 1
  case .incrTapped:
    copy.count += 1
  }
  return copy
}

上面的代码是个标准的 reducer 结构：当收到 incrTapped 时，修改全局状态（计数加一），再返回新的全局状态。为什么称这样的结构为 reducer？

参考这样的 函数签名：

func reduce<Result>(
    _ initialResult: Result,
    _ nextPartialResult: (Result, Self.Element) throws -> Result
) rethrows -> Result

其中 reducer 对应的正是 reduce 中的 nextPartialResult 部分，这也是我们将它称为 reducer 的原因。

Sequence 协议中还有 另一种 reduce 签名：

func reduce<Result>(
    into initialResult: Result,
    _ updateAccumulatingResult: (inout Result, Self.Element) throws -> ()
) rethrows -> Result

不难得出：(A, B) -> A 可以改写为 (inout A, B) -> Void。在工程实践中，AppState 迭代一段时间后，可能是个很大的结构体，使用 inout 可提升性能。

func counterReducer(value: inout AppState, action: CounterAction) {
  switch action {
  case .decrTapped:
    value.count -= 1
  case .incrTapped:
    value.count += 1
  }
}

纯函数（pure function）通常满足两点：

  1. 相同输入必然产生相同输出
  2. 没有副作用（不修改外部对象）

counterReducer 就是一个典型的纯函数。纯函数（我觉得）最吸引人的特点就是写单元测试很方便：不依赖外部环境，单元测试只要给定输入和断言输出即可，测试简单且稳定。

再看这样两个 reducer：primeModalReducer 和 favoritePrimesReducer。

public enum PrimeModalAction {
  case saveFavoritePrimeTapped
  case removeFavoritePrimeTapped
}

public func primeModalReducer(state: inout AppState, action: PrimeModalAction) {
  switch action {
  case .removeFavoritePrimeTapped:
    state.favoritePrimes.removeAll(where: { $0 == state.count })

  case .saveFavoritePrimeTapped:
    state.favoritePrimes.append(state.count)
  }
}

public enum FavoritePrimesAction {
  case deleteFavoritePrimes(IndexSet)
}

public func favoritePrimesReducer(state: inout AppState, action: FavoritePrimesAction) {
  switch action {
  case let .deleteFavoritePrimes(indexSet):
    state.favoritePrimes.remove(atOffsets: indexSet)
  }
}

那么如果一个 app 的逻辑由这三个 reducer 组成，我们就需要把这三种 reducer 对应的 action 也组合在一块，不难想到：

enum AppAction {
  case counter(CounterAction)
  case primeModal(PrimeModalAction)
  case favoritePrimes(FavoritePrimesAction)
}

三个 reducer 的函数签名也得一并调整：

func counterReducer(state: inout AppState, action: AppAction) {
  switch action {
  case .counter(.decrTapped):
    state.count -= 1

  case .counter(.incrTapped):
    state.count += 1

  default:
    break
  }
}

func primeModalReducer(state: inout AppState, action: AppAction) {
  switch action {
  case .primeModal(.removeFavoritePrimeTapped):
    state.favoritePrimes.removeAll(where: { $0 == state.count })
    state.activityFeed.append(.init(timestamp: Date(), type: .removedFavoritePrime(state.count)))

  case .primeModal(.saveFavoritePrimeTapped):
    state.favoritePrimes.append(state.count)
    state.activityFeed.append(.init(timestamp: Date(), type: .addedFavoritePrime(state.count)))

  default:
    break
  }
}

func favoritePrimesReducer(state: inout AppState, action: AppAction) {
  switch action {
  case let .favoritePrimes(.deleteFavoritePrimes(indexSet)):
    let removedPrimes = indexSet.map { state.favoritePrimes[$0] }
    state.favoritePrimes.remove(atOffsets: indexSet)
    for prime in removedPrimes {
      state.activityFeed.append(.init(timestamp: Date(), type: .removedFavoritePrime(prime)))
    }

  default:
    break
  }
}

得出整个 app 最大的 reducer：

func appReducer(value: inout AppState, action: AppAction) -> Void {
  switch action {
  case .counter(.decrTapped):
    value.count -= 1

  case .counter(.incrTapped):
    value.count += 1

  case .primeModal(.saveFavoritePrimeTapped):
    value.favoritePrimes.append(value.count)
    value.activityFeed.append(.init(timestamp: Date(), type: .addedFavoritePrime(value.count)))

  case .primeModal(.removeFavoritePrimeTapped):
    value.favoritePrimes.removeAll(where: { $0 == value.count })
    value.activityFeed.append(.init(timestamp: Date(), type: .removedFavoritePrime(value.count)))

  case let .favoritePrimes(.deleteFavoritePrimes(indexSet)):
    let removedPrimes = indexSet.map { value.favoritePrimes[$0] }
    value.favoritePrimes.remove(atOffsets: indexSet)
    for prime in removedPrimes {
      value.activityFeed.append(.init(timestamp: Date(), type: .removedFavoritePrime(prime)))
    }
  }
}

整个 app reducer 只是把三种局部 reducer 里的逻辑拷贝过来。可以想象，随着业务的迭代，整个 app reducer 会迅速膨胀。如果三个 reducer 能像乐高积木一样，组成一个最大的 app reducer 就好了！

How to be composable?

当 app reducer 收到某个 action 时，它如果可以直接把 action 分发到每个 reducer，让每个 reducer 独立决定是否处理这个 action 就好了！顺着这个思路，我们可以写出这样的 combine 函数：

func combine<Value, Action>(
  _ reducers: (inout Value, Action) -> Void...
) -> (inout Value, Action) -> Void {

  return { value, action in
    for reducer in reducers {
      reducer(&value, action)
    }
  }
}

那么，app reducer 可简化为：

let appReducer = combine(
  counterReducer,
  primeModalReducer,
  favoritePrimesReducer
)

回看现在的 counterReducer，总感觉哪里怪怪的：它知道得太多了！它只需要知道它负责把一个 inout Int 加加减减就够了！它只需要在意 .incrTapped 和 .decrTapped 这两个 action 就行了！最终目标是 func counterReducer(state: inout Int, action: CounterAction) { ... }，但我们先只简化 State，Action 暂时保留 AppAction。

// 最终目标：func counterReducer(state: inout Int, action: CounterAction) { ... }
func counterReducer(state: inout AppState, action: AppAction) {
  switch action {
  case .counter(.decrTapped):
    state.count -= 1

  case .counter(.incrTapped):
    state.count += 1

  default:
    break
  }
}

简化 State

这一步我们想要这样的 counterReducer：(inout Int, AppAction) -> Void，整个 app reducer 是 (inout AppState, AppAction) -> Void。我们需要新定义个 transform 函数来帮助完成这样的类型转换：

func transform<LocalValue, GlobalValue, Action>(
  _ reducer: @escaping (inout LocalValue, Action) -> Void
) -> (inout GlobalValue, Action) -> Void {
  return { globalValue, action in
    // Call the reducer
  }
}

这里先用 transform 占位，实际我们会用 pullback 来完成这个映射。所有的局部 reducer 都得通过这种变换，变为 (inout AppState, AppAction) -> Void，才能不破坏上面多个小 reducer combine 为一个大 reducer 的逻辑。

我们需要 f: (GlobalValue) -> LocalValue 这样的变化，然后再调用 reducer：

func pullback<LocalValue, GlobalValue, Action>(
  _ reducer: @escaping (inout LocalValue, Action) -> Void,
  _ f: @escaping (GlobalValue) -> LocalValue
) -> (inout GlobalValue, Action) -> Void {

  return { globalValue, action in
    var localValue = f(globalValue)
    reducer(&localValue, action)
  }
}

这样的变化，可取名叫 pullback，意味从局部 reducer 拉回至全局的 reducer。

上面的实现仅改变了 localValue，并没有把 localValue 的改变反射回 globalValue 上，还需新增 s: (inout GlobalValue, LocalValue) -> Void。f 更名为 get，s 更名为 set。

func pullback<LocalValue, GlobalValue, Action>(
  _ reducer: @escaping (inout LocalValue, Action) -> Void,
  get: @escaping (GlobalValue) -> LocalValue,
  set: @escaping (inout GlobalValue, LocalValue) -> Void
) -> (inout GlobalValue, Action) -> Void {

  return { globalValue, action in
    var localValue = get(globalValue)
    reducer(&localValue, action)
    set(&globalValue, localValue)
  }
}

在 Swift 中，一对 getter 和 setter 可以用 WritableKeyPath 来简化：

func pullback<LocalValue, GlobalValue, Action>(
  _ reducer: @escaping (inout LocalValue, Action) -> Void,
  value: WritableKeyPath<GlobalValue, LocalValue>
) -> (inout GlobalValue, Action) -> Void {
  return { globalValue, action in
    reducer(&globalValue[keyPath: value], action)
  }
}

struct FavoritePrimesState {
  var favoritePrimes: [Int]
  var activityFeed: [AppState.Activity]
}

func favoritePrimesReducer(state: inout FavoritePrimesState, action: AppAction) {
  switch action {
  case let .favoritePrimes(.deleteFavoritePrimes(indexSet)):
    let removedPrimes = indexSet.map { state.favoritePrimes[$0] }
    state.favoritePrimes.remove(atOffsets: indexSet)
    for prime in removedPrimes {
      state.activityFeed.append(.init(timestamp: Date(), type: .removedFavoritePrime(prime)))
    }

  default:
    break
  }
}

extension AppState {
  var favoritePrimesState: FavoritePrimesState {
    get {
      FavoritePrimesState(
        favoritePrimes: self.favoritePrimes,
        activityFeed: self.activityFeed
      )
    }
    set {
      self.favoritePrimes = newValue.favoritePrimes
      self.activityFeed = newValue.activityFeed
    }
  }
}

func primeModalReducer(state: inout AppState, action: AppAction) {
  switch action {
  case .primeModal(.removeFavoritePrimeTapped):
    state.favoritePrimes.removeAll(where: { $0 == state.count })
    state.activityFeed.append(.init(timestamp: Date(), type: .removedFavoritePrime(state.count)))

  case .primeModal(.saveFavoritePrimeTapped):
    state.favoritePrimes.append(state.count)
    state.activityFeed.append(.init(timestamp: Date(), type: .addedFavoritePrime(state.count)))

  default:
    break
  }
}

// 直接操作必须要用到的状态，剔除多余的状态
func counterReducer(state: inout Int, action: AppAction) {
  switch action {
  case .counter(.decrTapped):
    state -= 1

  case .counter(.incrTapped):
    state += 1

  default:
    break
  }
}

let appReducer = combine(
  pullback(counterReducer, value: \.count),
  primeModalReducer,
  pullback(favoritePrimesReducer, value: \.favoritePrimesState)
)

简化 Action

counterReducer 中仅使用 AppAction 中 counter 下的 actions，其他 enum case 默认不处理。这样也是易错的，app reducer 收到所有的 action 通通都会发送给这三个局部 reducer，如果局部 reducer 处理了不属于自己职责范围内的 action，就会出现 BUG！

func counterReducer(state: inout Int, action: CounterAction) {
  switch action {
  case .decrTapped:
    state -= 1

  case .incrTapped:
    state += 1
  }
}

同样地，我们也要把 counterReducer 能感知到的 action 简化至它仅需的 CounterAction！

我们需要这样的变换：

func pullback<Value, GlobalAction, LocalAction>(
  _ reducer: @escaping (inout Value, LocalAction) -> Void,
  action: WritableKeyPath<GlobalAction, LocalAction?>
) -> (inout Value, GlobalAction) -> Void {

  return { value, globalAction in
    guard let localAction = globalAction[keyPath: action]
    else { return }

    reducer(&value, localAction)
  }
}

为什么 action: WritableKeyPath<GlobalAction, LocalAction?> 中 LocalAction 是可选呢？

Swift 中没有类似的 enum KeyPath 概念：

struct EnumKeyPath<Root, Value> {
  let embed: (Value) -> Root
  let extract: (Root) -> Value?
}

通过手动创建计算属性后，我们可以看到 getter 始终返回的是可选值。

enum AppAction {
  case counter(CounterAction)
  ...

  var counter: CounterAction? {
    get {
      guard case let .counter(value) = self else { return nil }
      return value
    }
    set {
      guard case .counter = self, let newValue = newValue else { return }
      self = .counter(newValue)
    }
  }
  ...
}

合并两种 pullback

func pullback<GlobalValue, LocalValue, GlobalAction, LocalAction>(
  _ reducer: @escaping (inout LocalValue, LocalAction) -> Void,
  value: WritableKeyPath<GlobalValue, LocalValue>,
  action: WritableKeyPath<GlobalAction, LocalAction?>
) -> (inout GlobalValue, GlobalAction) -> Void {

  return { globalValue, globalAction in
    guard let localAction = globalAction[keyPath: action]
    else { return }

    reducer(&globalValue[keyPath: value], localAction)
  }
}

（我当时第一眼看到这样的函数签名，我也是惊呆的！）

enum CounterAction {
  case decrTapped
  case incrTapped
}

func counterReducer(state: inout Int, action: CounterAction) {
  switch action {
  case .decrTapped:
    state -= 1

  case .incrTapped:
    state += 1
  }
}

enum PrimeModalAction {
  case saveFavoritePrimeTapped
  case removeFavoritePrimeTapped
}

func primeModalReducer(state: inout AppState, action: PrimeModalAction) -> Void {
  switch action {
  case .removeFavoritePrimeTapped:
    state.favoritePrimes.removeAll(where: { $0 == state.count })
    state.activityFeed.append(.init(timestamp: Date(), type: .removedFavoritePrime(state.count)))

  case .saveFavoritePrimeTapped:
    state.favoritePrimes.append(state.count)
    state.activityFeed.append(.init(timestamp: Date(), type: .addedFavoritePrime(state.count)))
  }
}

enum FavoritePrimesAction {
  case deleteFavoritePrimes(IndexSet)
}

func favoritePrimesReducer(state: inout FavoritePrimesState, action: FavoritePrimesAction) -> Void {
  switch action {
  case let .deleteFavoritePrimes(indexSet):
    let removedPrimes = indexSet.map { state.favoritePrimes[$0] }
    state.favoritePrimes.remove(atOffsets: indexSet)
    for prime in removedPrimes {
      state.activityFeed.append(.init(timestamp: Date(), type: .removedFavoritePrime(prime)))
    }
  }
}

let appReducer: (inout AppState, AppAction) -> Void = combine(
  pullback(counterReducer, value: \.count, action: \.counter),
  pullback(primeModalReducer, value: \.self, action: \.primeModal),
  pullback(favoritePrimesReducer, value: \.favoritePrimesState, action: \.favoritePrimes)
)

到这一步，counterReducer 和 favoritePrimesReducer 完完全全地专注于自己所需的 State 和 Action，这就为后续的模块化提供了便利！primeModalReducer 仍需直接操作 AppState，所以这里使用 \.self。

Higher order reducer

高阶函数（higher‑order function）的定义：接受函数/闭包作为参数，或返回函数/闭包。那么「高阶 reducer」到底长什么样？函数既把 reducer 当输入，又把 reducer 当输出，这意味着什么？事实上，我们已经遇到过了：

  • combine 是一个高阶 reducer：它接收多个 reducer 作为输入（只要它们处理的 state 和 action 类型一致），然后把每个 reducer 都跑一遍，返回一个全新的 reducer。
  • pullback 也是一个高阶 reducer：它接收一个 reducer 作为输入，并通过对局部 state 和 action 的 KeyPath 映射，返回一个作用在更全局 state 和 action 上的新 reducer。

在下面这两个 reducer 中，你会发现他们在自己的 action 中，还额外多做了更新 activityFeed 的事情。要么在各自 action 枚举中新增更新 activityFeed 的 action，要么把这部分逻辑挪出去，交给另一个 reducer 处理。

func favoritePrimesReducer(state: inout FavoritePrimesState, action: FavoritePrimesAction) -> Void {
  switch action {
  case let .deleteFavoritePrimes(indexSet):
    let removedPrimes = indexSet.map { state.favoritePrimes[$0] }
    state.favoritePrimes.remove(atOffsets: indexSet)
    for prime in removedPrimes {
      state.activityFeed.append( // 更新 activity feed
        .init(
          timestamp: Date(),
          type: .removedFavoritePrime(prime)
        )
      )
    }
  }
}

func primeModalReducer(state: inout AppState, action: PrimeModalAction) -> Void {
  switch action {
  case .removeFavoritePrimeTapped:
    state.favoritePrimes.removeAll(where: { $0 == state.count })
    state.activityFeed.append( // 更新 activity feed
      .init(
        timestamp: Date(),
        type: .removedFavoritePrime(state.count)
      )
    )

  case .saveFavoritePrimeTapped:
    state.favoritePrimes.append(state.count)
    state.activityFeed.append( // 更新 activity feed
      .init(
        timestamp: Date(),
        type: .addedFavoritePrime(state.count)
      )
    )
  }
}

下面演示把这段更新逻辑挪到高阶 reducer 中，所以请理解为局部 reducer 不再写 activityFeed（否则会重复记录）。我们可以自定义一个高阶 reducer，名叫 activityFeed，放入更新 activityFeed 的逻辑。

func activityFeed(
  _ reducer: @escaping (inout AppState, AppAction) -> Void
) -> (inout AppState, AppAction) -> Void {

  return { state, action in
    switch action {
    case .counter:
      break

    case .primeModal(.removeFavoritePrimeTapped):
      state.activityFeed.append(
        .init(
          timestamp: Date(),
          type: .removedFavoritePrime(state.count)
        )
      )

    case .primeModal(.saveFavoritePrimeTapped):
      state.activityFeed.append(
        .init(
          timestamp: Date(),
          type: .addedFavoritePrime(state.count)
        )
      )

    case let .favoritePrimes(.deleteFavoritePrimes(indexSet)):
      let removedPrimes = indexSet.map { state.favoritePrimes[$0] }
      for prime in removedPrimes {
        state.activityFeed.append(
          .init(
            timestamp: Date(),
            type: .removedFavoritePrime(prime)
          )
        )
      }
    }

    reducer(&state, action)
  }
}


let appReducer: (inout AppState, AppAction) -> Void = combine(
  pullback(counterReducer, value: \.count, action: \.counter),
  pullback(primeModalReducer, value: \.self, action: \.primeModal),
  pullback(favoritePrimesReducer, value: \.favoritePrimesState, action: \.favoritePrimes)
)

let withActivityFeed = activityFeed(appReducer)

不难看出：高阶 reducer 的作用像一种 state 和 action 过滤器！在这样的架构下，打日志自然是方便许多的！

func logging<Value, Action>(
  _ reducer: @escaping (inout Value, Action) -> Void
) -> (inout Value, Action) -> Void {
  return { value, action in
    reducer(&value, action)
    print("Action: \(action)")
    print("State:")
    dump(value)
    print("---")
  }
}

let withLogging = logging(activityFeed(appReducer))

Store

Reducer 定义了状态变化的核心逻辑，它本质上只是一个函数，那谁负责持有状态并分发出去呢？是 Store！Store 是运行时核心对象，持有当前状态，接收 Action，然后调用 reducer 处理 action、更新状态，并分发至 View。

public final class Store<Value, Action>: ObservableObject {
    private let reducer: (inout Value, Action) -> Void
    @Published public private(set) var value: Value

    public init(initialValue: Value, reducer: @escaping (inout Value, Action) -> Void) {
        self.reducer = reducer
        self.value = initialValue
    }

    public func send(_ action: Action) {
        self.reducer(&self.value, action)
    }
}

ViewState

struct IsPrimeModalView: View {
  @ObservedObject var store: Store<AppState, AppAction>

  var body: some View {
    VStack {
      if isPrime(store.value.count) {
        Text("\(store.value.count) is prime 🎉")
        if store.value.favoritePrimes.contains(store.value.count) {
          Button("Remove from favorite primes") {
            store.send(.primeModal(.removeFavoritePrimeTapped))
          }
        } else {
          Button("Save to favorite primes") {
            store.send(.primeModal(.saveFavoritePrimeTapped))
            store.send(.counter(.decrTapped)) // ? 易错！发送不属于自己应该关注的 action
          }
        }
      } else {
        Text("\(store.value.count) is not prime :(")
      }
    }
  }
}

...
    .sheet(isPresented: self.$isPrimeModalShown) {
      IsPrimeModalView(store: self.store)
    }

IsPrimeModalView 中持有了全局的 store，很容易发送不属于自己应该关注的 action。如果能把 action 限定为 PrimeModalAction，这样在编译时就能发现问题所在了！再者，向 IsPrimeModalView 暴露了全局状态，View 上压根用不上这么多状态，同时也阻碍了模块的拆分。

与 reducer 全局 state、全局 action 的拆分类似，对于 Store 而言，也需要将其拆分为聚焦于局部 state 和局部 action 的局部 store！

简化 State

我们可以这样做 (Value) -> LocalValue 的变换：

  func map<LocalValue>(_ f: @escaping (Value) -> LocalValue) -> Store<LocalValue, Action> {
    return Store<LocalValue, Action>(
      initialValue: f(self.value),
      reducer: { localValue, action in
        self.send(action)
        let updatedLocalValue = f(self.value)
        localValue = updatedLocalValue
      }
    )
  }

那我们新建一个 playground 来看下运行效果：

let store = Store<Int, Void>(initialValue: 0, reducer: { count, _ in
  count += 1
})

store.send(()) // value: 1
store.send(()) // value: 2
store.send(()) // value: 3
store.send(()) // value: 4
store.send(()) // value: 5

store.value // value: 5

let newStore = store.map { $0 }

newStore.value // new value: 5
newStore.send(()) // new value: 6
newStore.send(()) // new value: 7
newStore.send(()) // new value: 8
newStore.value // new value: 8

store.value // value: 8

通过运行结果可以看出：newStore 收到的 action 不光会更新自己的 value，还会同步更新至 store。因为 map 创建的 newStore 不是独立的「副本」，而是转发到原始 store 的「映射」：

  • newStore.send(()) 会执行它的 reducer。
  • 这个 reducer 里第一句是 self.send(action)，也就是把 action 发送给原始 store。
  • 原始 store 的 reducer 会把 value 加 1。
  • 然后 newStore 再用 f(self.value) 把原始 store 的最新值同步到自己的 localValue。

所以 newStore 的每次 send 都会更新原始 store.value，因此最后原始 value 也变成 8。

这其实正是我们想要的效果：局部 store 收到 action 后产生的状态变化能正确投射到全局 store 上！

那反过来呢？全局 store 的状态没法与局部 store 的状态同步！

store.value // value: 8

store.send(()) // value: 9
store.send(()) // value: 10
store.send(()) // value: 11

newStore.value // new value: 8
store.value // value: 11

现在的局部 store 只能把自己的动作转发给全局 store（因为它直接调用了全局 store 的 send），所以能把变化传上去；但它没有办法从全局 store 接收后续的状态更新。如果局部 store 能监听全局 store 的状态变化，就可以把全局的新状态同步到局部状态，从而保持一致。

在 Swift 中，@Published 是 Combine 的属性包装器，它会生成一个投影值 projectedValue，用 $ 访问。这个投影值的类型是 Published<Value>.Publisher，它遵循 Publisher 协议，所以 $value 本质上就是一个 Publisher。局部 store 用 self.$value.sink 订阅全局 value 的发布流。每当全局 value 变化，就通过 f 映射成 LocalValue，并更新局部 localStore.value，最后把订阅存到 localStore.cancellable，保证监听持续存在。

  func map<LocalValue>(
    _ f: @escaping (Value) -> LocalValue
  ) -> Store<LocalValue, Action> {
    let localStore = Store<LocalValue, Action>(
      initialValue: f(self.value),
      reducer: { localValue, action in
        self.send(action)
        localValue = f(self.value)
      }
    )
    localStore.cancellable = self.$value.sink { [weak localStore] newValue in
      localStore?.value = f(newValue)
    }
    return localStore
  }

简化 Action

类似地，如果我们知道 f: @escaping (LocalAction) -> Action 这样的变换，就可以把 Store<Value, Action> 变为 Store<Value, LocalAction>。

  public func map<LocalAction>(
    f: @escaping (LocalAction) -> Action
  ) -> Store<Value, LocalAction> {
    return Store<Value, LocalAction>(
      initialValue: self.value,
      reducer: { value, localAction in
        self.send(f(localAction))
        value = self.value
      }
    )
  }

合并两种 map

并改名为 view，因为该方法返回的不是一个「独立的新 store」，而是原 store 的一个投影！通过 toLocalValue 把全局 Value 映射成局部 LocalValue，局部 store 只看到「局部视角」的状态。局部 store 只能发送 LocalAction，再被 toGlobalAction 转成全局 Action。也就是说，局部 store 只能发一个局部动作集合。数据源仍是全局 value。局部 store 订阅 $value，始终跟随全局 state 更新；它不拥有自己的状态源。

    public func view<LocalValue, LocalAction>(
        value toLocalValue: @escaping (Value) -> LocalValue,
        action toGlobalAction: @escaping (LocalAction) -> Action
    ) -> Store<LocalValue, LocalAction> {
        let localStore = Store<LocalValue, LocalAction>(
            initialValue: toLocalValue(value),
            reducer: { localValue, localAction in
                self.send(toGlobalAction(localAction))
                localValue = toLocalValue(self.value)
            }
        )
        localStore.cancellable = $value.sink { [weak localStore] newValue in
            localStore?.value = toLocalValue(newValue)
        }
        return localStore
    }

回顾一下现在 Store 的代码：

public final class Store<Value, Action>: ObservableObject {
    private let reducer: (inout Value, Action) -> Void
    @Published public private(set) var value: Value
    private var cancellable: Cancellable?

    public init(initialValue: Value, reducer: @escaping (inout Value, Action) -> Void) {
        self.reducer = reducer
        self.value = initialValue
    }

    public func send(_ action: Action) {
        self.reducer(&self.value, action)
    }

    public func view<LocalValue, LocalAction>(
        value toLocalValue: @escaping (Value) -> LocalValue,
        action toGlobalAction: @escaping (LocalAction) -> Action
    ) -> Store<LocalValue, LocalAction> {
        let localStore = Store<LocalValue, LocalAction>(
            initialValue: toLocalValue(value),
            reducer: { localValue, localAction in
                self.send(toGlobalAction(localAction))
                localValue = toLocalValue(self.value)
            }
        )
        localStore.cancellable = $value.sink { [weak localStore] newValue in
            localStore?.value = toLocalValue(newValue)
        }
        return localStore
    }
}

以本节开头提到的 IsPrimeModalView 为例，让我们看看如何修改：

public typealias PrimeModalState = (count: Int, favoritePrimes: [Int])

public struct IsPrimeModalView: View {
  @ObservedObject var store: Store<PrimeModalState, PrimeModalAction>

  public init(store: Store<PrimeModalState, PrimeModalAction>) {
    self.store = store
  }

  public var body: some View {
    VStack {
      if isPrime(self.store.value.count) {
        Text("\(self.store.value.count) is prime 🎉")
        if self.store.value.favoritePrimes.contains(self.store.value.count) {
          Button("Remove from favorite primes") {
            self.store.send(.removeFavoritePrimeTapped)
          }
        } else {
          Button("Save to favorite primes") {
            self.store.send(.saveFavoritePrimeTapped)
          }
        }
      } else {
        Text("\(self.store.value.count) is not prime :(")
      }
    }
  }
}


...
    .sheet(isPresented: self.$isPrimeModalShown) {
        IsPrimeModalView(
            store: self.store
                .view( // 投射出一个局部 Store
                    value: { ($0.count, $0.favoritePrimes) },
                    action: { .primeModal($0) }
                )
        )
    }

结语

叽里咕噜说了一大堆，第一部分就写到这里吧，目前为止展示的示例代码可在这里看。

下次介绍 reducer 在收到 action 后还可以执行一些副作用（Side Effects）。比如说，我收到一个 action，需要发送一个网络请求，等网络请求结束后，根据结果再执行不同的 action。

]]>Sunset WanWebSocket 协议学习笔记2026-01-25T10:48:23+08:002026-01-25T10:48:23+08:00https://sunsetwan.github.io/2026/01/25/WebSocket-note工作项目用了 Socket.IO 来做客户端与服务端的实时通信，我看了 Socket.IO 是基于 WebSocket 协议进一步封装的。于是，我希望通过实现 WebSocket 客户端 的 一小部分 功能，以达到了解 WebSocket 协议的目标！

  1. 教科书：RFC 6455
  2. 老师：Codex
  3. 代码仓库地址：WebSocketClient-Demo

WebSocket 协议简介

WebSocket 协议是一种能让客户端（浏览器）与服务端进行双向通信的协议。该协议由基于传输控制协议（Transmission Control Protocol, TCP）的打开握手与后续的基本消息成帧组成。

建立连接时的握手阶段

客户端发起握手

WebSocket 在握手阶段是利用 HTTP GET 请求来与服务端建立连接的，但对于 HTTP 有版本要求：至少大于等于 1.1。

常见的客户端发起握手请求头如下：

        GET /chat HTTP/1.1
        Host: server.example.com
        Upgrade: websocket
        Connection: Upgrade
        Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
        Sec-WebSocket-Version: 13

以下是握手中必须包含的关键头字段：Upgrade，Connection，Sec-WebSocket-Key，Sec-WebSocket-Version。且根据协议的定义：

  1. Upgrade: websocket
  2. Connection: Upgrade
  3. Sec-WebSocket-Version: 13

这三组键值对是固定的（大小写不敏感）。

如何计算出 Sec-WebSocket-Key？

首先，设客户端随机生成 16 个字节长度的随机数为 A，再对 A 做 Base64 编码，得出的结果就是该 Key 对应的 value。客户端每次开始握手都得重新生成一次，不可重复。

为什么需要 Sec-WebSocket-Key？

它用于让服务端根据该随机值生成 Sec-WebSocket-Accept，客户端再进行校验，从而确认对端确实理解并接受 WebSocket 握手。

实现客户端握手中产生的思考

因为是基于 NWConnection 利用 TCP 协议直接发送 GET 请求头，所以我们得自己 手动调整字符串 构造 Data，以遵循 HTTP 请求头的格式。这一开始把我难到了，意识到还需多复习 HTTP 协议。

服务端响应握手

服务端会阅读客户端请求头，并检查是否符合以下几点：

  1. GET 请求且 HTTP 版本至少为 1.1
  2. 得有键值对 Upgrade: websocket（大小写不敏感）
  3. 得有键值对 Connection: Upgrade（大小写不敏感）
  4. 得有键值对 Sec-WebSocket-Version: 13（大小写不敏感）
  5. 对 Sec-WebSocket-Key 作 Base64 decode，检查长度得是 16 个字节

如果以上的检查通过且可以创建连接，服务端会发出 HTTP Response：

        HTTP/1.1 101 Switching Protocols
        Upgrade: websocket
        Connection: Upgrade
        Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
如何计算 Sec-WebSocket-Accept？

具体实现可见 Handshake.swift。

拼接字符串

首先获取到客户端发来的 Sec-WebSocket-Key（dGhlIHNhbXBsZSBub25jZQ==），拼接上这段协议中定义好的 GUID（全局唯一标识符）：258EAFA5-E914-47DA-95CA-C5AB0DC85B11。

结果为 dGhlIHNhbXBsZSBub25jZQ==258EAFA5-E914-47DA-95CA-C5AB0DC85B11

对拼接后的字符串做 SHA‑1

结果是 20 字节（160 位）的散列值：b3 7a 4f 2c c0 62 4f 16 90 f6 46 06 cf 38 59 45 b2 be c4 ea

把 SHA‑1 结果做 Base64 编码

结果为 s3pPLMBiTxaQ9kYGzzhZRbK+xOo=。客户端收到这个 accept key 后，还会自行校验一遍。如果与自己算出来的不一致，会导致握手失败。

解析数据帧（Data Frame）

具体实现可见 DataFrameParser.swift。

在握手成功后，双端严格以数据帧格式通信，格式如下图：

WebSocket 数据帧中 FIN、RSV、opcode、MASK、长度和载荷字段的位布局

头部结构（2 个字节）

第 1 个字节：FIN（Final，是否是消息最后一个分片）、RSV1/RSV2/RSV3（Reserved，保留位）、opcode（操作码，4 位）。

FIN 为 1 表示这是消息的最后一个分片；0 表示后续还有分片。

RSV1/RSV2/RSV3：除非协商了扩展，否则必须为 0；否则接收方必须关闭连接。

opcode：

  • 0x0 续帧（Continuation）
  • 0x1 文本帧（Text）
  • 0x2 二进制帧（Binary）
  • 0x3–0x7 预留给未来非控制帧
  • 0x8 关闭（Close）
  • 0x9 Ping
  • 0xA Pong
  • 0xB–0xF 预留给未来控制帧

第 2 个字节：MASK（是否掩码）+ Payload len（负载长度，7 比特）。客户端向服务端发送的数据帧必须进行 masking，故 MASK 为 1，服务端向客户端发送的数据帧不进行 masking，故 MASK 为 0。

Payload Data

若 Payload len 为 126：后面跟 2 字节扩展长度（16 位无符号整数）。若 Payload len 为 127：后面跟 8 字节扩展长度（64 位无符号整数，最高位必须为 0）。扩展长度使用网络字节序（network byte order，大端序）。若 MASK 为 1：后面跟 4 字节 Masking-key（掩码键）。最后是 Payload Data（负载数据）：由 Extension data（扩展数据）+ Application data（应用数据）拼接组成。Payload Data 的总长度等于负载长度；其中扩展数据长度由扩展协议定义，未协商扩展时为 0。

特殊的数据帧——控制帧（Control Frame）

  • 定义与类型：操作码（opcode）最高位为 1 的帧即控制帧，已定义的有 0x8 关闭、0x9 Ping、0xA Pong；0xB–0xF 预留给未来控制帧。
  • 不能分片：控制帧必须 FIN = 1，且不得分片；如果接收方收到分片的控制帧，必须按协议失败处理（Fail the WebSocket Connection）。
  • 负载长度限制：控制帧负载长度必须 ≤ 125 字节；超过上限必须按协议失败处理。
  • 可穿插发送：控制帧可以在分片消息的中间插入发送，用于及时传达连接状态；接收方必须能在分片过程中处理控制帧。
  • 掩码规则：客户端发送的所有帧（包括控制帧）都必须带掩码；服务器发送的帧不得掩码。
Close（0x8）
  • 作用：发起关闭握手，告知对端准备关闭连接。
  • 负载结构：可选负载由状态码（2 字节）+ 关闭原因（可选 UTF‑8 文本）组成；若带原因文本，必须是有效 UTF‑8。
  • 行为要求：
    • 一端发送 Close 后，不得再发送数据帧。
    • 一端收到 Close 且自己尚未发送 Close，必须回送 Close 作为响应。
    • 完成双方 Close 交换后，连接关闭。
Ping（0x9）与 Pong（0xA）
  • Ping 可携带应用数据；收到 Ping 必须尽快回送 Pong。
  • Pong 的负载必须与对应 Ping 完全一致（逐字节相同）。
  • Pong 可以主动发送（非响应），作为单向心跳；对主动 Pong 不要求再回 Pong。
实现数据帧解析中产生的思考

复习了位运算，原来位运算发光发热的地方是这里！（例如获取 FIN 位）

复习了大端序和小端序：

  • 大端序（Big Endian）：最高有效字节放在最低内存地址；符合人类的阅读习惯
  • 小端序（Little Endian）：最低有效字节放在最低内存地址

强调「有效」是为了排除前导零或无效位造成的歧义。

当 payloadLength 等于 126 或 127 时，真正的 payloadLength 是要从紧接的 2 个字节或 8 个字节去读。这时候协议规定这段字节序是 network byte order（即大端序）。

在研究如何操作 Data 时，我仔细看了 Data 目前提供的 API，发现有 Span types！WWDC 25 Improve memory usage and performance with Swift 中有对它的介绍！Apple 也推出了 Swift Binary Parsing，后面计划抽空看看，应该能用来优化目前 DataFrameParser.swift 的实现。

分片（Fragmentation）

WebSocket 允许把一个消息拆成多个帧发送，降低内存压力与延迟，支持流式处理。数据帧也可以是不分片的。一个不分片的数据帧，FIN 位总是 1，opcode 肯定不为 0。

规则：

  • 第一个分片帧的 opcode 必须是文本帧（0x1）或二进制帧（0x2），FIN 位为 0。
  • 后续分片帧必须是续帧（0x0）。
  • 最后一个分片帧 FIN 为 1，opcode 仍为续帧（0x0）。
  • 消息边界：接收方用 FIN 判断一条消息结束；所有分片负载拼接成完整消息。
  • 控制帧：控制帧不能分片，但可以插入在分片序列中；接收方必须能在分片过程中处理控制帧。
  • 一致性约束：在一个消息分片未结束前，不能开始新的数据消息分片序列；否则属于协议错误。

关闭连接

正常关闭连接

任一端可发起：发送 Close 控制帧（可带状态码与原因），连接进入 CLOSING；双方都发送并接收 Close 后，应关闭底层传输控制协议（Transmission Control Protocol，TCP）连接，进入 CLOSED 状态。如果完成关闭握手后再关闭 TCP 连接，可称之为「干净关闭」，否则视为「非干净关闭」。

异常断开连接

出现错误即需关闭连接（握手阶段失败、协议错误、传输层连接意外中断等）。服务器在握手阶段可直接「中止连接（Abort）」并关闭 TCP 连接，不必发送 Close 帧。

用 Wireshark 分析

因为 WebSocket 的数据帧直接跑在 TCP 之上，很多只关注 HTTP 的抓包工具无法直接解析，所以我使用 Wireshark 来分析 WebSocketClient-Demo 发送的数据帧。我使用的是 websocat，用它来运行一个本地的 WebSocket 回声（echo）服务器。你给它发「hello」，它也会默认回你「hello」。

// 回声服务器在本地 8080 端口监听
websocat -t ws-listen:127.0.0.1:8080 mirror:

在另一个终端里连接回声服务器：

websocat -t ws://127.0.0.1:8080

建立连接时的握手阶段

Wireshark 抓包显示客户端 GET 升级请求和服务端 101 Switching Protocols 响应

点击 Connect，客户端主动发送 HTTP 升级请求，并收到服务端的同意协议升级响应。

解析数据帧（Data Frame）

建立连接成功后，发送 “hello” 字符串

Wireshark 显示客户端发送带 MASK 的 hello 文本帧

我们可以看到数据帧为：0x81 0x85 0x88 0x56 0xa3 0xf5 0xe0 0x33 0xcf 0x99 0xe7

数据帧头部为两个字节：

  1. 0x81 -> 0b1000_0001；可得 FIN 为 1，后面保留的三位均为 0，最后四位是 opcode，为 1，即代表该数据帧为文本。
  2. 0x85 -> 0b1000_0101；可得 MASK 为 1，因为这是客户端发送的数据，必须 masking。后面七位是 payload length，为 5，等于 “hello” 字符串的长度。

因为 MASK 为 1，所以接下来的四个字节是客户端随机生成的 4 字节 masking key：0x88 0x56 0xa3 0xf5；

因为从头部分析出 payload length 是 5，所以后续 5 个字节就是 masked payload。

客户端 masking：遍历 unmasked payload 中的每个字节，与 masking key 中每个字节（取余 4）作异或操作。

服务端从数据帧中取出 masking key，用其与 masked payload 再做一遍异或操作，就能还原出 unmasked payload。这是利用了异或的可逆性。设任意 bit 为 b，masking key 为 k，那么可得 b XOR k XOR k = b XOR (k XOR k) = b XOR 0 = b。

“hello” 对应的 16 进制的表达为：0x68 0x65 0x6c 0x6c 0x6f，与 masking key（0x88 0x56 0xa3 0xf5）异或后为：0xe0 0x33 0xcf 0x99 0xe7；与 Wireshark 上捕捉的结果相符！

服务端发来的数据帧

Wireshark 显示服务端返回不带 MASK 的 hello 文本帧

因为是回声服务器，所以服务端也是发来 “hello”，没有做 masking，能直接看到 payload 是 “hello”。

客户端主动与服务端断开连接

Wireshark 显示客户端发送带 MASK、状态码 1000 的关闭帧

上图中：客户端发出关闭控制帧，FIN 位为 1，opcode 为 8。

Wireshark 显示服务端返回不带 MASK 和载荷的关闭帧

上图中：客户端收到服务端响应的关闭控制帧。

心得体会

首先得：

  1. 把各个类的类名取好，能把类名取得比较恰当，说明心里已经把它的职责划分好。
  2. 定好各自公开/私有的接口。
  3. 开始使用之前「空实现」的类，把逻辑写对。
  4. 在第三步中，会带来很多思考，会使你退回第二步，重新思考接口的定义。重复几轮下来，大概率能完善接口的设计！
  5. 补上一些单元测试
  6. 补上具体方法的实现

我感觉通过前四步的操作，能对全局的实现以及方向有个更清晰的认识，俗称把握大局观。第一步和第二步只要和 Codex 老师进入 Plan mode 猛聊一小时（实际取决于实现的功能大小）。第三第四步自己开始尝试，遇到新的思路，再回头与 Codex 继续聊。第五第六步已经是来到 Codex 老师的舒适区了，要么是 review 它的代码，要么就是虚心学习它的代码。

Q & A

WebSocket 的出现是为了解决什么问题？

在 WebSocket 出现前，大家想在浏览器里做「服务端能主动推、客户端也能随时发」的双向通信，常见是这些方案：

  1. Long Polling（长轮询）：客户端发起一个超文本传输协议（Hypertext Transfer Protocol，HTTP）请求，服务器在新消息前「挂起」响应；一旦返回，客户端立即发起下一次请求，以此近似持续连接与服务端推送。
  2. 流式传输：服务器保持单个 HTTP 连接很久，持续写入分块数据，客户端边接收边处理，达到持续推送效果。

它们能用，但都有明显缺点：开销大、延迟不稳定、实现复杂。WebSocket 设计出来就是要用一个标准协议把这事正规化：一次升级握手后，真正实现全双工，不再靠「把 HTTP 请求拖得很长」来模拟。

WebSocket 握手为什么要借用 HTTP？

它通过 HTTP/1.1 Upgrade 发起请求，升级成功之后，同一条 TCP 连接上跑的是 WebSocket 帧协议，已经不是 HTTP 报文了。它「借用了 HTTP 这张门票」进入现有网络环境。WebSocket 想把那些「伪装成 HTTP 的双向通信方案」统一替换掉；它通过 HTTP Upgrade 来建立连接，从而继续利用现有的代理、过滤和鉴权等基础设施。

TCP 不是已经有 FIN/ACK 关闭流程了吗？为什么 WebSocket 还要多此一举？

现实网络中的中间设备有很多，TCP 关闭原因/时机，不一定能可靠地表达「对端按应用层语义关了」。

TCP 的 FIN/ACK 只表达「字节流结束」，不表达「消息语义结束」。但 WebSocket 有「消息/帧语义」和「关闭码/原因」。Close 帧可以带：关闭状态码（比如正常关闭、协议错误、消息太大、服务端异常等）和可选原因字符串。

参考

WebSocketClient-Demo 中仅实现了：

  1. 握手过程
  2. 仅支持解析/构造控制帧和 text 数据帧

所以，还是很有必要去看看其他 WebSocket 客户端/服务端的实现，我搜集了如下几个：

Starscream 源码分析

看来看去还是 Starscream 的星星数比较多多，同时也是 Socket.IO iOS 客户端的依赖之一，所有首先来看看它的架构图：

Starscream 从 API、Engine 到 Compression、Security、Transport 和 Framer 的分层架构图

设计特点

  1. 面向协议设计（POP）：每一层都通过协议（Engine, Transport, Framer, CertificatePinning, CompressionHandler）定义接口，实现可替换。

  2. 双引擎策略：WSEngine 提供完整的自定义 RFC 6455 实现；NativeEngine 封装系统的 URLSessionWebSocketTask。在 WebSocket.init 中根据系统版本和 useCustomEngine 参数自动选择。

  3. WSEngine 是组合中心：它实现了 TransportEventClient、FramerEventClient、FrameCollectorDelegate、HTTPHandlerDelegate 四个回调协议，将 Transport → HTTP 握手 → 帧解析 → 分片重组 → 压缩/解压 的完整流程串联起来。

  4. 传输层适配：TCPTransport（基于 Network.framework）用于 iOS 12+；FoundationTransport（基于 Stream）兼容更早的系统。

Starscream.WebSocket 的初始化过程

    public convenience init(
        request: URLRequest,
        certPinner: CertificatePinning? = FoundationSecurity(),
        compressionHandler: CompressionHandler? = nil,
        useCustomEngine: Bool = true
    ) {
        if #available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *), !useCustomEngine {
            self.init(request: request, engine: ())
        } else if #available(macOS 10.14, iOS 12.0, watchOS 5.0, tvOS 12.0, *) {
            self.init(request: request, engine: WSEngine(transport: TCPTransport(), certPinner: certPinner, compressionHandler: compressionHandler))
        } else {
            self.init(request: request, engine: WSEngine(transport: FoundationTransport(), certPinner: certPinner, compressionHandler: compressionHandler))
        }
    }

当最低支持 iOS 13 时，Starscream.WebSocket 背后的核心实现依赖于 NativeEngine，而 NativeEngine 则是构建于 URLSessionWebSocketTask 之上。现在大部分的 iOS app 早就最低支持 iOS 13 了吧，我怀疑可能就是这个原因让这个项目基本上不活跃了，最近的一次 release 已经是 2024 年三月份的了！

本着学习协议的目标，我们可以阅读 WSEngine 的代码。

握手阶段

代码

  1. 创建一个 HTTP Upgrade 的 URLRequest
  2. 利用 CFHTTPMessageCopySerializedMessage 方法把 URLRequest 转为 Data （代码）
  3. 使用 NWConnection 的 TCP 连接发送该 Data （代码）
  4. 等待 NWConnection 收齐服务端发来的 HTTP Response 头时，检验其是否合法 （代码）
  5. 若合法，在 didReceiveHTTP 回调中更新标志位 isConnecting = false, didUpgrade = true, canSend = true。使用 Value 为 1 的 DispatchSemaphore 来保护这些共享状态，以防出现数据竞争。

对比我写的 demo 里，是 手动构造一个多行 String 来实现 HTTP 请求头，而 Starscream 的做法在工程角度上说更好，先创建的是 URLRequest 对象，再用 CFNetwork 中的方法把它序列化为 Data，交给 TCP 传输层发送。

接受数据

代码

  1. TCPTransport 把 TCP 连接中的字节流组装为 Data，喂给 WSFramer
  2. WSFramer 把 Data 解析为 WebSocket 帧数据（是续帧，还是文本帧，还是二进制帧，还是控制帧）
  3. WSFrame 把解析出来的帧数据喂给 FrameCollector
  4. FrameCollector 把续帧拼接起来，组装为完整的“消息”（.text(String) / .binary(Data)）

代理链条

┌──────────────┐    TransportEventClient     ┌──────────┐
│ TCPTransport │ ──────────────────────────▶  │ WSEngine  │
└──────────────┘  "TCP 有数据来了/连上了"       └────┬─────┘
                                                   │
                    ┌──────────────────────────────┤
                    │ WSEngine 把数据分发给          │
                    │ 两个下游模块                   │
                    ▼                              ▼
          ┌─────────────────────┐        ┌──────────────┐
          │ FoundationHTTPHandler│        │   WSFramer    │
          └────────┬────────────┘        └──────┬───────┘
                   │ HTTPHandlerDelegate         │ FramerEventClient
                   │ "HTTP 握手成功了"             │ "解析出一个帧了"
                   ▼                              ▼
             ┌──────────┐                  ┌──────────┐
             │ WSEngine  │                 │ WSEngine  │
             └──────────┘                  └────┬─────┘
                                                │
                                                │ WSEngine 把帧交给
                                                ▼
                                       ┌────────────────┐
                                       │ FrameCollector  │
                                       └───────┬────────┘
                                               │ FrameCollectorDelegate
                                               │ "完整消息拼好了"
                                               ▼
                                         ┌──────────┐
                                         │ WSEngine  │
                                         └────┬─────┘
                                               │ EngineDelegate
                                               │ "这是最终事件"
                                               ▼
                                         ┌──────────┐
                                         │ WebSocket │
                                         └────┬─────┘
                                               │
                                               ▼
                                       用户 delegate / onEvent

WSEngine 在图中反复出现——它同时是 4 个模块的 delegate：

谁通知 WSEngine 通过什么协议 WSEngine 的回调方法
TCPTransport TransportEventClient connectionChanged(state:)
FoundationHTTPHandler HTTPHandlerDelegate didReceiveHTTP(event:)
WSFramer FramerEventClient frameProcessed(event:)
FrameCollector FrameCollectorDelegate didForm(event:)

WSEngine 作为”中枢调度器”：所有事件都汇聚到 WSEngine，由它决定下一步交给谁处理，最终通过 EngineDelegate 把结果传给 WebSocket。

]]>Sunset WanSwiftUI View 的 Identity 与 Lifetime2025-12-01T23:33:33+08:002025-12-01T23:33:33+08:00https://sunsetwan.github.io/2025/12/01/SwiftUI_Identity_lifetime前阵子遇到一个很奇怪的 BUG：用 NavigationStack push 一个 View，CPU 使用率竟然冲上 100%！当 Xcode 运行一段 SwiftUI 代码时，我们应该关注哪些方面？特此回顾 WWDC 21 Demystify SwiftUI。

当 Xcode 运行一段 SwiftUI 代码时，我们应该关注哪些方面？

  1. Identity — 是 SwiftUI 用来区分视图元素的「身份证」
  2. Lifetime — 是 SwiftUI 用来管理视图与其相关状态的生命周期
  3. Dependency — 是 SwiftUI 用来决定视图为何以及何时需要更新

Identity

SwiftUI 中 Identity 分为两种：Explicit Identity 和 Structural Identity。

外表相似的双胞胎并肩站在走廊中

当遇到两个外表很相似的双胞胎，我们该如何区分？对，可以通过姓名来区分！这就是 Explicit Identity。

我查了点资料，我们仅知道这对著名的双胞胎姐妹是格雷迪双胞胎姐妹，并不知道各自的姓名。那我问你：你觉得哪个更恐怖一点？我是觉得左边那位更恐怖一些。
通过她俩的相对位置来区分：一位是站在左边，另一位是站在右边。这就是 Structural Identity。

接下来，我们来看一个更实际的例子：

SwiftUI 条件分支映射为 ConditionalContent 的 True 和 False 两种结构身份

左边的代码在 SwiftUI 「眼里」当条件为真时显示 AdoptionDirectory 视图，条件为假时显示 DogList 视图。只要条件恒定，SwiftUI 能知道哪个是「真分支」哪个是「假分支」。

View body 中的 if 语句在 SwiftUI 里会被编译成 _ConditionalContent<TrueView, FalseView> 这样的泛型类型，TrueView 和 FalseView 是两个分支的具体类型。这个转换由 ViewBuilder 完成。
View 协议的 body 会隐式包裹在 ViewBuilder 中，ViewBuilder 会把 body 里的条件逻辑拼成一个统一的泛型视图类型。

Structural Identity 是 Swift 通过视图元素在视图层级中的类型与位置来识别视图身份的方法。

PawView 示例

在这个 代码示例 里，我们可以通过点击事件来更新 dog.isGood 状态，从而触发 pawView 的刷新。

    @ViewBuilder
    var pawView: some View {
        if dog.isGood {
            PawView(tint: .green)
                .padding(.top, 32)
            Spacer()
                .padding(.bottom, 32)
        } else {
            Spacer()
            PawView(tint: .red)
                .padding(.bottom, 32)
        }
    }

条件分支切换时，绿色爪印消失后红色爪印重新出现的动画

问题一：为什么是绿色爪印消失后再出现红色爪印呢？

因为 SwiftUI 是通过 Structural Identity 来区分绿色爪印和红色爪印，当 dog.isGood 变化时，SwiftUI 认为它需要销毁绿色爪印视图和创建红色爪印视图。

不难得出：视图的 Identity 发生变化后，SwiftUI 会认为它需要销毁旧视图并创建新视图。

问题二：单个爪印直接从绿色过渡到红色应该会更丝滑，我要怎么做？

    var pawView: some View {
        PawView(tint: dog.isGood ? .green : .red)
            .padding(.top, 32)
            .padding(.bottom, 32)
            .frame(maxHeight: .infinity, alignment: dog.isGood ? .top : .bottom)
    }

我们可以把 pawView 里的 if 分支拿掉，单个 PawView 的 Structural Identity 就保持不变；dog.isGood 变化时，只是同一个视图的 tintColor 和位置在变，状态与动画都能连续。

保持同一 PawView 身份后，爪印颜色和位置连续过渡的动画

Lifetime

我们给 PawView 加上 PawViewState 状态，来看看 Structural Identity 的变化对视图状态的影响

class PawViewState {
    let id: UUID

    init(id: UUID = UUID()) {
        self.id = id
        print("PawViewState(\(id)) init at \(Date())")
    }

    deinit {
        print("PawViewState(\(id)) deinit at \(Date())")
    }
}

struct PawView: View {
    let tint: Color
    @State private var state: PawViewState = .init()

    var body: some View {
        Circle()
            .fill(tint)
            .frame(width: 180, height: 180)
            .overlay(
                Image(systemName: "pawprint.fill")
                    .resizable()
                    .scaledToFit()
                    .foregroundColor(.white)
                    .padding(44)
            )
    }
}

在我触发两次点击事件（Good dog → Bad dog, Bad dog → Good dog）后，Xcode console 输出如下：

PawViewState(39BFC159-AE06-45A5-9083-B1C5BDF053C3 init at 2025-11-30 05:42:02 +0000 // Good dog 1 init
PawViewState(5FB6A6D4-1E81-43A1-8AB1-04C2DEE8455A init at 2025-11-30 05:42:05 +0000 // Bad dog 1 init
PawViewState(39BFC159-AE06-45A5-9083-B1C5BDF053C3 deinit at 2025-11-30 05:42:06 +0000 // Good dog 1 deinit
PawViewState(33E05E98-2553-4C8D-81B0-A56E2E353962 init at 2025-11-30 05:42:07 +0000 // Good dog 2 init
PawViewState(5FB6A6D4-1E81-43A1-8AB1-04C2DEE8455A deinit at 2025-11-30 05:42:08 +0000 // Bad dog 1 deinit

从上面的例子中总结：

  1. 视图的 Identity 发生变化后，SwiftUI 会认为它需要销毁旧视图并创建新视图。也就是说，视图的生命周期是否延续取决于 Identity 是否保持不变。
  2. SwiftUI 里状态的生命周期和视图的生命周期是绑定在一起的。也就是说，一个视图被创建时状态才会被创建，视图被销毁时状态就随之消失。

因此，可得：

SwiftUI 把视图的「本质」归结为它持有的状态，并把这份状态和视图的身份绑定在一起。
身份不变，状态就被保留下来；身份一变，SwiftUI 就当成全新的视图，状态也重建。这样能清晰地区分：哪些状态应该延续（身份稳定的视图），哪些状态应该重置（身份变化的视图）。

FavoritePetsView 示例

再看这个 例子，来辅助理解上面的总结。

Favorite Pets 列表显示五只宠物及右上角 Add 按钮

struct Pet: Identifiable {
    var name: String
    var kind: Animal
    var id: UUID { // 不稳定的 identity
        UUID()
    }
}

struct FavoritePetsView: View {
    @State private var pets: [Pet]

    init(pets: [Pet]) {
        self.pets = pets
    }

    var body: some View {
        NavigationStack {
            List {
                ForEach(pets) { pet in
                    PetRow(pet: pet)
                }
            }
            .listStyle(.plain)
            .navigationTitle("Favorite Pets")
            .toolbar {
                ToolbarItem(placement: .topBarTrailing) {
                    Button("Add") {
                        addTomCat()
                    }
                }
            }
        }
    }

    func addTomCat() {
        let newPet = Pet(name: "汤姆", kind: .cat)
        pets.insert(newPet, at: 0)
    }
}

当点击 Add 按钮时，「汤姆猫」出现在 List 的首位。让我们用 SwiftUI Instruments 来查看当前视图的更新次数。

SwiftUI Instruments 显示身份不稳定时 PetRow body 执行 29 次

因为 PetRow Identity 的不稳定性，导致 PetRow 的 body 被执行多次。如果放在一个大型项目中，可能会导致 App 出现卡顿。

使用计算属性生成 UUID 的方式遵循 Identifiable 会导致视图 Identity 不稳定，所以作如下修改，以提供稳定的 Identity。

struct Pet: Identifiable {
    var name: String
    var kind: Animal
    let id = UUID()
}

可以再次运行 SwiftUI Instruments 来查看当前视图的更新次数：

使用稳定 id 后 SwiftUI Instruments 显示 PetRow body 仅创建 6 次

PetRow 的 body 被执行的次数锐减至 6 次！原本已有 5 个宠物，再加上新增的「汤姆猫」，总计 6 次，与预期相符。

TreatJar 示例

再看这个稍微复杂一点的 例子。Treat Jar View 展示的是给宠物准备的零食。如果有零食过期，那就置灰。

Treat Jar 页面中已过期零食变灰，未过期零食保持高亮

我们借助于 ExpirationModifier 来实现置灰的效果。

    var body: some View {
        NavigationStack {
            ScrollView {
                LazyVGrid(columns: columns, spacing: 16) {
                    ForEach(treats, id: \.serialNumber) { treat in
                        TreatCell(treat: treat)
                            .modifier(ExpirationModifier(date: treat.expiryDate, referenceDate: referenceDate))
                    }
                }
                .padding(16)
            }
            .background(Color(.systemGroupedBackground))
            .navigationTitle("Treat Jar")
            .toolbar {
                ToolbarItem(placement: .topBarLeading) {
                    Button(referenceDateIsExpired ? "Restore" : "Expire") {
                        toggleExpirationSimulation()
                    }
                }
            }
        }
    }

struct ExpirationModifier: ViewModifier {
    var date: Date
    var referenceDate: Date = .now

    func body(content: Content) -> some View {
        if date < referenceDate {
            content.opacity(0.3)
        } else {
            content
        }
    }
}

此时执行点击左上角 Expire 按钮来模拟所有的零食过期。SwiftUI Instruments 给出的视图更新次数如下：

条件分支切换过期状态后，SwiftUI Instruments 显示 TreatCell body 创建 2 次

代表两种零食的 TreatCell 创建了两次，但实际上零食过期后，只需置灰即可，不需要重新创建 TreatCell。

struct ExpirationModifier: ViewModifier {
    var date: Date
    var referenceDate: Date = .now

    func body(content: Content) -> some View {
        if date < referenceDate { // Structural Identity
            content.opacity(0.3)
        } else {
            content
        }
    }
}

使用了 ExpirationModifier 之后，ForEach 中的 Content View 的 Identity 属于 Structural Identity。

// ForEach 中的 Content View
TreatCell(treat: treat)
 .modifier(ExpirationModifier(date: treat.expiryDate, referenceDate: referenceDate))

根据之前的经验，我们可以通过这种方式来优化，即去除 if 分支：

struct ExpirationModifier: ViewModifier {
    var date: Date
    var referenceDate: Date = .now

    func body(content: Content) -> some View {
        content.opacity(date < referenceDate ? 0.3 : 1)
    }
}

运行 SwiftUI Instruments，再次点击左上角 Expire 按钮，可以看到：

移除条件分支后，Instruments 只记录 ExpirationModifier body 的 7 次更新

TreatCell.body 没有再被执行过了！所以在 View 中使用 if 分支时，可以停下来问自己：我是要多个视图还是某一视图的两种状态呢？引入不必要的分支，可能会导致性能下降，甚至视图的状态丢失。

Dependency

DogView 代码中依赖、body 和 action 的对应区域

（本节不是本文讨论的重点，于是我放上 AI 对此的总结）

  • 依赖的含义：视图的输入（属性、@State/@Binding/@Environment/ObservableObject 等）。依赖一旦变更，对应视图就必须重新计算 body。
  • 依赖关系的结构：虽然视图层级像树，但同一个依赖可被多处使用，整体更像一张依赖图。某个依赖变化时，SwiftUI 只让依赖它的视图重建，而不是全量刷新。
  • 身份在其中的作用：视图的身份（显式 id 或结构身份）决定依赖变化如何被路由到具体节点；身份稳定，就能更好地保持状态和避免多余重建。
  • 选择稳定且唯一的标识：数据驱动的视图（ForEach 等）需要稳定、唯一的 id。随机 id 或数组下标会让身份漂移，造成闪烁、错误动画或状态丢失。
  • 精简条件分支：多余的 if/switch 会制造额外的身份节点，导致重复重建。能用「惰性」修饰符（如条件放进 opacity，1 时无影响）折叠条件时，更新会更集中高效。
  • 更新流程心智模型：依赖变化 → 标记相关视图 → 重新求 body 生成新值；值本身是短暂对比用的，持久状态与视图身份绑定并随身份存续。

回顾

还记得文章开头我提及的奇怪 BUG 吗？这是能复现的 demo，而且在 iOS 17.1.2 上能稳定复现。

typealias DetailState = DetailViewModel.State

final class DetailViewModel: ObservableObject {
    struct State: Identifiable {
        let title: String
        let subtitle: String
        var text: String = "123"
//
        var id: UUID {
            let newID = UUID()
            print("🆔🆔🆔 [DetailState] id accessed, generated: \(newID)")
            return newID
        }

        // Solution: Use stable explicit identity
//        let id = UUID()
    }

    @Published var state: State

    // MARK: - Textfield logic

    init(state: State) {
        self.state = state
    }
}

核心就在于通过 Navigator push Detail 页面时，DetailState 的 explicit identity 不稳定。每次求值 body 都会重新访问 State.id，计算属性每次生成新的 UUID，导致 Identifiable 身份变化。SwiftUI 认为当前 NavigationStack 顶端元素变了，于是销毁旧的 Detail 页面并创建新的 Detail 页面。

Button("Show Detail") {
    let state: DetailState = .init(title: "Detail Title", subtitle: "Detail subtitle")
    navigator.push(to: .detail(state))
}

运行 SwiftUI Instruments 来看看视图的变化次数：

SwiftUI Instruments 显示 DetailView 更新约 4900 次并出现严重卡顿

从上图可以看出：在短短几秒之内，DetailView 更新了将近 5000 次，SwiftUI 内部的 NavigationStack 更新了将近一万五千次，整个 App 出现了严重的卡顿！

]]>Sunset WanProtocol Witness in Swift2024-06-23T21:23:49+08:002024-06-23T21:23:49+08:00https://sunsetwan.github.io/2024/06/23/Swift-Protocol-Witness在 Swift 中，协议是非常重要的部分之一。使用协议，可以让我们写出灵活的代码，而不必拘泥于接口和实现的耦合，但协议也有自己的问题。

问题 1

protocol A {}

protocol B {}

extension B: A {} // 🛑 Extension of protocol 'B' cannot have an inheritance clause

我们无法在协议 B 的扩展中继承协议 A。

protocol A {}

protocol B: A {} // 🟢

只有在协议 B 声明时，才能建立继承关系。当协议 B 非我们自己声明时，那就无计可施了。

问题 2

遵循协议的类型只能以一种方式来实现协议的要求。

indirect enum Tree<A> {
    case empty
    case node(left: Tree<A>, value: A, right: Tree<A>)
}

// ⚠️ Types are only allowed to conform to a protocol in one single way.
extension Tree: Sequence {
    // in-order?
    // pre-order?
    // post-order?
}

我们利用 Swift 中的 enum 来定义树的结构，并期望 Tree 遵循 Sequence 协议。那么遍历 Tree 时，用哪种方式去遍历是固定的，是根据 IteratorProtocol 协议的实现来定的。

问题 3

有些类型无法遵循协议，如 Tuple。

let tuple1 = (1, 1)
let tuple2 = (2, 2)

@discardableResult
func isEqual<T: Equatable>(lhs: T, rhs: T) -> Bool {
    lhs == rhs
}

isEqual(lhs: tuple1, rhs: tuple2) // 🛑 Type '(Int, Int)' cannot conform to 'Equatable'

Protocol Witnesses （协议目击者）

Protocol witnesses are generated by the Swift compiler, when a protocol is used in a generic context, the compiler generates a separate implementation for each concrete type that conforms to the protocols. These implementations called protocol witnesses, are optimized for the specific type.

简而言之，Protocol Witnesses 是 Swift 编译器生成的一种数据结构，这种数据结构里包含了遵循某个协议的实现细节。也就是说，如果 Swift 中没有设计协议，我们也能利用这种数据结构实现协议的特性。

protocol Combinable {
    func combine(_ other: Self) -> Self
}

extension Int: Combinable {
    func combine(_ other: Int) -> Int {
        self + other
    }
}

Combinable 是个很简单的协议，我们让 Int 遵循 Combinable 协议，并用整型数的加法来满足协议要求。

如果 Double 和 Float 类型也想变成 Combinable 呢？

😐 嗯，继续添加对应的实现呗！

extension Double: Combinable {
    func combine(_ other: Double) -> Double {
        self + other
    }
}

extension Float: Combinable {
    func combine(_ other: Float) -> Float {
        self + other
    }
}

似乎闻到了坏代码的味道！😷

我们转头一想，Int，Double，Float 都是遵循 Numeric 协议的，那么直接让 Numeric 协议继承自 Combinable，似乎问题就解决了！

// 🛑 Extension of protocol 'Numeric' cannot have an inheritance clause
extension Numeric: Combinable {

}

😇 还是不行！🙅

解决问题 1

让我们写出 Combinable 协议对应的 Witness 来解决这个问题。Combining<A> 是Combinable 协议的 Witness。

struct Combining<A> {
    let combine: (A, A) -> A
}

再写出加法的实现：

extension Combining where A: Numeric {
    static var sum: Combining {
        Combining { $0 + $1 }
    }
}

最后，

Combining<Int>.sum.combine(1, 2) // Output: Int 3

Combining<Double>.sum.combine(1.0, 2.0) // Output: Double 3.0

解决问题 2

Int 变成 Combinable，不应该只有加法这一种实现方式，也可以是两个 Int 做乘法。

extension Combining where A: Numeric {
    static var sum: Combining {
        Combining { $0 + $1 }
    }

    static var prod: Combining {
        Combining { $0 * $1 }
    }
}

让我们看一个复杂点的例子：

extension Array where Element: Combinable {
    func reduce(_ initial: Element) -> Element {
        self.reduce(initial) {
            $0.combine($1)
        }
    }
}

// 转为使用 Combining<A>
extension Array {
    func reduce(_ initial: Element, _ combining: Combining<Element>) -> Element {
        return reduce(initial, combining.combine)
    }
}

[1, 3, 5].reduce(0, .sum) // Output: 9
[CGFloat(2), 3, 5].reduce(1, .prod) // Output: 30

我们只需传入不同实现的 Witness 即可实现同一协议方法的不同实现。

解决问题 3

let tuple1 = (1, 1)
let tuple2 = (2, 2)

@discardableResult
func isEqual<T: Equatable>(lhs: T, rhs: T) -> Bool {
    lhs == rhs
}

isEqual(lhs: tuple1, rhs: tuple2) // 🛑 Type '(Int, Int)' cannot conform to 'Equatable'

以 Array 为例，如果 Element 是 Equatable 的，那么整个 Array 也是 Equatable 的。那么同理 (1, 1) 这个 tuple 也应该是 Equatable 或者 Combinable 的，因为整型数 1 是 Equatable 的，也是 Combinable 的！

如果目标是证明： (A, B) 是 Combinable 的，那么我们需要拿出 Combining<(A, B)> 这个 witness 才能证明！但我们现在只有 Combining<A> 和 Combining<B>，能以此为基础推导出 Combining<(A, B)> 吗？

答案是可以：

func zip<A, B>(_ a: Combining<A>, _ b: Combining<B>) -> Combining<(A, B)> {
    Combining { lhs, rhs in
        (a.combine(lhs.0, rhs.0), b.combine(lhs.1, rhs.1))
    }
}

[
    (1, 1.1),
    (2, 2),
    (3, 3),
].reduce((1, 0), zip(.prod, .sum)) // Output: (6, 6.1)

收获

前面的内容讲了不少 Protocol Witness 的内容，但既然 Swift 编译器已经把这些细节隐藏起来了，那我们知道这些有什么用呢？请看下面一个例子：

protocol 动物 {
    func 走路()
}

extension 动物 {
    func 走路() {
        print("我用 4 条腿走路")
    }

    func 奔跑() {
        print("我用 4 条腿奔跑")
    }

    func 跑跑跳跳() {
        走路()
        奔跑()
    }
}

struct 蜘蛛: 动物 {
    func 走路() {
        print("我用 8 条腿走路")
    }

    func 奔跑() {
        print("我用 8 条腿奔跑")
    }
}

let 小蜘蛛 = 蜘蛛()
小蜘蛛.跑跑跳跳()
// Output:
// 我用 8 条腿走路
// 我用 4 条腿奔跑

我们可以用 Protocol Witness 的知识来说明这个输出的原因。在 Swift 协议中，只有被要求的函数才会进行动态派发，即只有在 Protocol Witness 中的方法才会进行动态派发。

所以，我们可以想象小蜘蛛的 走路 和 奔跑 方法中都有一个隐藏的参数（动物 的 witness）。

在小蜘蛛的 走路 方法执行时，发现 witness 中有 走路 方法的实现，即执行动态派发的方法 走路（输出：”我用 8 条腿走路”）。

在小蜘蛛的 奔跑 方法执行时，发现 witness 中并没有 奔跑 方法的实现，即执行协议扩展中静态派发的方法 奔跑（输出：”我用 4 条腿奔跑”）

很明显，蜘蛛不光用 8 条腿走路，它们还可能是用 8 条腿奔跑的。

那么我们只需把 奔跑 方法加入 动物 协议的 witness 中，即把 奔跑 方法加入 动物 协议中，使其成为协议约束的一部分！这样就可以让这只小蜘蛛也用上 8 条腿奔跑了！

protocol 动物 {
    func 走路()
    func 奔跑()
}

...
...

let 小蜘蛛 = 蜘蛛()
小蜘蛛.跑跑跳跳()
// Output:
// 我用 8 条腿走路
// 我用 8 条腿奔跑

WWDC 24 中也提到了 Protocol Witness

于 Explore Swift performance 视频 [31: 04] 处：
DataModel 协议要求与 DataModelWitnessTable 中函数指针的对照

左边为 DataModel 协议，右边为 DataModel 协议的 Witness。

在每个协议要求的方法中，均有一个额外的隐藏参数——指向 witness 的指针。

]]>Sunset WanAlamofire 源码阅读（一）2024-06-15T00:01:13+08:002024-06-15T00:01:13+08:00https://sunsetwan.github.io/2024/06/15/Alamofire-%E6%BA%90%E7%A0%81%E9%98%85%E8%AF%BB%E7%AC%94%E8%AE%B0阅读 Alamofire 5.9.1 版本的源代码，有些收获，记录于此。

创建 URLSession

AF 在初始化 URLSession 时，使用到三个队列，分别是：rootQueue、requestQueue 和 serializationQueue。rootQueue 默认为 DispatchQueue(label: “org.alamofire.session.rootQueue”)。

而 requestQueue 和 serializationQueue 默认均是以 rootQueue 为 target 的串行队列。也就是说，提交到 requestQueue 上的 task A 是会在 rootQueue 上执行的。

假设 iOS 会给 rootQueue 分配一个线程 T1，那么提交到 requestQueue 和 rootQueue 上的任务均会在线程 T1 上执行。

如果 requestQueue 自己是个单独的串行队列呢？iOS 会专门给 requestQueue 分配另一个线程 T2，这样 App 就可能使用了不必要的线程资源。

Alamofire 的 requestQueue 和 serializationQueue 都以 rootQueue 为目标队列，共用其执行线程

当存在过多线程时，不仅会增加内存压力，更重要的是，这些线程在有限的 CPU 核心上运行，导致频繁的线程上下文切换。有时候，与实际执行需要的指令相比，这些上下文切换所消耗的资源和时间反而占据了主要部分。这种情况下，由于线程被阻塞的同时，又不断有新的任务以 async 的方式提交到并行队列，导致过多的新线程被创建，我们将其称为线程爆炸。

Apple 也在 DispatchQueue 文档 中提示我们避免创建过多线程，限制线程数量可以避免资源的过度占用和性能下降。

AF 创建 Request 的流程

Alamofire 从 Session 发起请求并创建 DataRequest 的调用流程

AF 处理 Response 的流程

Alamofire 接收 URLSession 回调并序列化 Response 的处理流程

AF 中是如何解决数据竞争的？

AF 中是利用泛型类 Protected<Value> 来实现线程安全的读和写。

泛型类 Protected<Value> 的核心思路是利用锁的机制来实现线程同步。除此以外，还利用到@dynamicMemberLookup 和 KeyPath 的特性，以方便地访问/修改 Value 的成员变量（属性）。

我也借鉴它的思路，解决了工作中的一个数据竞争导致的崩溃（EXC_BAD_ACCESS KERN_INVALID_ADDRESS）。在读取硬件设备的数据时，业务层会以并发的方式发送蓝牙指令，而蓝牙发送工具类中使用一个结构体 FIFO 队列来控制蓝牙指令的执行顺序。

public protocol Queue {
    associatedtype Element
    mutating func enqueue(_ element: Element)
    mutating func dequeue() -> Element?
}

public struct FIFOQueue<Element>: Queue {
    ...
    ...
}

该结构体 FIFO 队列的入队出队方法均是 mutating 方法，结构体的 mutating 方法本质上是把当前的值拷贝一份，作出修改后，重新赋值给 self。

假设要发出的两个蓝牙指令分别在不同的线程中发送，那么这两个线程就有可能同时执行 FIFO 队列的入队方法，即出现数据竞争的情况。

在定位到这个崩溃的根本原因后，利用泛型类 Protected<Value> 就能很方便地解决问题。

extension FIFOQueue {
    /// Return a thread-safe reference of a `FIFOQueue`.
    public static func makeThreadSafeReference(_ elements: [Element] = []) -> Protected<Self> {
        Protected(Self.init(elements))
    }
}

extension Protected: Queue where Value: Queue {
    public typealias Element = Value.Element

    public func enqueue(_ element: Value.Element) {
        write { queue in queue.enqueue(element) }
    }

    public func dequeue() -> Value.Element? {
        write { queue in queue.dequeue() }
    }
}

在添加上述代码之后，只需改动蓝牙发送工具类中初始化 FIFO 队列 一行代码。

// Before
var queue = FIFOQueue<Value>()

// After
var queue = FIFOQueue<Value>.makeThreadSafeReference()

这一刻，我觉得 Swift 是真的优雅！

SSL Pinning

AF 也内置了常见的 SSL pinning 方式，比如通过固定证书的方式和使用公钥的方式等。

For projects deploying to iOS 14, tvOS 14, watchOS 7, or macOS 11 or later, Apple now provides built in pinning capabilities configurable in your app’s Info.plist. Please use that capability before implementing your own using Alamofire.

但如果 iOS 项目是最低支持 iOS 14 的，AF 优先推荐使用 iOS 系统内置的方案来实现 SSL Pinning。

什么是 Pinning？

把主机名（Host）与预设好的 X509 证书或者公钥关联起来的过程叫做 pinning。iOS App 中可内置关联好的证书或公钥来防止中间人攻击（Man-in-the-middle attack）。

什么是中间人攻击（Man-in-the-middle attack）

在使用非对称加密中，Alice 若想与 Bob 进行安全的通信，Alice 需要拿到 Bob 的公钥，然后 Alice 使用 Bob 的公钥加密通信内容。而加密后的内容只能以 Bob 的私钥解密，这似乎听起来很安全。那么设想这样一个场景：

  1. Alice 向 Bob 发送：嗨！Bob 请给我你的公钥。
  2. Jack 窃取到了这条信息，且转发给了 Bob。
  3. Bob 把自己的公钥发送给 Alice。
  4. Jack 收到了 Bob 的公钥，但却把他自己的公钥发给 Alice。
  5. Alice 认为自己收到了 Bob 的公钥，其实是 Jack 的公钥。
  6. Alice 向 Bob 发送：今晚 7 点去吃麦当劳吧，并用（她认为的） Bob 的公钥加密。
  7. Jack 收到 Alice 用自己的公钥加密的信息后，用自己的私钥解密，并把信息篡改为“今晚 6 点去吃食其家吧”，再用 Bob 的公钥加密，发给 Bob。
  8. Bob 收到信息，用自己的私钥解密后，就去准备晚上 6 点和 Alice 在食其家碰头了。

在上述场景中，Alice 需要一种方式来确保自己收到的公钥是 Bob 的公钥，而不是攻击者 Jack 的公钥。Bob 可以向权威机构申请一个证书，这个证书会包含 Bob 的公钥，由权威机构来给 Bob 的公钥作背书。

所以 iOS app 中常见的防止中间人攻击的方法之一就是预先把与公司主机名关联好的公钥内置在 app 中。在建立 HTTPS 安全连接时，读取证书链中的叶子节点证书，先通过证书的签名和所使用的加密算法来验证证书的完整性。完整性验证通过后，再对比公钥是否一致。

Cache

AF 使用 URLSession 的系统实现来缓存网络请求的响应的，即默认存入 URLCache.shared 中。

URLSession 的缓存策略（requestCachePolicy）有 6 种：

  1. useProtocolCachePolicy
    1. 解释：遵循 HTTP 中的缓存机制，详见 Caching in HTTP。
  2. reloadIgnoringLocalCacheData
    1. 解释：不使用任何缓存数据。
  3. reloadIgnoringLocalAndRemoteCacheData
  4. returnCacheDataElseLoad
    1. 解释：优先使用缓存数据，若没有缓存数据，则开始网络请求。
  5. returnCacheDataDontLoad
    1. 解释：使用缓存数据，若没有缓存数据，则直接网络请求失败，这种行为有点像离线模式。
  6. reloadRevalidatingCacheData

我们还可以通过实现这个代理方法，来实现更细节的控制，比如阻止对某个特定 URL 的响应进行缓存。

    open func urlSession(_ session: URLSession,
                         dataTask: URLSessionDataTask,
                         willCacheResponse proposedResponse: CachedURLResponse,
                         completionHandler: @escaping (CachedURLResponse?) -> Void) {
    // Add your implementation
    }

但需要注意的是，这个代理方法被调用的条件有些苛刻，得同时满足以下 7 个条件才行！

URLSession 调用 willCacheResponse 代理方法所需满足的七个条件

]]>Sunset WanCodable 学习笔记2022-04-14T09:41:00+08:002022-04-14T09:41:00+08:00https://sunsetwan.github.io/2022/04/14/Codable本文为 Raywenderlich 出版的《Expert Swift》第 8 章节《Codable》阅读笔记。

Swift 4.0 就引入了 Codable 协议。话不多说，进入正题：
示例 JSON：

{
  "accessKey" : "S|_|p3rs3cr37",
  "AddressInfo" : {
    "atmCode" : "1132",
    "city" : "Albuquerque",
    "street" : "3828 Piermont Drive",
    "zip" : 87112
  },
  "ContactInfo" : {
    "addedOn" : "04-14-2022 13:58",
    "cellularPhone" : "+972 542-288-482",
    "email" : "freak4pc@gmail.com",
    "homePhone" : "+1 212-741-4695",
    "website" : "http://github.com/freak4pc"
  },
  "family" : [
    "Tom",
    "Elia"
  ],
  "name" : "Shai Mishali"
}

如何 Decode？

即如何解析这段 JSON？

维持原有层级结构

这个 JSON 对应的 Swift 模型为：

import Foundation

struct Customer1: Codable {
    let accessKey: String
    let addressInfo: AddressInfo
    let contactInfo: ContactInfo
    let family: [String]
    let name: String

    enum CodingKeys: String, CodingKey {
        case accessKey
        case addressInfo
        case contactInfo
        case family, name
    }
}

// MARK: - AddressInfo
struct AddressInfo: Codable {
    let atmCode, city, street: String
    let zip: Int
}

// MARK: - ContactInfo
struct ContactInfo: Codable {
    let addedOn, cellularPhone, email, homePhone: String
    let website: String
}

Customer1 结构体模型的层级结构与 JSON 对象的层级结构保持一致。这样就可以利用 JSONDecoder 把示例 JSON 成功地解析为 Customer1 结构体模型。

自定义 JSON 对应模型的层级结构

以上述 Customer1 模型为例，如果想访问该顾客所在的城市：

let jack = Customer1()
let city = jack.addressInfo.city

如果想直接通过 jack.city 来访问 jack 所在的城市信息，该怎么处理？

1. 使用计算属性

    var city: String {
        return addressInfo.city
    }

但这种方式的弊端是：万一如果想把 AddressInfo 这嵌套的一层直接去掉，得手写好多类似上面的代码。

2. 使用嵌套的 CodingKey 枚举

使用嵌套的 CodingKey 枚举可以把具有层级的 JSON “拍扁”。

    enum CodingKeys: String, CodingKey {
        case name
        case accessKey
        case status
        case addressInfo = "AddressInfo"
        case contactInfo = "ContactInfo"
    }
    
    enum AddressInfo: String, CodingKey {
        case atmCode
        case street
        case city
        case zip
    }
    
    enum ContactInfo: String, CodingKey {
        case homePhone, cellularPhone, email, website
        case addedOn
    }

还得自己实现对应的 decode 方法：

    init(from decoder: Decoder) throws {
        let customer = try decoder.container(keyedBy: CodingKeys.self)
        let name = try customer.decode(String.self, forKey: .name)
        let accessKey = try customer.decode(String.self, forKey: .accessKey)
        let status = try customer.decode(Int.self, forKey: .status)
        self.name = name
        self.accessKey = accessKey
        
        let addressInfo = try customer.nestedContainer(keyedBy: AddressInfo.self, forKey: .addressInfo)
        let atmCode = try addressInfo.decode(String.self, forKey: .atmCode)
        let street = try addressInfo.decode(String.self, forKey: .street)
        let city = try addressInfo.decode(String.self, forKey: .city)
        
        // 当 JSON 对象中 `zip` key 对应的 value 类型是 String 时的兼容处理
        if case let zipString? = try? addressInfo.decodeIfPresent(String.self, forKey: .zip),
            let zipString = zipString
        {
            self.zip = Int(zipString) ?? -1
        } else if let zipInt = try addressInfo.decodeIfPresent(Int.self, forKey: .zip) {
            self.zip = zipInt
        } else {
            self.zip = -1
        }
        
        self.atmCode = atmCode
        self.street = street
        self.city = city
        
        let contactInfo = try customer.nestedContainer(keyedBy: ContactInfo.self, forKey: .contactInfo)
        let homePhone = try contactInfo.decode(String.self, forKey: .homePhone)
        let cellularPhone = try contactInfo.decode(String.self, forKey: .cellularPhone)
        let email = try contactInfo.decode(String.self, forKey: .email)
        let website = try contactInfo.decode(String.self, forKey: .website)
        let addedOn = try contactInfo.decode(Date.self, forKey: .addedOn)
        self.homePhone = homePhone
        self.cellularPhone = cellularPhone
        self.email = email
        self.website = website
        self.addedOn = addedOn
    }

在自己实现 decode 方法时，还需要对几类容器（Container）有了解：
JSON 示例中 Keyed、Nested、Unkeyed 和 Single Value 四类容器的位置

  • Keyed Container：最常见的容器之一，可用来解析键值对数据，对应的 key 定义在 CodingKeys 枚举中。
  • Unkeyed Container：用来解析不是以字符串为 key 的结构，例如常见的数组结构。
  • Single Value Container：用来把单一的数据解析为有具体类型的数据结构。
  • Nested Container：当某个容器成为另一个容器的子容器时，它被称为嵌套容器

我们可以方便地把容器理解为：一个对数据编解码的环境。

被“拍扁”后的模型为：

struct Customer2: Encodable {
    var name: String
    var accessKey: String
    var family: [String]
    
    var atmCode: String
    var street: String
    var city: String
    var zip: Int
    
    var homePhone: String
    var cellularPhone: String
    var email: String
    let website: String
    let addedOn = Date()

如何 Encode?

示例模型对象：

import Foundation

struct Customer: Encodable {
  var name: String
  var accessKey: String
  
  var atmCode: String
  var street: String
  var city: String
  var zip: Int
  
  var homePhone: String
  var cellularPhone: String
  var email: String
  let website: String
  let addedOn = Date()
  var family: [String]
}

let customer = Customer(
  name: "Shai Mishali",
  accessKey: "S|_|p3rs3cr37",
  atmCode: "1132",
  street: "3828 Piermont Drive",
  city: "Albuquerque",
  zip: 87119,
  homePhone: "+1 212-741-4695",
  cellularPhone: "+972 542-288-482",
  email: "freak4pc@gmail.com",
  website: "http://github.com/freak4pc",
  family: ["Tom", "Elia"]
)

我们可以利用 Encodable 的默认实现来把模型对象转为 JSON 对象：

let dateFormatter: DateFormatter = {
  let dateFormatter = DateFormatter()
  dateFormatter.dateFormat = "MM-dd-yyyy HH:mm"
  return dateFormatter
}()

let jsonEncoder = JSONEncoder()
jsonEncoder.dateEncodingStrategy = .formatted(dateFormatter)
jsonEncoder.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]

if let jsonObject = try? jsonEncoder.encode(customer),
let jsonString = String(data: jsonObject, encoding: .utf8) {
  print(jsonString)
}

// 输出：
{
  "accessKey" : "S|_|p3rs3cr37",
  "addedOn" : "04-14-2022 15:36",
  "atmCode" : "1132",
  "cellularPhone" : "+972 542-288-482",
  "city" : "Albuquerque",
  "email" : "freak4pc@gmail.com",
  "family" : [
    "Tom",
    "Elia"
  ],
  "homePhone" : "+1 212-741-4695",
  "name" : "Shai Mishali",
  "street" : "3828 Piermont Drive",
  "website" : "http://github.com/freak4pc",
  "zip" : 87119
}

修改 JSON 对象的层级结构

如果想修改 encode 之后的 JSON 对象的层级结构呢？还是得使用嵌套的 CodingKey 枚举，并自己实现 encode 方法：

    func encode(to encoder: Encoder) throws {
        var customer = encoder.container(keyedBy: CodingKeys.self)
        try customer.encode(name, forKey: .name)
        try customer.encode(accessKey, forKey: .accessKey)
        
        var addressInfo = customer.nestedContainer(keyedBy: AddressInfo.self, forKey: .addressInfo)
        try addressInfo.encode(atmCode, forKey: .atmCode)
        try addressInfo.encode(street, forKey: .street)
        try addressInfo.encode(city, forKey: .city)
        try addressInfo.encode(zip, forKey: .zip)
        
        var contactInfo = customer.nestedContainer(keyedBy: ContactInfo.self, forKey: .contactInfo)
        try contactInfo.encode(homePhone, forKey: .homePhone)
        try contactInfo.encode(cellularPhone, forKey: .cellularPhone)
        try contactInfo.encode(email, forKey: .email)
        try contactInfo.encode(website, forKey: .website)
        try contactInfo.encode(addedOn, forKey: .addedOn)
    }

达成 Codable

通过上述自定义 encode 和 decode 操作之后，就达成 Codable 。

import Foundation

struct Customer: Codable {
    internal init(name: String, accessKey: String, atmCode: String, street: String, city: String, zip: Int, homePhone: String, cellularPhone: String, email: String, website: String, addedOn: Date = Date(), family: [String]) {
        self.name = name
        self.accessKey = accessKey
        self.atmCode = atmCode
        self.street = street
        self.city = city
        self.zip = zip
        self.homePhone = homePhone
        self.cellularPhone = cellularPhone
        self.email = email
        self.website = website
        self.addedOn = addedOn
        self.family = family
    }
    
    var name: String
    var accessKey: String
    
    var atmCode: String
    var street: String
    var city: String
    var zip: Int
    
    var homePhone: String
    var cellularPhone: String
    var email: String
    let website: String
    var addedOn: Date = Date()
    var family: [String]
    
    enum CodingKeys: String, CodingKey {
        case name
        case accessKey
        case family
        case addressInfo = "AddressInfo"
        case contactInfo = "ContactInfo"
    }

    enum AddressInfo: String, CodingKey {
        case atmCode
        case street
        case city
        case zip
    }

    enum ContactInfo: String, CodingKey {
        case homePhone, cellularPhone, email, website
        case addedOn
    }
    
    func encode(to encoder: Encoder) throws {
        var customer = encoder.container(keyedBy: CodingKeys.self)
        try customer.encode(name, forKey: .name)
        try customer.encode(accessKey, forKey: .accessKey)
        
        var family = customer.nestedUnkeyedContainer(forKey: .family)
        try family.encode(contentsOf: self.family)

        var addressInfo = customer.nestedContainer(keyedBy: AddressInfo.self, forKey: .addressInfo)
        try addressInfo.encode(atmCode, forKey: .atmCode)
        try addressInfo.encode(street, forKey: .street)
        try addressInfo.encode(city, forKey: .city)
        try addressInfo.encode(zip, forKey: .zip)

        var contactInfo = customer.nestedContainer(keyedBy: ContactInfo.self, forKey: .contactInfo)
        try contactInfo.encode(homePhone, forKey: .homePhone)
        try contactInfo.encode(cellularPhone, forKey: .cellularPhone)
        try contactInfo.encode(email, forKey: .email)
        try contactInfo.encode(website, forKey: .website)
        try contactInfo.encode(addedOn, forKey: .addedOn)
    }
    
    init(from decoder: Decoder) throws {
        let customer = try decoder.container(keyedBy: CodingKeys.self)
        let name = try customer.decode(String.self, forKey: .name)
        let accessKey = try customer.decode(String.self, forKey: .accessKey)
        self.name = name
        self.accessKey = accessKey

        let addressInfo = try customer.nestedContainer(keyedBy: AddressInfo.self, forKey: .addressInfo)
        let atmCode = try addressInfo.decode(String.self, forKey: .atmCode)
        let street = try addressInfo.decode(String.self, forKey: .street)
        let city = try addressInfo.decode(String.self, forKey: .city)

        // 当 JSON 对象中 `zip` key 对应的 value 类型是 String 时的兼容处理
        if case let zipString? = try? addressInfo.decodeIfPresent(String.self, forKey: .zip),
            let zipString = zipString
        {
            self.zip = Int(zipString) ?? -1
        } else if let zipInt = try addressInfo.decodeIfPresent(Int.self, forKey: .zip) {
            self.zip = zipInt
        } else {
            self.zip = -1
        }

        self.atmCode = atmCode
        self.street = street
        self.city = city

        let contactInfo = try customer.nestedContainer(keyedBy: ContactInfo.self, forKey: .contactInfo)
        let homePhone = try contactInfo.decode(String.self, forKey: .homePhone)
        let cellularPhone = try contactInfo.decode(String.self, forKey: .cellularPhone)
        let email = try contactInfo.decode(String.self, forKey: .email)
        let website = try contactInfo.decode(String.self, forKey: .website)
        let addedOn = try contactInfo.decode(Date.self, forKey: .addedOn)
        self.homePhone = homePhone
        self.cellularPhone = cellularPhone
        self.email = email
        self.website = website
        self.addedOn = addedOn

        let family = try customer.decode([String].self, forKey: .family)
        self.family = family
    }
}

可以看出：自定义实现 encode 和 decode 方法所带来的代码量还是不小的，然而于此同时也带来了较高的灵活度。

举个例子，假如 JSON 对象中 zip 对应的值的类型是字符串，如“87119”。而 Customer 模型中 zip 变量类型为 Int，则可以在自定义 decode 方法中特别处理：

// 当 JSON 对象中 `zip` key 对应的 value 类型是 String 时的兼容处理
if case let zipString? = try? addressInfo.decodeIfPresent(String.self, forKey: .zip),
let zipString = zipString
{
    self.zip = Int(zipString) ?? -1
} else if let zipInt = try addressInfo.decodeIfPresent(Int.self, forKey: .zip) {
    self.zip = zipInt
} else {
    self.zip = -1
}

再者，如果 JSON 新加一个 memberType 字段来表示顾客的身份：

enum MemberType: Int {
    case visitor = 1
    case vip = 2
    case unknown = -1
}

突然某一天，收到的 JSON 对象中 memberType 为 3，意味超级 vip 客户，这是业务迭代新增的需求，而在 Customer 未对此改动作相应的更新时，也在 decode 方法里对这种情况作兼容处理，比如直接设为 .unknown。

JSONEncoder

  • KeyEncodingStrategy：内置默认的 convertToSnakeCase 策略，如模型中的变量名为：xmlContents，经过 convertToSnakeCase 策略之后，对应的 JSON key 会变为 xml_contents。也提供自定义的接口，让开发者自行决定。
  • OutputFormatting：内置三种默认的输出格式化方式
    • prettyPrinted：iOS 7 开始支持
    • sortedKeys：iOS 11 开始支持
    • withoutEscapingSlashes：iOS 13 开始支持
  • userInfo：外部可通过此与自定义的 encode 过程进行信息传递。
  • DateEncodingStrategy：内置 iso8601 等编码格式，同时也提供传入自定义的 DateFormatter 对象对日期进行自定义处理。
  • DataEncodingStrategy：内置 base64 等编码格式，同时也提供自定义接口，让开发者自行决定。

JSONDecoder 的结构与 JSONEncoder 很相似，不再一一赘述。

SwiftyJSON 源码分析（未完待续）

SwiftyJSON 的 JSON 结构体组成及其输入和协议关系

]]>Sunset Wan打造一个简单的 iOS App CI 系统2022-03-30T09:41:00+08:002022-03-30T09:41:00+08:00https://sunsetwan.github.io/2022/03/30/%E6%89%93%E9%80%A0%E4%B8%80%E4%B8%AA%E7%AE%80%E5%8D%95%E7%9A%84%20iOS%20App%20CI%20%E7%B3%BB%E7%BB%9F除了 Xcode Cloud，你还有别的选择。
本文介绍如何在 macOS 上使用 fastlane 来帮助你打造一个简单的 iOS App CI 系统。

在安装 fastlane 之前

与 macOS 系统自带的 Ruby 环境隔离

fastlane 对 Ruby 的最低要求是 2.5 及以上版本。虽然 macOS 自带 Ruby 环境，但强烈建议单独配置个 Ruby 环境，与系统自带的 Ruby 环境隔离。Ruby 官方有给出管理多版本 Ruby 的 方法，我个人常使用的是 rbenv。

使用 bundler 管理 gem

使用 bundler 管理 gem，这能确保团队协作时 gem（cocoapods 和 fastlane 等） 版本的统一。举个例子，如果团队成员的 cocoapods 版本不统一，Podfile.lock 这个文件经常会出现不必要的改动。

跟 cocoapods 管理 pod 类似，bundler 通过 Gemfile 来安装所需的 gem。

本文所使用的 Gemfile 内容为：

source "https://rubygems.org"
gem "fastlane", '2.195.0'
gem "cocoapods"

值得一提的是：要在 bundler 管理的环境下，执行相关 gem 的命令，得加上 bundle exec 的前缀。对 bundle exec 命令的详细介绍，请参考这篇 文档。

使用 fastlane 接管应用的打包和上传 App store 流程

1. 设置打包参数

一般地，在开始打包之前，需要的参数为：

  1. 代码对应的分支名：branchName（String Type）
  2. App scheme 名：scheme（String Type）
  3. 是否需要上传 App store：deployToProd （Boolean）

其他的参数，可以根据自己的需要来设定。

2. 自动同步签名证书和 Provisioning Profile

fastlane 的 match 可以帮助在多台 macOS 设备自动同步签名证书和 Provisioning Profile。match 支持以多种方式存储签名证书和 Provisioning Profile，如存在 Git 仓库中、存在云上（Azure、Google Cloud 和 AWS）等。

一般地，会选择使用 match 把签名证书和 Provisioning Profile 加密保存在 Git 仓库上。此时，为了安全，match 会提醒你设置一个密码，这样在新的 macOS 设备上同步证书信息时，会提示输入密码，提高数据的安全性。

在 match 初始化配置完毕后，敲以下命令，可以同步三种导出方式对应的证书信息至本地，然后重启下 Xcode，点进 Signing & Capabilities 查看是否生效。

bundle exec fastlane match appstore
bundle exec fastlane match development
bundle exec fastlane match adhoc

虽然 match 的文档上写明：第一次初始化 match 前，建议使用 match nuke 命令来清理现有的签名证书和 Provisioning Profiles，但经验而谈，最好是用 match 管理签名证书和 Provisioning Profiles 的这套做法在组内成功推广开来之后再用 😜。

3. 更新代码

根据第一步获取的 branchName，在 ruby 脚本内执行 git 命令即可。

4. 安装 Pod 依赖

fastlane 的 cocoapods 可用来安装 iOS 工程的 Pod 依赖，指定 Podfile 的路径即可。

podFilePath = File.absolute_path("../").to_s
# install_dependencies
cocoapods(
	clean_install: true,
	podfile: podFilePath,
	verbose: true,
	repo_update: true
)

5. 清除 Xcode 缓存

fastlane 的 clear_derived_data 可用来清除 Xcode 缓存。

6. 开始打包

fastlane 的 gym 可用来执行 Xcode 打包命令。

gym(
	workspace: workspaceName, # 以 .xcworkspace.xcworkspace 结尾的 iOS 工程名
	scheme: fullScheme, # iOS 工程的 scheme 名
	export_method: exportMethod, # 所选的导出方法，与 fastlane match type 有关
	silent: false,
	clean: false,
	output_directory: ipaOutputPath,
	output_name: iPAOutputName,
	suppress_xcode_output: true,
	include_symbols: false,
	include_bitcode: false,
	build_path: fastlaneBuildPath,
	archive_path: archivePath,
	derived_data_path: fastlaneDerivedDataPath,
	buildlog_path: logPath,
	analyze_build_time: false,
	destination: "generic/platform=iOS"
)

iOS App scheme、match type 和 gym export method 三者之间可能对应的关系如下图所示：
test、pre-prod 与 prod 三种 scheme 对应的 match type 和 gym export method

7. 上传至 App store

fastlane 老式的做法是用 Apple ID 的账号密码去登陆 App store connect，这样不光得设置一大堆环境变量，如下：

FASTLANE_USER = "sunsetwan@gmail.com"
FASTLANE_ITC_TEAM_NAME = "Sunset Technology Co. LTD"
FASTLANE_PASSWORD = "xxx"
app_identifier = "com.sunset.test"
SPACESHIP_2FA_SMS_DEFAULT_PHONE_NUMBER = "+86xxx"
FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD = "xxx"

而且登陆态一般只能维持两个礼拜。一旦过期，得重新输入 Apple ID 两步验证发来的短信验证码，这一点是比较令人困扰的，会直接打断自动化的流程，且现在 Apple ID 一旦开启了两步验证，就没法关闭了。

现在推荐使用 App Store Connect API 的方式来完成 Apple ID 的认证授权。

主要的三个步骤如下：

  1. 用「账户持有者」权限的 Apple ID 登陆 App Store Connect，创建 API Key 文件（.p8）。
  2. 把这 API Key 文件保存在 CI 机器上
  3. 使用 fastlane 的 app_store_connect_api_key 来完成验证。

参考代码：

desc "使用 App Store Connect API 的 deliver"
private_lane :swizzed_deliver do |options|
	ipa_file_absolute_path = options[:ipa_file_absolute_path]
	if ipa_file_absolute_path.to_s.empty? 
		raise "ipa_file_absolute_path is empty"
	end
	
	app_connect_api_key_path = ""
	Dir.chdir("../app_connect_api_key") do
		searchPattern = "AuthKey_xxx.p8"
		files = Dir.glob(searchPattern)
		if files.empty?
			raise "Error: can't find AuthKey_xxx.p8\nsearchPattern: #{searchPattern}\nCurrentPWD: #{Dir.pwd}"
		else
			path = files[0].to_s
			app_connect_api_key_path = File.absolute_path(path)
		end 
	end 
	
	api_key = app_store_connect_api_key(
		key_id: "xxx",
		issuer_id: "xxx",
		key_filepath: app_connect_api_key_path, 
		duration: 1200, # optional (maximum 1200)
		in_house: false # optional but may be required if using match/sigh
	)

	if api_key.nil? 
		raise "api key is missing!"
	end
	
	deliver(
		ipa: ipa_file_absolute_path,
		skip_screenshots: true,
		skip_metadata: true,
		skip_app_version_update: true,
		force: true,
		api_key: api_key,
		run_precheck_before_submit: false
	)
end

最后，可以配合使用 Gitlab Runner，来自动触发上述构建流程。

CI 的核心是什么？

我带着这问题去读了下《Software Engineering at Google》的第 23 章节 Continuous Integration。我个人觉得这问题的答案是：

A CI system decides what tests to use, and when.

当然，我认为这里提到的 test 不一定就是单元测试，可能还包含 lint 工具的执行结果等。

我前阵子读 Kingfisher 源码的时候，发现它也有写不少测试代码。

于是，我找到 Jon Reid 写的《iOS Unit Testing by Example: XCTest Tips and Techniques Using Swift》，决定读一读，学习如何使用 XCTest。

其中有关 XCTestCase 的生命周期的介绍，令人印象深刻，记录于此。
假设我们要测试的类为 MyClass：

class MyClass {
    
    private static var allInstances = 0
    private let instance: Int

    init() {
        MyClass.allInstances += 1
        instance = MyClass.allInstances
        print(">> MyClass.init() #\(instance)")
    }
    
    deinit {
        print(">> MyClass.deinit #\(instance)")
    }
    
    func methodOne() {
        print(">> methodOne")
    }
    
    func methodTwo() {
        print(">> methodTwo")
    }
}

对应的测试代码 MyClassTests 为：

import XCTest
@testable import TestLifeCycle

class MyClassTests: XCTestCase {

    func test_methodOne() {
        let sut = MyClass()
        sut.methodOne()
    }
    
    func test_methodTwo() {
        let sut = MyClass()
        sut.methodTwo()
    }
}

Xcode 中包含 test_methodOne 和 test_methodTwo 的 MyClassTests 测试类，左侧可运行整组测试
点击运行按钮，可以看到如下测试日志：
两个测试均各自创建、调用并销毁一个 MyClass 实例的测试日志
以 test_methodOne 方法为例，整个测试流程方法调用顺序为：

  1. MyClass.init()
  2. methodOne
  3. MyClass.deinit()

但 test_methodOne 方法和 test_methodTwo 方法内分别创建了一个 MyClass 实例，是不是代码有些重复了？

于是，我尝试这样优化：

class MyClassTests: XCTestCase {
    
    private let sut = MyClass()

    func test_methodOne() {
        sut.methodOne()
    }
    
    func test_methodTwo() {
        sut.methodTwo()
    }
}

再次点击运行按钮，得到如下测试日志：
把 MyClass 设为测试类属性后，测试运行前连续初始化两个实例且没有销毁日志
咦！怎么 MyClass.init() 调用了两次？MyClass.deinit() 方法没被调用！
在测试代码开始运行之前，两个 MyClass 的实例被创建了，且从未被销毁！这样会有两个潜在的问题：

  1. 如果 MyClass 的 init 方法出了问题，测试代码很难捕捉到这个问题，因为问题发生的时机在任何测试代码运行之前。
  2. 如果 MyClass 的 deinit 方法出了问题，测试代码很难捕捉到这个问题，因为这些对象未被销毁。

XCTest 是如何管理 Test case 的？

我想当然觉得是这样的：

  1. 创建 XCTestCase 子类的实例对象
  2. 执行创建好的实例对象的测试方法
  3. 执行完毕，销毁创建好的实例对象

但实际上是这样的：

  1. XCTest 找到所有 XCTestCase 的子类
  2. 在每一个这样的子类中，找到每个测试方法
  3. 对于每个测试方法，XCTest 会创建一个对应的实例
  4. XCTest 把每种 XCTestCase 的子类的实例包装成一个个的 test suite
  5. 当前四个步骤完成后，XCTest 开始运行测试代码。

以 MyClassTests 为例：

  1. XCTest 找到 XCTestCase 的子类：MyClassTests
  2. 在 MyClassTests 中，找到两个测试方法：test_methodOne 和 test_methodTwo
  3. 创建两个 MyClassTests 的实例
  4. 把这两个实例包装成一个 test suite

因为这两个 MyClassTests 的实例均持有 MyClass 属性，所以这就是 MyClass.init() 调用了两次的原因。

避免重复测试代码的正确方式

这里介绍 XCTest 的两个方法：setUp() 和 tearDown()
setUp() 方法是在每个测试方法执行前执行，用来设置初始状态。
tearDown() 方法是在每个测试方法执行后执行，用来执行清理动作。
使用这两个方法优化之后的代码：

import XCTest
@testable import TestLifeCycle

class MyClassTests: XCTestCase {
    
    private var sut: MyClass!
    
    override func setUp() {
        super.setUp()
        sut = MyClass()
    }
    
    override func tearDown() {
        sut = nil
        super.tearDown()
    }

    func test_methodOne() {
        sut.methodOne()
    }
    
    func test_methodTwo() {
        sut.methodTwo()
    }
}

再次点击运行按钮，得到如下测试日志：
使用 setUp 与 tearDown 后，每个测试都正确初始化并销毁 MyClass 实例的日志
Wow！实例对象正确地初始化了，最终也被正确地销毁了！

fastlane 的 run_tests 可用来在 ruby 脚本中执行测试代码。

结语

有人会说：搞个 CI 成本太高了，但我觉得它带来的价值是高于成本的。
这里引用《Software Engineering at Google》第 23 章节的一段话：

CI leads to a more stable product and happier developer culture in which engineers feel more confident that “the system” will catch problems, and they can focus more on features and less on fixing.

让工程师们 focus more on features and less on fixing，这一点真的很重要。

]]>Sunset WanKingfisher 源码阅读（一）2022-03-28T09:41:00+08:002022-03-28T09:41:00+08:00https://sunsetwan.github.io/2022/03/28/Kingfisher%20%E6%BA%90%E7%A0%81%E9%98%85%E8%AF%BB%EF%BC%88%E4%B8%80%EF%BC%89最近想了解如何设计一个简单的缓存系统，于是找了 Kingfisher 7.1.2 版本的源代码读一读，有些收获，记录于此。

缓存系统一般可分为：内存缓存（memory cache）和硬盘缓存（disk cache）。

内存缓存

内存缓存背后支撑的数据结构是 Foundation 框架中的 NSCache。
NSCache 有两个限制：countLimit 和 totalCostLimit。前者是表示能存储多少个对象，后者是表示缓存的容量有多大。但这两个限制是软限制——如果超过限制，NSCache 中保存的对象不一定会被及时地从其中移出。根据 官方文档，超过限制之后，对象的移出时机取决与 NSCache 背后的实现。

NSCache 的泛型声明要求 KeyType 和 ObjectType 都是 AnyObject 引用类型

NSCache 是个泛型类，所以我们得定义好 KeyType 和 ObjectType。
根据声明的类型约束，KeyType 的类型得是一个类。一般地，类似 key 的数据结构会采用 String。而这里 KeyType 得是引用类型而不是值类型，所以我们会选择 NSString。但在 API 设计时，对外暴露的那一层 API，还是可以使用 String。到调用 NSCache 的 setObject(_:forKey:cost:) 方法时，再把 String 转为 NSString。之所以这样做，是因为值类型更符合当前场景的需求。
Kingfisher 中 ObjectType 对应的数据结构是这么设计的：

class StorageObject<T> {
    let value: T // 图片的数据
    let expiration: StorageExpiration // 过期策略
    let key: String
    
    private(set) var estimatedExpiration: Date // 预计到期时间
    
    init(_ value: T, key: String, expiration: StorageExpiration) {
        self.value = value
        self.key = key
        self.expiration = expiration
        
        self.estimatedExpiration = expiration.estimatedExpirationSinceNow
    }
    
    // 根据当前缓存对象的续期策略，进行续期。
    func extendExpiration(_ extendingExpiration: ExpirationExtending = .cacheTime) {
        switch extendingExpiration {
            case .none:
            return
            case .cacheTime:
            self.estimatedExpiration = expiration.estimatedExpirationSinceNow
            case .expirationTime(let expirationTime):
            self.estimatedExpiration = expirationTime.estimatedExpirationSinceNow
        }
    }
    
    var expired: Bool {
        return estimatedExpiration.isPast
    }
}

硬盘缓存

所谓硬盘缓存，就是把缓存数据写入一个文件。当对象写入硬盘缓存时，需要的是图片的数据，缓存的 Key 以及过期策略（StorageExpiration）。写入文件的 URL 是通过缓存的 Key 计算可得。

Kingfisher 利用操作系统中的文件系统来快捷地存储该缓存对象的 上一次访问时间 和 预计到期时间。Kingfisher 把写入文件的 创建时间 写为 上一次访问时间，把写入文件的 修改日期 写为 预计到期时间，还挺巧妙的 🤯。

let now = Date()
let attributes: [FileAttributeKey : Any] = [
    // The last access date.
    .creationDate: now.fileAttributeDate,
    // The estimated expiration date.
    .modificationDate: expiration.estimatedExpirationSinceNow.fileAttributeDate
]
do {
    try config.fileManager.setAttributes(attributes, ofItemAtPath: fileURL.path)
} catch {
    try? config.fileManager.removeItem(at: fileURL)
    throw KingfisherError.cacheError(
        reason: .cannotSetCacheFileAttribute(
            filePath: fileURL.path,
            attributes: attributes,
            error: error
        )
    )
}

当从硬盘中访问缓存时，Kingfisher 设计了 FileMeta 数据结构：

struct FileMeta {
    
    let url: URL
    
    let lastAccessDate: Date?
    let estimatedExpirationDate: Date?
    let isDirectory: Bool
    let fileSize: Int
    
    init(
        fileURL: URL,
        lastAccessDate: Date?,
        estimatedExpirationDate: Date?,
        isDirectory: Bool,
        fileSize: Int)
    {
        self.url = fileURL
        self.lastAccessDate = lastAccessDate
        self.estimatedExpirationDate = estimatedExpirationDate
        self.isDirectory = isDirectory
        self.fileSize = fileSize
    }
    
    func expired(referenceDate: Date) -> Bool {
        return estimatedExpirationDate?.isPast(referenceDate: referenceDate) ?? true
    }
    
    // 根据当前缓存对象的续期策略，进行续期。
    func extendExpiration(with fileManager: FileManager, extendingExpiration: ExpirationExtending) {
        guard let lastAccessDate = lastAccessDate,
        let lastEstimatedExpiration = estimatedExpirationDate else
        {
            return
        }
        
        let attributes: [FileAttributeKey : Any]
        
        switch extendingExpiration {
            case .none:
            // not extending expiration time here
            return
            case .cacheTime:
            let originalExpiration: StorageExpiration =
            .seconds(lastEstimatedExpiration.timeIntervalSince(lastAccessDate))
            attributes = [
                .creationDate: Date().fileAttributeDate,
                .modificationDate: originalExpiration.estimatedExpirationSinceNow.fileAttributeDate
            ]
            case .expirationTime(let expirationTime):
            attributes = [
                .creationDate: Date().fileAttributeDate,
                .modificationDate: expirationTime.estimatedExpirationSinceNow.fileAttributeDate
            ]
        }
        
        try? fileManager.setAttributes(attributes, ofItemAtPath: url.path)
    }
}

不难看出：FileMeta 的设计思路与 StorageObject 的设计思路有不少相似的地方。

缓存过期策略

Kingfisher 有设计 5 种缓存对象的过期策略：

public enum StorageExpiration {
    case never // 缓存对象永不过期
    case seconds(TimeInterval) // 缓存对象在当前时间点后的 x 秒过期
    case days(Int) // 缓存对象在当前时间点后的 x 天过期
    case date(Date) // 缓存对象在指定 Date 过期
    case expired // 缓存对象已过期
		...
		...
}

缓存续期策略

根据程序局部性的原理，被访问过的缓存很有可能再被访问一次，所以也应有缓存续期策略。
Kingfisher 有设计 3 种缓存续期策略：

public enum ExpirationExtending {
    case none // 不续期，到期时间不变
    case cacheTime // 以当前时间点为基础续期
    case expirationTime(_ expiration: StorageExpiration) // 以指定到期策略续期
}

无论是内存缓存还是硬盘缓存，默认的缓存续期策略均为：cacheTime。

缓存清除策略

内存缓存清除策略

内存缓存的清除策略分为两种：

  1. 系统控制：超过 NSCache 的“软限制”，系统自动清除。
  2. 自己控制：定期扫描已缓存的对象，移出已过期的对象。

对于缓存系统来说，策略 1 是可能有负面影响的，因为系统可能会清除一个仍未过期的对象，从而降低了缓存的命中率。可行的解决办法是：提高 NSCache 的 totalCostLimit。然而这会导致缓存对象所占用的内存变大，需要自己把握这之间的平衡。

内存缓存的对象默认的有效期是 5 分钟。关于策略 2，Kingfisher 设计了一个 timer 来周期性（默认周期为 2 分钟）地清除过期的缓存对象。

cleanTimer = .scheduledTimer(withTimeInterval: config.cleanInterval, repeats: true) { [weak self] _ in
    guard let self = self else { return }
    self.removeExpired()
}

...
...

public func removeExpired() {
    lock.lock()
    defer { lock.unlock() }
    for key in keys {
        let nsKey = key as NSString
        guard let object = storage.object(forKey: nsKey) else {
            keys.remove(key)
            continue
        }
        if object.estimatedExpiration.isPast {
            storage.removeObject(forKey: nsKey)
            keys.remove(key)
        }
    }
}

硬盘缓存清除策略

硬盘缓存的对象默认的有效期是 7 天，其清除策略是自己控制的。
类似地，Kingfisher 也对硬盘缓存的可用容量做了限制，通过 sizeLimit 来控制。但 Kingfisher 在对象存入硬盘缓存时，并未对对象的大小做检查。我的猜想是一方面是可以提高缓存的命中率，另一方面是有其他更好的时机来核查缓存对象的大小，并清除过大的缓存对象。

如果 app 进入了 UIApplication.State.background 状态，Kingfisher 就会开始清理过期的对象和过大的缓存对象。

清理过期对象的做法：

func removeExpiredValues(referenceDate: Date) throws -> [URL] {
    let propertyKeys: [URLResourceKey] = [
        .isDirectoryKey,
        .contentModificationDateKey
    ]
    
    let urls = try allFileURLs(for: propertyKeys)
    let keys = Set(propertyKeys)
    let expiredFiles = urls.filter { fileURL in
        do {
            let meta = try FileMeta(fileURL: fileURL, resourceKeys: keys)
            if meta.isDirectory {
                return false
            }
            return meta.expired(referenceDate: referenceDate)
        } catch {
            return true
        }
    }
    try expiredFiles.forEach { url in
        try removeFile(at: url)
    }
    return expiredFiles
}

清理过大对象的做法：

func removeSizeExceededValues() throws -> [URL] {
    
    if config.sizeLimit == 0 { return [] } // 0 意味着无大小限制。
    
    var size = try totalSize()
    if size < config.sizeLimit { return [] }
    
    let propertyKeys: [URLResourceKey] = [
        .isDirectoryKey,
        .creationDateKey,
        .fileSizeKey
    ]
    let keys = Set(propertyKeys)
    
    let urls = try allFileURLs(for: propertyKeys)
    var pendings: [FileMeta] = urls.compactMap { fileURL in
        guard let meta = try? FileMeta(fileURL: fileURL, resourceKeys: keys) else {
            return nil
        }
        return meta
    }

    // 以上一次访问时间从大到小排序，最近访问的对象排在最前。
    pendings.sort(by: FileMeta.lastAccessDate)
    
    var removed: [URL] = []
    let target = config.sizeLimit / 2
    while size > target, let meta = pendings.popLast() {
        size -= UInt(meta.fileSize)
        try removeFile(at: meta.url)
        removed.append(meta.url)
    }
    return removed
}

「清理过大对象」这个说法其实有些模糊，更准确地说明是：如果当前硬盘缓存的容量大于 sizeLimit，则根据对象的上一次访问时间进行排序，最近访问的对象排在前面。Kingfisher 的做法是：从最不经常访问的对象开始删除，直到当前存储的对象的总大小缩减至一半及其以下，才停止删除。这是经典的 LRU 缓存淘汰算法。

出错处理

Kingfisher 把自身模块内的错误细分为 5 类，分别为：

/// Represents the error reason during networking request phase.
case requestError(reason: RequestErrorReason)
/// Represents the error reason during networking response phase.
case responseError(reason: ResponseErrorReason)
/// Represents the error reason during Kingfisher caching system.
case cacheError(reason: CacheErrorReason)
/// Represents the error reason during image processing phase.
case processorError(reason: ProcessorErrorReason)
/// Represents the error reason during image setting in a view related class.
case imageSettingError(reason: ImageSettingErrorReason)

每类错误还会携带对应出错原因。从错误的分类，可以大致看出 Kingfisher 分为图片下载模块、图片缓存模块、图片处理模块等模块。

其他

在阅读 Kingfisher 缓存系统相关代码时，我还发现了其他值得学习的代码，一并记录。

网络请求重试机制

Kingfisher 重试机制：RetryStrategy 根据数据源、错误和重试次数决定继续重试或停止
Kingfisher 设计一个 RetryStrategy 协议，由遵循该协议的对象来作出决定（RetryDecision）。RetryDecision 有两种：继续重试和停止重试。

遵循 RetryStrategy 协议的对象内部设计了三种重试模式：

public struct DelayRetryStrategy: RetryStrategy {
    
    public enum Interval {
        case seconds(TimeInterval) // 指定 n 秒后重试
        case accumulated(TimeInterval) // 指定 n 秒以累加的方式重试，例如第一次为 3s 后重试，第二次就是 6s 后重试，以此类推。
        case custom(block: (_ retriedCount: Int) -> TimeInterval) // 告诉你已经重试的次数，自行决定几秒后进行重试
        
        func timeInterval(for retriedCount: Int) -> TimeInterval {
            let retryAfter: TimeInterval
            switch self {
                case .seconds(let interval):
                retryAfter = interval
                case .accumulated(let interval):
                retryAfter = Double(retriedCount + 1) * interval
                case .custom(let block):
                retryAfter = block(retriedCount)
            }
            return retryAfter
        }
    }
    
    ...
    ...
    
}

其核心方法实现如下：

public func retry(context: RetryContext, retryHandler: @escaping (RetryDecision) -> Void) {
    // 超过最大重试次数后，停止重试
    guard context.retriedCount < maxRetryCount else {
        retryHandler(.stop)
        return
    }
    
    // 当出错原因是用户取消该任务时，不进行重试
    guard !context.error.isTaskCancelled else {
        retryHandler(.stop)
        return
    }
    
    // 仅在网络请求响应出错时，进行重试
    guard case KingfisherError.responseError = context.error else {
        retryHandler(.stop)
        return
    }
    
    // 根据当前所使用的重试策略，结合当前已重试次数，计算出 interval 秒后进行重试
    let interval = retryInterval.timeInterval(for: context.retriedCount)
    if interval == 0 { // 立即进行重试
        retryHandler(.retry(userInfo: nil))
    } else {
        // 延迟 interval 秒后，提交重试任务。
        DispatchQueue.main.asyncAfter(deadline: .now() + interval) {
            retryHandler(.retry(userInfo: nil))
        }
    }
}

委托模式

iOS 开发者最熟悉的设计模式之一就是 Delegate，常见于 UITableViewDelegate 等。
平时自定义的类有时也需要把某个方法的实现委托给另一个类去实现。
例如，Task 的 finish(taskID: String) 方法需要交给外部去实现：

class Task {
    var onFinished: ((String) -> String?)?
    
    func finish(taskID: String) {
        let string = onFinished?(taskID)
        print(String(describing: string))
    }
}

class KFViewController: UIViewController {
    let subtaskAmount = 3
    override func viewDidLoad() {
        super.viewDidLoad()
    
        let task = Task()
        task.onFinished = { [weak self] taskID in
            guard let self = self else {
                return nil
            }
            
            let string = "Task \(taskID) is finished, the number of subtasks is \(self.subtaskAmount)"
            return string
        }
        // 输出：Optional("Task 123 is finished, the number of subtasks is 3")
        task.finish(taskID: "123")

        ...
        ...

这样的写法是可行的，但每次必须记得在 onFinished 闭包中弱引用 self 以免出现循环引用的问题，导致内存泄漏。

Kingfisher 中有这样一个好用的工具类：class Delegate<Input, Output>：

public class Delegate<Input, Output> {
    public init() {}

    private var block: ((Input) -> Output?)?
    public func delegate<T: AnyObject>(on target: T, block: ((T, Input) -> Output)?) {
        self.block = { [weak target] input in
            guard let target = target else { return nil }
            return block?(target, input)
        }
    }

    public func call(_ input: Input) -> Output? {
        return block?(input)
    }

    public func callAsFunction(_ input: Input) -> Output? {
        return call(input)
    }
}

借助这个工具类，让我们看看优化后的版本：

class Task {
    var onFinished = Delegate<String, String>()
    
    func finish(_ taskID: String) {
        let string = onFinished.call(taskID)
        print(String(describing: string))
    }
}

class KFViewController: UIViewController {
    let subtaskAmount = 3
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let task = Task()
        task.onFinished.delegate(on: self) { (self, taskID) in
            let string = "Task \(taskID) is finished, the amount of its subtask is \(self.subtaskAmount)"
            return string
        }
        
        task.finish("123")
        ...
        ...

下面第二个 self 已是弱引用后的版本，无需每次得加 weak 关键字了。

task.onFinished.delegate(on: self) { (self, taskID) in

再者，把匿名函数（Closure）包装成一个 Delegate 对象使用使得代码更加清晰。

提问 1：为啥 onFinished.call(taskID) 返回的是可选类型 String？

// 这里的泛型约束明明是 String 类型
var onFinished = Delegate<String, String>()

因为 Delegate 内部实现是弱引用 self，所以 self 处于一种可能有可能没有的状态，这就导致返回值的类型均是可选类型的了。

提问 2: 如果把 Output 泛型约束为可选类型，那返回值类型不就是可选的可选类型（??）吗？

public class Delegate<Input, Output> {
    public init() {}
    private var block: ((Input) -> Output?)?
    ...
    ...

Kingfisher 已对这种情况做了处理：

extension Delegate where Output: OptionalProtocol {
    // 此时 Output 的类型为可选类型
    public func call(_ input: Input) -> Output {
        if let result = block?(input) {
            return result
        } else {
            return Output._createNil
        }
    }

    public func callAsFunction(_ input: Input) -> Output {
        return call(input)
    }
}

public protocol OptionalProtocol {
    static var _createNil: Self { get }
}
extension Optional : OptionalProtocol {
    public static var _createNil: Optional<Wrapped> {
         return nil
    }
}

当 Output 类型为可选类型时，新增一个直接返回 Output 的 call 方法。

Kingfisher 还使用了 Swift callAsFunction 的新特性，这意味着可以无需再调用 call 方法，如：

class Task {
    var onFinished = Delegate<String, String>()
    
    func finish(_ taskID: String) {
//        let string = onFinished.call(taskID)
        /// 利用 callAsFunction 的特性
        let string = onFinished(taskID)
        print(String(describing: string))
    }
}

CacheCallbackCoordinator

顾名思义就是缓存模块内的异步回调方法的协调器。

// 是否需要缓存原始图片
let needToCacheOriginalImage = options.cacheOriginalImage &&
options.processor != DefaultImageProcessor.default

let coordinator = CacheCallbackCoordinator(
    shouldWaitForCache: options.waitForCache, shouldCacheOriginal: needToCacheOriginalImage)
let result = RetrieveImageResult(
    image: options.imageModifier?.modify(value.image) ?? value.image,
    cacheType: .none,
    source: source,
    originalSource: context.originalSource
)
// Add image to cache.
let targetCache = options.targetCache ?? self.cache
targetCache.store(
    value.image,
    original: value.originalData,
    forKey: source.cacheKey,
    options: options,
    toDisk: !options.cacheMemoryOnly)
{
    _ in
    coordinator.apply(.cachingImage) {
        completionHandler?(.success(result))
    }
}

if needToCacheOriginalImage {
    let originalCache = options.originalCache ?? targetCache
    originalCache.storeToDisk(
        value.originalData,
        forKey: source.cacheKey,
        processorIdentifier: DefaultImageProcessor.default.identifier,
        expiration: options.diskCacheExpiration)
    {
        _ in
        coordinator.apply(.cachingOriginalImage) {
            completionHandler?(.success(result))
        }
    }
}

coordinator.apply(.cacheInitiated) {
    completionHandler?(.success(result))
}

有两个布尔值在控制 completionHandler?(.success(result)) 执行的时机，它们分别是：

  1. 是否需要缓存原始图片（needToCacheOriginalImage）
  2. 是否等待缓存过程结束（shouldWaitForCache）

在这两个变量的排列组合下，Kingfisher 需要确保该回调执行的次数有且只有一次！

因此，CacheCallbackCoordinator 内部维护了一个包含四种状态的枚举 State、导致状态发生转移的三种 Action，以及描述状态是如何转移的 apply 方法：

enum State {
    case idle
    case imageCached
    case originalImageCached
    case done
}

enum Action {
    case cacheInitiated
    case cachingImage
    case cachingOriginalImage
}

func apply(_ action: Action, trigger: () -> Void) {
    switch (state, action) {
        case (.done, _):
        break
        
        // From .idle
        case (.idle, .cacheInitiated):
        if !shouldWaitForCache {
            state = .done
            trigger()
        }
        case (.idle, .cachingImage):
        if shouldCacheOriginal {
            state = .imageCached
        } else {
            state = .done
            trigger()
        }
        case (.idle, .cachingOriginalImage):
        state = .originalImageCached
        
        // From .imageCached
        case (.imageCached, .cachingOriginalImage):
        state = .done
        trigger()
        
        // From .originalImageCached
        case (.originalImageCached, .cachingImage):
        state = .done
        trigger()
        
        default:
        assertionFailure("This case should not happen in CacheCallbackCoordinator: \(state) - \(action)")
    }
}

有了这些，便可以画出一个有限状态机的状态转移图：CacheCallbackCoordinator 状态机
从图中可以看出：在从 idle 状态到 done 状态的任意一条路线上，trigger 方法的执行次数有且只有一次！这样设计的代码清晰，也容易测试，是很值得学习的案例了！

结语

读 Kingfisher 源码要分享的第一部分就到此结束了，还有图片下载流程、图片处理流程、对多平台的支持（Kingfisher 还支持 watchOS、tvOS 和 macOS）等。

这也是我第一次比较认真地花大段时间仔细读开源代码，收获颇丰。

就这样慢慢进步吧！

]]>Sunset WanWWDC21 10267 一窥 Xcode Cloud2021-08-09T09:41:00+08:002021-08-09T09:41:00+08:00https://sunsetwan.github.io/2021/08/09/WWDC%2021%2010267%20%E4%B8%80%E7%AA%A5%20Xcode%20Cloud有幸参与《WWDC 21 内参》的工作，欢迎 订阅 该专栏！

Xcode Cloud 是为 Apple 平台开发者所设计的一项易用的集持续集成（Continuous Integration）和持续交付（Continuous Delivery）于一体的服务。

持续集成指的是周期性地合并发生变动的代码，这样能尽早地发现问题解决问题，以提高代码质量。

一个典型的持续集成工作流程如下图所示：
典型持续集成流程：推送 Git 变更后执行构建、测试与自定义任务，再生成产物和通知

  1. 将发生变动的代码推送至远端代码仓库。
  2. 项目开始构建、运行测试代码和其他自定义步骤。
  3. 如若通过质量测试（构建成功、测试通过等），保存构建产物，并发出通知至其他团队成员。

再让我们看一下 iOS 应用常见的开发流程：
iOS 应用开发循环：开发团队构建测试并分发，用户手动测试反馈后继续优化

  1. 修复 Bug 和完成新的需求。
  2. 根据团队内部 Code Review 的反馈，对代码作相应的修改。
  3. 通过自测后，将应用分发至测试团队手中。
  4. 根据测试用户的反馈，及时地修复问题。

高效地运作上图所示流程是构建高质量应用的关键。

嘭! Xcode Cloud 此时闪亮登场！
Xcode Cloud 将 Xcode 开发、TestFlight 测试与 App Store 分发连接成闭环
在上述持续集成的流程之上，Xcode Cloud 把应用开发、应用测试和应用分发三点连接起来，提供给开发者一条完整的开发流水线：

  1. 应用开发
  2. 应用测试
  3. 应用分发
  4. 收集使用反馈
  5. 根据反馈，进行快速迭代

立马上手 Xcode Cloud

Xcode 中 Fruta 的 Xcode Cloud 总览，左侧列出工作流与构建状态，右侧汇总各次构建

Fruta 是 Apple 用来演示 Xcode Cloud 的 App。在 Xcode 13 本地打开的 Xcode Cloud 控制台页面大致如上图所示，左边侧边栏展示了已完成/正在执行中的工作流，右边则是对多个工作流的总览，从中我们可以粗略了解整个团队开发的进度。

什么是 Xcode Cloud Workflow？

我们可以把 Xcode Cloud 工作流理解成某种配置。Xcode Cloud 会读取该配置的内容，从而明白自己在何时执行何种任务。某个工作流执行的过程称为一次构建。Xcode Cloud 依托于 Apple 自管理的云端基础设施。该基础设施提供代码签名，同时也能帮助开发者访问多种不同版本的操作系统和 Xcode，例如最新版的 macOS Monterey 和 Xcode 13。

Fruta Build 595 总览：iOS 和 macOS 归档成功，iOS 测试失败，TestFlight 后置操作完成

在左侧边栏中点选某个工作流，展现在我们面前的是该工作流单次运行的总览。从这里，我们能看到测试代码运行的结果与相应的日志，甚至可以双击报错处，直接定位到导致出错的某一行代码。

App Store Connect 网页中的 Fruta Xcode Cloud 构建列表

这些内容可不只是在 Xcode 本地才能看到，也可以在 App Store Connect 网页中获取到，包括开始构建、管理工作流、检阅构建产物、与团队成员共享构建报告和管理通知等。比如，在构建完成后，可以在网页中设置结果通知到 Slack 等交流协作工具，以帮助团队成员在第一时间知道结果。

值得一提的是：网页版的 Xcode Cloud 提供与 Xcode 应用内一致的全功能体验。

One More Thing…

Xcode Cloud 不光是团队开发以及协作流程的好帮手，而且 Apple 一贯良好的隐私保护也未曾在它身上缺席，源代码的管理是软件工程中的核心之一。Xcode Cloud 的方方面面均是为保护用户数据而设计的：

  • 构建环境的信息过一段时间会被删除
  • 从不存储项目源代码
  • 构建数据会被加密存储在 CloudKit 数据库中
  • 用户可随时随地删除数据，且数据会被从 Xcode Cloud 系统中完全移除

为你的工程配置 Xcode Cloud

Xcode 的 Product 菜单中选择 Xcode Cloud，再点击 Create Workflow
在 Xcode 13 中（满足一些前提条件之后）仅需几步操作即可为你的工程配置 Xcode Cloud。

Xcode Cloud 产品选择页中选中支持 iOS 和 macOS 的 Fruta App
接着，选中接入 Xcode Cloud 的应用（这里以 Fruta 为例），·

Default 工作流预览：main 分支变更触发，使用最新 Xcode，归档 iOS 与 macOS
然后，开始预览一个工作流。工作流最基本的四个要素为：

  • 启动的条件
  • 构建的环境
  • 执行的任务
  • 结束后执行的任务

想要深入了解工作流的编辑过程，请参考 WWDC21 10268 探索 Xcode Cloud 工作流。

Xcode Cloud 请求访问 GitHub 上的 FrutaApp 主仓库与 scripts 仓库
然后需要给 Xcode Cloud 授权以获取 Fruta 源代码。授权范围不光光是代码主仓库，也包括名下的子模块以及私有的 Swift Package。

Fruta App 使用到两个托管于 GitHub 上的私有仓库，所以点击「Grant Access」会跳转到 App Store Connect 网页界面。值得一提的是：这个流程取决于工程代码是如何托管的。Xcode Cloud 要求使用 Git 来管理工程代码，且仅支持以下几种源代码管理提供商：

  • Bitbucket Cloud 和 Bitbucket Server
  • GitHub 和 GitHub 企业版
  • GitLab 和自建版本的 GitLab

Xcode Cloud 也支持 Git 大文件存储（Git LFS）。

整个授权过程将 Apple ID 与源代码管理提供商的账号相关联，并使用源代码管理提供商原生的授权方式与 Xcode Cloud 的安全加密，以确保源代码和用户信息处于保护之下。

FrutaApp 主仓库与 scripts 仓库均已授权 Xcode Cloud 访问
在 App Store Connect 上完成授权后就可以回到 Xcode 本地继续之前的流程。

确认将 Fruta App 与 App Store Connect 中的 Xcode Cloud 构建关联
点击 Complete 按钮，Xcode Cloud 将会帮助开发者把应用信息注册至 App Store Connect。

Fruta 已配置 Xcode Cloud，选择 main 分支并点击 Start Build 开始首次构建
终于到了最后一步！点击 Start Build 按钮，就可以开始第一次构建。

检阅 Xcode Cloud 构建报告

Build 1 总览：iOS 归档完成，macOS 归档因两个问题失败
以 Fruta 这次构建为例：从该构建报告中，我们可以清晰明了地知道构建耗时以及构建环境的配置。点击右上角的 Rebuild 按钮也能帮助我们重新开始构建。

Build 1 的 iOS 归档日志与各构建步骤耗时
Build 1 的 iOS 归档产物列表，包含日志、安装包和 xcarchive
在 Actions 一列中，点击单个 action，可以看到该次 Action 的日志和相应的产物。这样的设计使得整个团队都能很方便地获取到当前 CI 的信息。

macOS 归档失败：UIKit 在 macOS 不可用且找不到 UIKit 模块
喔嚯，在 Build 1 中的「 在 macOS 上归档（Archive）」这一任务失败了！是因为无法在 macOS 上使用 UIKit 框架。我们可以把鼠标移至报错处，点击 ➡️ 小箭头，会直接跳转到对应出错的代码文件。

在 MeasurementView 中用条件编译避免 macOS 构建导入 UIKit
根据之前的报错提示，我们可以快速定位问题。

修复 macOS 导入错误后自动触发 Build 2，Build 1 仍显示失败
在 Git 上推送最新的代码之后，Xcode Cloud 自动触发了新的构建——Build 2。

Xcode Cloud 中的团队协作

当团队中的另一位成员打开 Xcode Cloud 时，他/她也可以看到之前构建失败的 Build 1 和构建成功的 Build 2。

Build 1 和 Build 2 均是名为 Default 的工作流的两次不同的构建。但 Default 这个名字取得不够具体，让我们在它上面点击鼠标右键并在弹出的菜单中选择 Edit Workflow...，来看看是如何简单地编辑一个 Xcode Cloud 工作流吧！

在工作流 General 设置中将名称从 Default 改为 Releases
将工作流的名称从 Default 修改为 Releases 更加符合该工作流的意图。

Releases 工作流触发条件：监听 main 和 release/v1 分支并自动取消旧构建
点选左侧边栏的 Start Condition 就可以开始编辑该工作流的触发条件。
类似地，我们在 Custom Branches 一栏中点击 + 号，添加 release/v1 分支。

Releases 工作流添加必过的 iOS 测试任务，覆盖 iPhone 12 与推荐 iPad
Releases 工作流怎么能少了测试任务呢！点击 Actions 右边的小加号，并在弹出的菜单中选择 Test 即可添加对应的测试任务。

点选左侧边栏的 Environment 就可以开始编辑该工作流的环境配置。其中有一个可勾选的 Clean 选项。一旦勾选，Xcode Cloud 会在每次开始构建时清空 DerivedData 缓存文件夹。更多详细内容，请参考 WWDC21 10268 探索 Xcode Cloud 工作流 [06:02] 处。

由此可见，借助于 Apple 云基础设施的力量，整个团队的协作效能将大大提高。

一点自己的思考

鱼儿游于水，却困于水

Xcode Cloud 在 Apple 生态圈中如鱼得水，然而现实是：公司中往往需要搭建一套通用 CI、CD 流程，把 iOS 与 Android 两端统一管理。在这种情况下，第一顺位可能是社区内容更完善的 Fastlane。Fastlane 对 iOS、Android 和跨平台方案（如 Flutter）均提供不同程度的支持，也能方便地配合 GitLab CI、Jenkins 等一起协同工作。

何…何时能开始使用它呢？

WWDC21 上一公布 Xcode Cloud，我就第一时间申请 beta 版测试资格，到现在过去大半个月了，也没拥有测试资格。利用搜索引擎，我也只发现 @PastePalApp 的作者有收到测试资格，他用简单的图文描述了下 Xcode Cloud 的体验（相关链接）。

Xcode Cloud 应该会是依托于 Apple 基础设施的云服务，回想起国区 iBooks Store、iTunes Store 的昙花一现，Xcode Cloud 会如期而至吗？

“那么，古尔丹，代价是什么呢？”

你以为你的项目会像 Fruta 那样点一点就能很顺利地接入 Xcode Cloud 了吗？你错啦！
接入 Xcode Cloud 的前置条件还不少：

  • 得使用自 Xcode 10 以来的新版构建系统
  • 得使用自动代码签名
  • 得使用符合条件的源代码管理服务
  • ……

更多详情，请参考 Xcode Cloud 的使用要求。

]]>Sunset Wan