coding on liang2kl's Blog

WWDC22 Sessions 记录

liang2kl@outlook.com (Liang Yesheng) — Wed, 08 Jun 2022 22:27:07 +0800

虽然 iOS 16 和 macOS 13 并没有太大的变化，但是 SDK（特别是 SwiftUI）更新的东西相当多，解决了很多以前开发中的痛点。

目录（根据观看时间顺序，大致按照发布顺序）：

Meet Swift Regex
Meet desktop class iPad
The SwiftUI cookbook for navigation
Hello Swift Charts
What’s new in SwiftUI
What’s new in UIKit
Compose custom layouts with SwiftUI
Swift Charts: Raise the bar
Embrace Swift generics
Design protocol interfaces in Swift

Meet Swift Regex

https://developer.apple.com/videos/play/wwdc2022/110357/

Swift 5.7 新增了强类型的正则表达式类型，自动将字符串转化为需要的类型，支持编译器检查。另外还提供了 RegexBuilder 框架，使用 SwiftUI 所使用的 result builder 语法来写正则表达式，非常具有表达力。编译器帮忙检查的 regex 和强类型的 capture 太香了。

Regex literal，强类型静态正则表达式：

// Regex literals
let digits = /\d+/
// digits: Regex<Substring>

Regex Builder，使用 result builder 构建正则表达式：

// CREDIT 03/02/2022 Payroll from employer $200.23
// CREDIT 03/03/2022 Suspect A $2,000,000.00
// DEBIT 03/03/2022 Ted's Pet Rock Sanctuary $2,000,000.00
// DEBIT 03/05/2022 Doug's Dugout Dogs $33.27

import RegexBuilder
let fieldSeparator = /\s{2,}|\t/
let transactionMatcher = Regex {
 Capture { /CREDIT|DEBIT/ }
 fieldSeparator

 Capture { One(.date(.numeric, locale: Locale(identifier: "en_US"), timeZone: .gmt)) }
 fieldSeparator

 Capture {
 OneOrMore {
 NegativeLookahead { fieldSeparator }
 CharacterClass.any
 }
 }
 fieldSeparator
 Capture { One(.localizedCurrency(code: "USD").locale(Locale(identifier: "en_US"))) }
}
// transactionMatcher: Regex<(Substring, Substring, Date, Substring, Decimal)>}

Named captures，给各个 group 起名（返回的结果是一个 Tuple，因此可以在编译期加上标识）：

let regex = #/
 (?<date> \d{2} / \d{2} / \d{4})
 (?<middle> \P{currencySymbol}+)
 (?<currency> \p{currencySymbol})
/#
// Regex<(Substring, date: Substring, middle: Substring, currency: Substring)>

Meet desktop class iPad

https://developer.apple.com/videos/play/wwdc2022/10069/

针对 iPad 生产力问题作的改进，推出了更像 macOS 的 toolbar。不过，这远远不能解决 iPad 缺少足够 productive 的应用的问题。

https://developer.apple.com/videos/play/wwdc2022/10054/

苹果终于改进了 SwiftUI 上视图导航的逻辑。简单来说就是以前只能傻傻地打开另一个视图而无法获取之前的视图的情况，现在可以获取并可以用程序控制当前所在的层级了。

官方的示例代码：

import SwiftUI

// Pushable stack
struct PushableStack: View {
 @State private var path: [Recipe] = []
 @StateObject private var dataModel = DataModel()

 var body: some View {
 NavigationStack(path: $path) {
 List(Category.allCases) { category in
 Section(category.localizedName) {
 ForEach(dataModel.recipes(in: category)) { recipe in
 NavigationLink(recipe.name, value: recipe)
 }
 }
 }
 .navigationTitle("Categories")
 .navigationDestination(for: Recipe.self) { recipe in
 RecipeDetail(recipe: recipe)
 }
 }
 .environmentObject(dataModel)
 }
}

相比于之前 NavigationLink 提供一个 View，现在可以提供一个用于区分不同目标的值来代替（这样就可以记录栈上的内容）：

NavigationLink(recipe.name, value: recipe)

然后，使用 navigationDestination() 来返回对应的 View：

.navigationDestination(for: Recipe.self) { recipe in
 RecipeDetail(recipe: recipe)
}

使用新的 NavigationStack，我们传递一个 path 来获取当前导航栈上的所有 destination 所对应的值：

NavigationStack(path: $path)

这样，我们可以通过更改 path 来随意更改导航栈：

path.removeAll()

另外，还可以通过 SceneStorage 持久化当前的状态。

Hello Swift Charts

https://developer.apple.com/videos/play/wwdc2022/10136/

官方的图表框架，使用 SwiftUI 快速构建图表，非常简洁。比如，创建折线图：

Chart(partyTasksRemaining) { element in
 LineMark(
 x: .value("Date", element.date, unit: .day),
 y: .value("Tasks Remaining", element.remainingCount)
 )
 .foregroundStyle(by: .value("Category", element.category))
 .symbol(by: .value("Category", element.category))
}

最后效果很不错（也很苹果）：

声明式语法真是太适合做图表了，matplotlib 虽然强大但是画个图挺麻烦的，在想着以后科研能不能用 Swift 画图（

What’s new in SwiftUI

https://developer.apple.com/videos/play/wwdc2022/10052/

除了上面提到的 Swift Charts 和 navigation 之外，这次 SwiftUI 的主要更新还有：

macOS 可以创建单独的、可以控制显示/关闭的窗口了：

@main
struct PartyPlanner: App {
 var body: some Scene {
 WindowGroup("Party Planner") {
 PartyPlannerHome()
 }

 Window("Party Budget", id: "budget") {
 Text("Budget View")
 }
 .keyboardShortcut("0")
 }
}

另外，终于支持状态栏 app 了：

@main
struct PartyPlanner: App {
 var body: some Scene {
 MenuBarExtra("Bulletin Board", systemImage: "quote.bubble") {
 BulletinBoard()
 }
 .menuBarExtraStyle(.window)
 }
}

Resizable sheets

加入了去年 UIKit 新增的可变高度的 sheet：

.sheet(isPresented: $presented) {
 Text("Budget View")
 .presentationDetents([.height(250), .medium])
 .presentationDragIndicator(.visible)
}

其他

其他的更新包括：

macOS 上 Form 新的外观
支持多行的 TextField 和限定行高范围
iPad 支持 Table
可自定义的 toolbar
可自定义的 layout

What’s new in UIKit

https://developer.apple.com/videos/play/wwdc2022/10068/

现在基本不写 UIKit 了，这部分就没怎么记录。比较有意思的是，现在创建 UICollectionView 和 UITableView 可以用 SwiftUI 来写 cell 的 UI 了：

cell.contentConfiguration = UIHostingConfiguration {
 VStack {
 Image(systemName: "wand.and.stars")
 .font(.title)
 Text("Like magic!")
 .font(.title2).bold()
 }
 .foregroundStyle(Color.purple)
}

其他的更新，如新的 toolbar，到暑假可以用来改进一下 Whiz Reader（不过可能用 SwiftUI 重写而不是继续用 UIKit）。

Compose custom layouts with SwiftUI

https://developer.apple.com/videos/play/wwdc2022/10056/

支持自定义布局应该是本次 SwiftUI 最重要的更新了。现在我们可以访问到一些以前获取不到的信息来放置子视图了。

Grid

在介绍自定义布局之前，首先介绍了新增的 Grid 类型，可以构建静态的对齐与网格的布局。

与之前的 LazyHGrid 和 LazyVGrid 不同，Grid 不是懒加载的，因此高/宽是确定的，适合于静态 grid 的构建。

与 VStack 和 HStack 的组合相比，Grid 的各行/列可以自动根据最大元素调整大小，而 VStack 和 HStack 不行。比如，现在可以实现这样一个列表：

左侧的名称一栏自动将宽度调整到适合于最大的 Goldfish，右侧同理。

在以前，使用 VStack 和 HStack 想要实现各列大小一致，只能给各列指定固定的大小。比如，树洞的评论界面大概是这样实现的：
VStack {
 ForEach(comments) { comment in
 HStack {
 Text(comment.name)
 .fixedSize(.horizontal, 20)
 Text(comment.content)
 }
 }
}
当 comment.name 过长时，就会变成两行，非常影响体验。

自定义布局

自定义布局对应一个新的协议：Layout。

Layout 通过两个函数参与布局过程：

func sizeThatFits(
 proposal: ProposedViewSize,
 subviews: Subviews,
 cache: inout Void
) -> CGSize

func placeSubviews(
 in bounds: CGRect,
 proposal: ProposedViewSize,
 subviews: Subviews,
 cache: inout Void
)

第一个函数 sizeThatFits() 通过返回一个大小来告诉父 View 我们需要多少空间；第二个函数 placeSubviews() 将所有的子 View 放置在合适的位置（使用我们在 sizeThatFits 中要求的空间）。

sizeThatFits

我们先来看 sizeThatFits()。它有三个参数：

proposal：父 View 所期望这个布局的大小。我们（可以）根据 proposal 的大小来决定我们最终要占据多少空间，当然也可以忽略
subviews：布局中所有的子 View。这并不是 View 本身，而是它的“代理”（proxy），仅给我们提供必要的信息和接口
cache：可用来缓存中间计算结果

关于 proposal，官方文档是这样介绍的：

A proposed size for the subview. In SwiftUI, views choose their own size, but can take a size proposal from their parent view into account when doing so.

可以看到，proposal 是父视图对子视图大小的“建议”。父视图在进行布局时，将建议的大小传入每个子视图，子视图经过计算返回最终的大小（可以是 proposal 的大小，也可以不是），父视图最终根据子视图返回的大小来进行布局的计算（而不是它所认为的大小，即 proposal）。

我们以官方的例子为例。这个例子实现了一个 EqualWidthHStack，有几个需求：

水平布局
每个子 View 大小相同
每个子 View 的大小都等于最大的子 View

对于这个 layout，sizeThatFits() 如下：

原理很简单：计算子 View 的最大的 size，加上之间的 spacing，即是布局需要的大小。我们通过 LayoutSubview 的 sizeThatFits() 获取每个子 View 的大小，然后计算最大值：

private func maxSize(subviews: Subviews) -> CGSize {
 let subviewSizes = subviews.map { $0.sizeThatFits(.unspecified) }
 let maxSize: CGSize = subviewSizes.reduce(.zero) { currentMax, subviewSize in
 CGSize(
 width: max(currentMax.width, subviewSize.width),
 height: max(currentMax.height, subviewSize.height))
 }

 return maxSize
}

在 sizeThatFits() 中，我们忽略了 proposal，这样在父视图的任何大小下这个布局所占的空间都是一样的。如果需要更灵活的布局，如空间不足时自动缩小，可以根据不同的 proposal 返回不同的大小。

placeSubviews

placeSubviews() 相较于 sizeThatFits() 多了一个参数 bounds，其余参数均相同；我们通过调用 LayoutSubview 的方法来放置子视图。其实完全可以理解为两个函数是同一个函数的两个部分，sizeThatFits() 用于计算视图大小，placeSubviews() 用我们计算好的大小来放置视图；只是因为上层调用是两个不连续的过程，才将它们分开为两个函数。

因此，这两个函数一般具有部分相同的逻辑，比如上面的 maxSize() 和 spacing()，最好将其写到一个新的函数中以便复用，或者直接将中间结果放到 cache 中（待考证）。

实现 EqualWidthHStack 的 placeSubviews() 很简单，我们只需要通过相同的方法计算 maxSize 和 spacing，然后将每个 subView 放置在合适的位置就可以了。这个过程通过 LayoutSubView 的 place() 方法完成。

传递额外信息

这种方式有一个问题：传入的 subviews 只是视图的代理，不带有视图的信息。如果我们需要传递子视图的额外信息用于布局的计算，官方提供了一种（强类型的）方式：

struct Rank: LayoutValueKey {
 static let defaultValue: Int = 1
}

MyLayout(1...10) { rank in
 Text("\(rank)")
 .layoutValue(key: Rank.self, value: rank)
}

使用下标运算符，我们可以从 subview 中获取对应的值：

let ranks = subviews.map { subview in
 subview[Rank.self]
}

这样就实现了额外信息的传递。

自适应布局

有意思的是，官方还实现了一个能够根据可用空间的大小自动调整布局的布局 ViewThatFits：

ViewThatFits {
 EqualWidthHStack {
 Buttons(...)
 }
 VStack {
 Buttons(...)
 }
}

当空间足够时，选择第一个 EqualWidthHStack；空间不够时，选择所需空间更少的 VStack。

其实这个非常 fancy 的布局的实现应该很简单：根据 EqualWidthHStack 和 VStack 的 sizeThatFits() 的返回值，按顺序选择能够在可用空间内放置的一个。当然，我们没办法在自定义排布中选择哪些子视图不显示，因此是没办法完美地手动实现一个类似的容器的（可以通过不给子视图分配空间来实现，不过这样子视图仍然会加载）。

AnyLayout

最后，官方提供了一个 type-erased 的 Layout，即 AnyLayout，可以用于动态改变布局类型：

let layout = isThreeWayTie ? AnyLayout(HStack())
 : AnyLayout(MyRadialLayout())

layout {
 ForEach(pets) { pet in
 Avatar(pet: pet)
 }
}
.animation(...)

另外，由于 layout 中的 View（在这里是若干个 Avatar）在不同的布局下具有相同的 view identity，因此布局变化前后子视图是不变的。通过这一点，我们甚至可以为不同布局的变化加上动画。

Swift Charts: Raise the bar

https://developer.apple.com/videos/play/wwdc2022/10137/

Swift Charts 框架的进阶介绍，主要介绍了一些自定义方法。

增加标注：

指定图表颜色：

自定义刻度：

自定义图表区域：

在图表上添加一层 overlay，可用于交互：

Embrace Swift generics

https://developer.apple.com/videos/play/wwdc2022/110352/

介绍了 Swift 范型的更新，主要针对 protocol。

protocol Animal {
 associatedtype Feed: AnimalFeed
 func eat(_ feed: Feed)
}

struct Farm {
 func feed(_ animal: some Animal) {
 let crop = type(of: animal).Feed.grow()
 let produce = crop.harvest()
 animal.eat(produce)
 }
 func feedAll(_ animals: [any Animal]) {
 for animal in animals {
 feed(animal)
 }
 }
}

上面的代码中有几个关键点：

协议限制在 Swift 5.7 中可以用 opaque type，即 some 关键字表示
可以用 type(of:) 来获取确定的具体类型
在 Swift 5.7 中可使用 any 实现针对 protocol 的类型消除（type erasure）

any 非常实用。之前，数组只能储存同一具体类型的数据，不能储存遵循相同协议而类型不同的数据（主要原因应该是内存大小不同）；在 Swift 5.7 中，使用 any 可以储存遵循某协议的任意类型的数据。现在，数组就不一定直接储存对象本身了。如果对象大小合适（这里不太清楚“合适”的含义，估计是指针大小以内？），可以直接存到数组里，否则存在外面：

这种方式有点像存了一堆指针，但是又不完全是（较小的对象可以直接放在数组内），可能是为了减少虚函数查表的开销？

另外，any 类型可以用于 some，具体类型的获取在运行时完成。这种转换叫做“opening boxes”，即“打开盒子看究竟是什么动物”：

最后，官方建议：

Write some by default

道理很简单，直接调用带 some 参数的函数实际上在编译期是确定了类型的，而 any 在编译期去掉了具体类型的信息，在运行期才能确定，相比之下效率较低。

Design protocol interfaces in Swift

https://developer.apple.com/videos/play/wwdc2022/110353/

在上面 Embrace Swift generics 的基础上，进一步介绍使用新的语言特性设计协议。

Type erasure

和上面类似的例子。当我们使用类型消除时，所有类型变成“上界”（不太明白这个名词的意思…），与之相关的所有泛型都变成对应的上界。

比如，any Animal 调用 produce() 的结果类型为 any Food：

但是，反过来，不能够将某一个符合 associatedtype 的类型作为参数传入一个上界类型的函数中。

比如，Crop() 不能作为 any Animal 的 eat() 的参数：

这里的关键在于，一个具体类型总是可以安全地转换为 any，而 any 不能反过来安全地转换为某一个具体的类型。

Hide implementation details

有时候，我们不希望暴露太多实现细节，比如下面的这个例子：

我们希望使用 LazyFilterSequence 来提高性能，然而并不希望将这个信息暴露在 API 中。Swift 为了解决这个问题，增加了一个叫做 primary associated types 的语法：

Primary associated types 大致的意思是，将 protocol 中与实现细节相关的 associatedtype 使用尖括号暴露出来，从而能够使用 some 或者 any 来表示满足这个 associatedtype 要求的类型。

比如，标准库中的 Collection：

protocol Collection<Element>: Sequence {
 associatedtype Element
}

关于 `type(of:)`

看完视频最主要的疑问是：type(of:) 究竟是完全由运行时决定的，还是有编译器参与的。比如上面的例子：

protocol Animal {
 associatedtype Feed: AnimalFeed
 func eat(_ feed: Feed)
}

func feed(_ animal: some Animal) {
 let crop = type(of: animal).Feed.grow()
 let produce = crop.harvest()
 animal.eat(produce)
}

编译器知道 some Animal 是一个具体的、遵循 Animal 的类型（包括运行时才能确定类型的 any Animal），因此可以确定 type(of: animal).Feed 的类型就是具体类型的 Feed，上面的代码得以通过编译。

但是，脱离了 some 的语境，any 就没有这种机制了：

let animal: any Animal = Cow()
let crop = type(of: animal).Feed.grow()
// error: type of expression is ambiguous without more context
// let crop = type(of: animal).Feed.grow()
// ~~~~~~~~~~~~~~~~~^^^^~~~~~~~

编译器实际上通过 some 给 any 提供了便利，即虽然不能在编译期知道具体的类型，但是可以保证 associatedtype 的正确性，这也是上面所说的“Open boxing”实现的效果。要想利用这种便利，我们需要使用带有 some 参数的函数。

协程上下文切换

liang2kl@outlook.com (Liang Yesheng) — Thu, 26 May 2022 13:02:01 +0800

最近在研究 Arachne 做用户态线程调度的方法。

众所周知，一个线程的状态包括：

PC
一些寄存器（即“上下文”）

切换线程时，需要切换上下文；为了将来能够恢复上下文，在切换时我们需要将当前的上下文保存在某个地方。我们尝试用 C 写一个简单的上下文切换。

上下文切换

进行上下文切换的汇编代码在上汇编课时就讲过：

swapcontext:
# save current context
pushq %r12
pushq %r13
pushq %r14
pushq %r15
pushq %rbx
pushq %rbp
movq %rsp, (%rsi)
# restore previously saved context
movq (%rdi), %rsp
popq %rbp
popq %rbx
popq %r15
popq %r14
popq %r13
popq %r12

上面的代码做了几件事情：

保存当前上下文
1. 将被调用者保存寄存器保存到当前的调用栈上
2. 将当前的栈指针 %rsp 保存到 %rsi 所指向的内存地址上
恢复之前保存的上下文
1. 将栈指针恢复为 %rdi 所保存的另一个协程的栈顶
2. 恢复另一个协程的栈上面保存的被调用者保存寄存器

这里需要理解一个问题：为什么需要保存被调用者保存寄存器？

“被调用者保存寄存器”指的是在调用子过程前后不发生改变的寄存器，即子过程需要在返回前将这些寄存器的值恢复。上面的 swapcontext 是一个过程调用，因此需要遵循这一惯例。然而，与一般的过程调用不同，我们在这里实际上是切换到了另一个上下文中，因此我们实际上是恢复了另一个协程的上下文。

这里可能会产生疑惑：调用者保存寄存器呢？实际上，调用 swapcontext 的过程在调用它之前就已经把调用者保存寄存器保存好了（如果有必要的话）。理解的关键是：swapcontext 是一个过程，而不是内联的汇编代码。

调用栈结构

由于 swapcontext 中会将当前的上下文保存到某个内存地址，我们之后只需要将这个内存地址传入 swapcontext 就可以切换回来了。在这里，我们主要考虑在一开始如何切换到一个指定的函数上；我们需要初始化调用栈，使得 swapcontext 后能够跳转到指定的函数。

不难画出这样的一个调用栈：

 +-----------------------+
 | |
 +-----------------------+
 | Return Address |
 +-----------------------+
 | |
 | Registers |
sp-> | |
 +-----------------------+
 | |
 | |

我们将需要切换到的函数的地址保存在 Return Address 中。在使用 popq 指令恢复所有保存的寄存器后，rsp 指向此函数地址，swapcontext 返回（ret 指令）后便跳转到函数的入口地址。需要注意的是 Return Address 上方需要保留 8 字节的空间。

栈的初始化过程如下：

#define SPACE_FOR_SAVED_REGISTERS 48UL
#define STACK_SIZE 1024UL

void routine2() {
 // ...
}

void *sp2;
char stack[8 + SPACE_FOR_SAVED_REGISTERS + STACK_SIZE];

int main() {
 // Initialize stack for routine2
 sp2 = stack + SPACE_FOR_SAVED_REGISTERS + STACK_SIZE - 2 * sizeof(void *);

 // Set return address
 *(void **)sp2 = routine2;

 // Point to bottom of the register stack
 sp2 = (char *)sp2 - SPACE_FOR_SAVED_REGISTERS;

 //...
}

在这里，我们创建一个栈，并将 routine2 的地址写到相应位置；sp2 指向最后一个储存寄存器值的位置。

此时，stack、sp2 和调用栈的结构如下：

 +-----------------------+
 | |
 +-----------------------+
 | Address of `routine2` |
 +-----------------------+
 | |
 | Registers |
sp2-> | |
 +-----------------------+
 | |
 | |
 | Stack Space |
 | |
stack-> | |
 +-----------------------+

程序

最后，我们写几个简单的上下文切换的 demo。

例子 #1

在这里，我们进行两次上下文切换，从 routine 切换到 routine2，再切换回 routine。

其中，swapcontext 需要加上 noinline 的 attribute，这是为了保证 swapcontext 作为过程被调用。

另外，编译时需要加上 -fomit-frame-pointer，否则编译器在编译时会在过程前后分别加上 pushq %rbp 和 popq %rbp，导致栈结构遭到破坏。

#include <stdio.h>

#define SPACE_FOR_SAVED_REGISTERS 48UL
#define STACK_SIZE 1024UL

void __attribute__((noinline)) swapcontext(void** saved, void** target) {
 asm("pushq %r12\n\t"
 "pushq %r13\n\t"
 "pushq %r14\n\t"
 "pushq %r15\n\t"
 "pushq %rbx\n\t"
 "pushq %rbp\n\t"
 "movq %rsp, (%rsi)");

 asm("movq (%rdi), %rsp\n\t"
 "popq %rbp\n\t"
 "popq %rbx\n\t"
 "popq %r15\n\t"
 "popq %r14\n\t"
 "popq %r13\n\t"
 "popq %r12");
}

void *sp2;
void *sp;
char stack[8 + SPACE_FOR_SAVED_REGISTERS + STACK_SIZE];

void routine() {
 printf("routine()\n");
 // Switch to routine2
 swapcontext(&sp2, &sp);
 printf("routine() end\n");
}

void routine2() {
 printf("routine2()\n");
 // Switch back
 swapcontext(&sp, &sp2);
 // Unreachable
 printf("routine2() end\n");
}

int main() {
 // Initialize stack for routine2
 sp2 = stack + SPACE_FOR_SAVED_REGISTERS + STACK_SIZE - 2 * sizeof(void *);

 // Set return address
 *(void **)sp2 = routine2;

 // Point to bottom of the register stack
 sp2 = (char *)sp2 - SPACE_FOR_SAVED_REGISTERS;

 routine();

 printf("main routine\n");
 return 0;
}

输出如下：

routine()
routine2()
routine() end
main routine

例子 #2

继续尝试一些其他的用法。在这里，我们计算 0 累加至 9 的结果，并在每次循环时都切换一次上下文，然后立刻切换回来。

void routine() {
 printf("routine()\n");
 int sum = 0;

 for (int i = 0; i < 10; i++) {
 sum += i;
 swapcontext(&sp2, &sp);
 }

 printf("sum: %d\n", sum);
}

void routine2() {
 for (;;) {
 printf("routine2()\n");
 swapcontext(&sp, &sp2);
 }
}

输出为：

routine()
routine2()
routine2()
routine2()
routine2()
routine2()
routine2()
routine2()
routine2()
routine2()
routine2()
sum: 45

汇编结果

使用 -O1 编译上面第二个例子（去掉所有 printf），routine 的汇编代码如下：

0000000000000639 <routine>:
639: 55 push %rbp
63a: 53 push %rbx
63b: bb 0a 00 00 00 mov $0xa,%ebx
640: 48 8d 2d f9 09 20 00 lea 0x2009f9(%rip),%rbp # 201040 <sp>
647: 48 89 ee mov %rbp,%rsi
64a: 48 8d 3d 47 0e 20 00 lea 0x200e47(%rip),%rdi # 201498 <sp2>
651: e8 af ff ff ff callq 605 <swapcontext>
656: 83 eb 01 sub $0x1,%ebx
659: 75 ec jne 647 <routine+0xe>
65b: 5b pop %rbx
65c: 5d pop %rbp
65d: c3 retq

可以看到，for 循环使用 %ebx（被调用者保存）进行计数，在调用 swapcontext 前后并没有保存其值。保存这个寄存器是 swapcontext 的责任。

Jinja 继承、函数和块

liang2kl@outlook.com (Liang Yesheng) — Fri, 24 Sep 2021 00:00:00 +0800

最近在为 mkdocs-blogging-plugin 添加自定义的功能，因为本来就是用 Jinja 的 HTML 模版来生成 HTML，所以也想用 Jinja 给用户提供自定义的接口。

大概的要求有：

提供自定义单个 post 而保留大体框架的方法
提供自定义 style sheet 的方法
提供整体重写的方法

这篇文章只会覆盖到部分。

继承：`extends`

Jinja 给我们提供了一种类似于继承的方法，可以在保留原来模版所有内容的情况下增加、重写部分内容的方法。

在“子模版”中，通过 extends 引用“父模版”：

{% extends "blog.html" %}

如果只有这一句，相当于将原来 blog.html 中所有内容原封不动地搬到新的模版中。至于增加和重写内容，稍后再谈。

函数：`macro`

在用户提供的覆写模版中，我们需要用户向父模版提供一个“函数”，用来生成单个博客的内容。

Jinja 中的“函数”叫做 macro，通过这样的方法定义：

{% macro render_blog(title, description, time, url) -%}
 {# content #}
{%- endmacro %}

以及，这样调用：

{% call render_blog(title, description, time, url) %}
 {# caller_content #}
{% endcall %}

在 call 调用 macro 后，将整个 call 块替换为 macro 块里面的所有内容 {# content #}，与 C 中的宏定义一致（这应该也是为什么叫做 macro 的原因）。

另外，macro 有一个隐含参数 caller，其作用是返回 call 块中间的内容 {# caller_content #}，如：

macro：

{% macro foo(name) -%}
 <div>{{ name + " says: " + caller() }}</div>
{%- endmacro %}

call：

{% call foo("liang2kl") %}
 Hello, World!
{% endcall %}

call 的结果为：

<div>liang2kl says: Hello, World!</div>

值得注意的是，如果不想传递 caller 中的内容，也需要在 macro 中调用 caller()，否则会报错：

TypeError: macro ‘foo’ was invoked with two values for the special caller argument. This is most likely a bug.

现在，我们只需要用户提供一个产生博客内容的 macro 给我们的父模版就可以了。

重写：`block`

Jinja 的继承机制允许我们在“子模版”中选择性地重写部分内容，而保持其他部分不变。实现的机制是 block。

在父模版中，我们用 block 块划出允许重写的部分。如：

{% block style %}
<style>
 ...
</style>
{% endblock %}

在子模版中，重写：

{% block style %}
 ...
{% endblock %}

即可将父模版中的 style 块替换为新的块。

另外，可以用 super() 保留原来内容：

{% block style %}
 {{ super() }}
 ...
{% endblock %}

放在一起

将上面几个功能放在一起，我们给用户提供这样的自定义方式：

{% macro render_blog(title, description, time, url) -%}
 <a href="{{ url }}"><h3>{{ title }}</h3></a>
 <div>{{ description }}</div>
 <div>{{ time }}</div>
 <hr/>
 {{ caller() }}
{%- endmacro %}

{% extends "blog.html" %}

{% block style %}
 .md-typeset .blog-post-title {
 color: blue;
 }
{% endblock %}

其作用：

在引入 blog.html 之前，定义 render_blog 的 macro，以便在 blog.html 中调用
引入 blog.html
通过 block 修改 blog.html 的 style 块

做一个 MkDocs 博客插件

liang2kl@outlook.com (Liang Yesheng) — Thu, 09 Sep 2021 00:00:00 +0800

MkDocs 是个好东西，非常适合用来写一些 tech 文章；而 MkDocs 的 Material 主题更是 geek 风格十足。第一次看到 Material for MkDocs，就一见钟情，马上搭了个博客网站。

但是，仔细一看 Material for MkDocs 的介绍，感觉不太对劲：

Technical documentation that just works

Create a branded static site from a set of Markdown files to host the documentation of your Open Source or commercial project…

MkDocs 本来就只是为了搭建项目文档网站设计的，很多功能和设计（如底部导航栏、侧边栏等）更适合文档，而非博客。这导致，MkDocs 并没有将所有文章列在一个地方的功能。没有博客界面，怎么能叫做一个博客呢……

但是，实在舍不得这么好看的界面，就琢磨着自己魔改一番。正好小学期学了 Python，可以用来练练手。

最终成果开源于 mkdocs-blogging-plugin

MkDocs 的插件是怎么工作的

仔细读了读开发者文档，MkDocs 插件的工作是在 MkDocs 处理文档的整个生命周期的不同阶段拦截当前结果，并返回处理后的结果。比如，对生成的 html 进行修改，是在插件类的 on_page_content 函数中实现的：

on_page_content

The page_content event is called after the Markdown text is rendered to HTML (but before being passed to a template) and can be used to alter the HTML body of the page.

Parameters:

html: HTML rendered from Markdown source as string

page: mkdocs.nav.Page instance

config: global configuration object

files: global files collection

Returns: HTML rendered from Markdown source as string

我们从函数参数中读取当前处理中的 html 字符串，在对其进行处理后，返回最终的 html 字符串，就完成了插件对页面内容的修改。

实现这些函数，我们就可以读取需要的信息，并更改某些页面内容。

设计与实现

首先，考虑把博客内容加入什么地方。考虑到用户可能需要在博客列表的前后加上其他的信息，直接生成一个页面不太可行。参考 mkdocs-git-revision-date-localized-plugin 的做法，让用户在需要添加博客内容的地方加上一个指定的占位符 {{ blog_content }}，然后在处理时用正则表达式替换即可。

然后，考虑博客的排序。我们选择使用 git log 来获取博文的创建和更新时间，然后向用户提供配置的选项（从新到旧 + 根据创建时间 / 从旧到新 + 根据修改时间等）。这部分代码可以直接抄 mkdocs-git-revision-date-localized-plugin 的实现，工作量–。

插件类与用户配置

根据文档，插件类需要继承 BasePlugin。在 BasePlugin 中，config_scheme 为插件的可配置选项。比如，我们需要用户设置一个名叫 foo 的参数，其类型为 str：

class BloggingPlugin(BasePlugin):
 config_scheme = (
 ("foo", config_options.Type(str, default=None)),
 )

这样，用户在 mkdocs.yml 中，可以这样配置 foo（假设我们的插件名为 blogging）：

plugins:
 - blogging:
 foo: bar

获取博客文件

我们需要给予用户自行设置哪些文件夹、哪些文件的途径。在 config_scheme 中，加上一项 dirs：

config_scheme = (
 ("dirs", config_options.Type(list, default=None)),
)

然后，在 on_page_content 函数中，如果 page 是在用户设置的 dirs 里面，就将其储存下来：

def on_post_page(self, output, page, config):
 for dir in self.docs_dirs:
 if page.file.src_path[:len(dir)] == dir:
 self.blog_pages.append(page)

另外，有些文章在 dirs 中，但可能并不希望被包括进博客中（如一些 index page）。对于这些文件，我们要求用户在 markdown 的 meta 中加入一项 exclude_from_blog：

---
exclude_from_blog: true
---

然后，修改一下上面的判断条件：

if page.file.src_path[:len(dir)] == dir \
 and (not "exclude_from_blog" in page.meta \
 or not page.meta["exclude_from_blog"]):

就可以实现页面的筛选。

页面生成

我们需要生成博客的列表界面，最简单的办法就是用 html 模版引擎来为我们动态地生成静态页面，这里使用 MkDocs 使用的 jinja2 来处理。

生成博客列表不是难事，写一个 for 循环就可以了：

{% for page in pages %}
 <div>...</div>
{% endfor %}

比较棘手的是分页的处理。根据我们的设计，我们最终在一个页面中插入博客内容，但是分页一般是多个页面。

最终采取了将所有博客信息塞入页面、使用 css 现实当前页面博客信息 / 隐藏其他页面的方法：

首先，在 pagination 中，将地址设置为 #page{{当前页面}}：

<a href="#page{{ page_idx + 1 }}">{{ page_idx + 1 }}</a>

在 css 中，id 与 # 后面字符相同的可以用 :target 选择器选中。比如，当前页面是 /blog/#page1，那么 :target 选中的就是 id = "page1" 的元素。我们只需要将 :target 设为显示，其他设为隐藏就可以了。

在 html 中：

<div class="pages">
 {% for page_idx in range(0, page_num) %}
 <div class="page" id="page{{ page_idx + 1 }}">
 <!-- 第 page_index + 1 页的内容 -->
 </div>
 {% endfor %}
</div>

在 css 中：

/* 将所有子元素隐藏 */
.pages > * {
 display: none;
}

/* 显示 :target */
.pages > :target {
 display: block;
}

由于 css 处于后面的声明会覆盖前面的声明，:target 可以显示，而其他页面的元素将被隐藏。这样就实现了分页。

另外，我们还需要 JavaScript 来处理 pagination 的高亮，在这里就不赘述了。

这种解决方法其实有个问题：当我们点击链接跳转到 #pageX 的时候，浏览器会自动跳转到 id = pageX 的元素处，非常影响体验。如今已经抛弃这种方法，改为在 JavaScript 中利用点击事件获取页面、更改 page 的 class 来实现页面的显示和隐藏。

页面插入

在插件的 on_post_page 函数中，将原来文件中的 {{ placeholder }} 替换为用 jinja 生成的 html 字符串：

def on_post_page(self, output, page, config):
 additional_html = self.template.render(pages=self.blog_pages, ...)

 output = re.sub(
 r"\{\{\s*blog_content\s*\}\}",
 additional_html,
 output,
 flags=re.IGNORECASE,
 )

 return output

就基本上完成了所有的工作。

总结

上面所述的仅仅是插件开发中一些枝干的问题，实际上，做一个工程，而不仅是自己用的小软件，要考虑的问题远不止于怎么实现功能，不仅要尽可能满足用户的需求，还要处理各种 corner cases（~~测试工程师进酒吧~~）。当然，造轮子虽然难，但是其中的快乐是无穷的。

用 Property Wrapper 包装网络请求参数

liang2kl@outlook.com (Liang Yesheng) — Sat, 28 Aug 2021 00:00:00 +0800

偶然看到 Java 语言 Retrofit 库的文档，对这种标注 HTTP 请求参数的方式十分感兴趣（其实我也没学过 Java）：

@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

联想一下以前用 Swift 写的网络请求（参考协议 + 泛型：威力巨大的组合），都需要手动赋值参数，实在是不太优雅：

let headers: HTTPHeaders = [
 "TOKEN": self.configuration.token,
 "Accept": "application/json"
]

let parameters: [String : Encodable] = [
 "pid" : self.configuration.postId,
 "switch": self.configuration.switchToAttention ? 1 : 0,
]

Java 的这种语法与 Swift 的 Property Wrapper 很像（实践证明 Swift 这个语法局限性还是挺大的），~~而且逼格也非常高~~ ，恰好也一直想自己写个 Property Wrapper 玩一玩研究一下，于是就动手写一个包装网络请求参数的库。

理想效果

理想中，对参数的包装应该达到的效果有：

用 Property Wrapper 包装实际的参数值和对应的 key

struct SomeRequest: Request {
 @Header("TOKEN") var accessToken
 @Field("page") var page: Int
 @Field("foo") var bar: String
 ...
}

能够自动找到所有的参数，并将其放入 HTTP 请求中

目标有了，就开始写吧！

设计与实现

包装参数

我们的 Property Wrapper 中需要 key 和 value。尝试写一下 @Query：

@propertyWrapper
struct Query<Value: Encodable> {
 var key: String
 var wrappedValue: Value

 init(wrappedValue: Value, _ key: String) {
 self.key = key
 self.wrappedValue = wrappedValue
 }
}

@Query 接受 String 作为 key，和一个遵循 Encodable 协议的值作为 value。

可是，当我们尝试使用这个 Property Wrapper 的时候，却出现了问题：

@Query("foo") var bar: Int

这样写会出现编译错误：

Missing argument for parameter 'wrappedValue' in call

原因在于，@Query("foo") var bar: Int 的声明其实是在调用 Query<Int> 的 init(wrappedValue: Value, _ key: String)，而 Swift 不允许存在未初始化的成员变量，所以必须同时初始化 key 和 wrappedValue：

@Query("foo") var bar: Int = 1

但是，总不能要求调用者每种类型都给出个默认值……这样实在是太丑陋了，也不符合语义—— @Query("foo") 声明 key，value 应该是之后赋值的。而且也不现实，如果 wrappedValue 是一个自定义类型的话，提供默认值是一件匪夷所思的事情。

没办法，Property Wrapper 括号中的参数并不是严格意义上静态的 attribute，而是一个函数的参数，是一个变量，这本来就是和我们的需求相背的。

那么，退而求其次，既然不能要求提供默认值，那我们可以用一种不会产生歧义的、带有默认初始化方法的变量—— Optional：

@propertyWrapper
struct Query<Value: Encodable> {
 var key: String
 var wrappedValue: Value?

 init(wrappedValue: Value?, _ key: String) {
 self.key = key
 self.wrappedValue = wrappedValue
 }
}

这样一来，参数的声明就可以稍微合理一点了：

@Query("foo") var bar: Int? = nil

虽然我们还是要提供一个初始值，但是 nil 在这里刚好可以表达“未初始化”的意思，在以后解析所有参数的时候，如果这个值没有被设定，我们直接跳过这个请求参数就好了。

到这里，自然会想到在 init 中给 wrappedValue 设定 nil 的默认值，使得我们不需要手动写 = nil：

init(wrappedValue: Value? = nil, _ key: String)

这似乎解决了问题，我们可以这样写了：

@Query("foo") var bar: Int?

但是又多了一个问题：我们不能直接用 wrappedValue 初始化含有 @Query 变量的类型了，如：

struct Foo {
 @Query("foo") var bar: Int?
}

// let foo = Foo(bar: 1)
// Cannot convert value of type 'Int' to expected argument type 'Query<Int>'

用一个例子测试一下 Property Wrapper 初始化的原理：
struct A<Value: Encodable> {
 var key: String
 private var value: Value?
 public var wrappedValue: Value? {
 get { value }
 set { value = newValue; print(newValue) }
 }

 public init(wrappedValue: Value?, _ key: String) {
 self.key = key
 self.value = wrappedValue
 print("Initializing with wrappedValue \(wrappedValue), key \(key)")
 }
}

struct Test {
 @A("hello") var a: Int? = nil
}

let foo = Test()
let bar = Test(a: 1)
输出为：
Initializing with wrappedValue nil, key hello
Initializing with wrappedValue Optional(1), key hello
原来 @A 变量在 Test 的构造函数中无论是否赋值，都只会调用一次 @A 的 init。当我们不指定 a 的值的时候，使用我们提供的默认值 nil 进行初始化；当我们指定 a 的值的时候，使用我们指定的值。

所以，@Query("foo") var bar: Int? = nil 中 = nil 其实就相当于 init 的一个默认参数。这也解释了为何我们直接在 init 中设参数默认值使得无法用 wrappedValue 初始化。

所以，还是手动把 = nil 加上为妙。

获取信息

包装好了，怎么获取这些变量是另一个大问题。要知道，我们根本不知道传进来的对象是什么。例如，我们的 SomeRequest 中有这些参数：

struct SomeRequest {
 @Query("page") var page
 @Query("bar") var foo: Int? = nil
}

我们当然不知道 SomeRequest 中有 page 和 foo 两个成员。

幸好，我们有 Mirror ——利用对象的元数据，能够向我们提供对象成员变量的信息。¹

用 Mirror 尝试一下：

let mirror = Mirror(reflecting: request) // request is `SomeRequest`
for (_, property) in mirror.children {
 // property 是 request 的成员变量
}

我们可以通过这种方法访问 request 对象的所有成员变量。接下来的问题是，我们怎么识别是不是 @Query，以及怎么把 Query 里面的 key 和 wrappedValue 取出来。

一种很朴素，又很错误的想法是这样：

if let property = property as? Query {
 ...
}

这样当然通过不了编译，Query 只是个模版，不是具体的类。我们需要一种与 Query 模版参数无关的方法。

我们喜欢的 protocol 这时可以发挥作用了。我们不需要获取“property 具体的类型”这么强的信息，只需要这个 property 能够向我们提供我们需要的 URL 编码的 value 和 key 就行了。马上可以写一个协议：

protocol QueryProtocol {
 func urlEncodedKey() -> String
 func urlEncodedValue() -> String
}

我们给 Query 加上 QueryProtocol 的协议：

extension Query: QueryProtocol {
 func urlEncodedKey() -> String {
 return SomeURLStringEncoder().encode(key)
 }
 func urlEncodedValue() -> String {
 return SomeURLStringEncoder().encode(wrappedValue)
 }
}

这样，我们就可以用 Mirror 访问 key 和 value 了：

let mirror = Mirror(reflecting: request) // request is `SomeRequest`
for (_, property) in mirror.children {
 if let query = property as? QueryProtocol {
 let key = query.urlEncodedKey()
 let value = query.urlEncodedValue()

 // TODO: Add key, value to request URL.
 }
}

这样，最后一个障碍——读取参数信息也扫清了。我们可以获取到一个类里面所有的 @Query 参数了，将所有的 key 和 value 加到请求的 URL 即可。

实际上的处理要稍微复杂一点，因为 Value 可能是一个数组，这时候就不仅仅是一个 key 和 value 对了。

后续

根据相似的思路，我们可以为 Header、body 参数等定义类似的 Property Wrapper：

Property Wrapper	Description	Wrapped Value
`@Header`	HTTP Header	`String?`
`@HeaderDict`	An dictionary of headers	`[String : String]?`
`@Query`	Query parameters	`Encodable?`
`@QueryDict`	An dictionary of query parameters	`[String : String]?`
`@KeyQuery`	Query parameters with no value associated	`Bool`
`@JSON`	Body parameters with JSON encoding	`Encodable?`
`@Field`	Form URL Encoded parameters	`Encodable?`

我们可以在一个类声明中定义所有的请求参数了。最后的实现效果如下：

struct SetPushRequest: JSONDecodableRequest, RequestConfiguration {
 @Header("TOKEN") var accessToken = nil
 @Field("push_system_msg") var pushSystemMessage: Bool? = nil
 @Field("push_reply_me") var pushReplyMe: Bool? = nil
 @Field("push_favorited") var pushFavourite: Bool? = nil

 struct Response: Codable {
 var code: Int
 var msg: String?
 }

 let base: URL = URL(string: "https://dev-api.thuhole.com")!
 let path: String = "v3/config/set_push"
 let method: HTTPMethod = .post

 var configuration: Self { return self }
}

let request = SetPushRequest(accessToken: token, pushSystemMessage: true, pushReplyMe: true, pushFavourite: false)

request.perform { result in
 switch result {
 case .success(let response):
 print(response)
 case .failure(let error):
 print(error)
 }
}

SetPushRequest 的定义不计空行只用了 14 行。在原来树洞的代码中，完成上述功能写了 31 行（不包括上面代码不涉及的功能）。

项目源代码参见 liang2kl/APIKit（~~虽然还没写完~~）。

利用 Property Wrapper 包装参数，加上一些基本信息，就可以定义一个 HTTP 请求了。最重要的是，我们再也不需要手动设置 parameters 了。

Mirror | Apple Developer Documentation ↩︎

协议 + 泛型：威力巨大的组合

liang2kl@outlook.com (Liang Yesheng) — Thu, 26 Aug 2021 00:00:00 +0800

写树洞客户端时，和一个 PKU 的同学一起写，他负责写调用树洞 HTTP API 获取数据的部分。既然涉及到协作，就得先规定下接口了。

对于 Swift 来说，规定接口的最好的办法自然是 protocol ——规定并强制实现所有的接口。于是，我着手写这个协议的声明。

源代码参见 liang2kl/HollowCore。

协议的设计

目标

协议的设计有两个目标：

所有的请求均提供统一的接口，方便调用
尽可能方便不同的请求类复用代码

v1.0：最初尝试

接口无非是 输入 + 输出，对于网络请求，输入即是请求的参数，输出是得到的 response。很容易想到这样一个声明：

protocol Request {
 // 用网络请求参数初始化请求
 init(parameters: [String : String])
 // 开始请求
 func performRequest(completion: @escaping (String?, Error?) -> Void)
}

其中，init 接受一个字典作为输入，performRequest 接受一个回调函数，异步处理数据。

乍看之下，似乎没什么问题——调用者只需要将参数的字典传进去，然后接收 JSON 格式的 String 字符串就行了。不过，这个设计真的合理吗？

仔细分析，这个版本的协议存在这些问题：

调用者的输入 parameters: [String : String] 没有受到任何限制，导致：
- 调用者在每次调用时都需要查看文档以确定需要传哪些参数
- 被调用者需要繁琐地一一检查字典的 key 和 value 是否符合要求
直接返回原始的 JSON 字符串，每次调用后均需要解析

问题的根本在于，完成网络请求的类并不知道任何关于请求本身的具体信息。我们需要向类提供这些信息，使得类只接受符合规定的输入，并提供解析好的、符合规定的输出。而且，完成这个目标最好是依赖编译期进行静态的检查，避免可能出现的失误。朝着这个目标，我们来写 2.0 版本。

v2.0：添加请求信息

我们需要向 Request 协议内添加参数、输出的信息。

首先考虑传递参数的问题。一个朴素的想法是在 init 中分别列出参数，如：

init(token: String, page: Int, ...)

但是这就违背了我们**「提供一个统一的接口」**的宗旨。理想情况下，我们应该提供这样一个接口：

init(configuration: Configuration)

其中，Configuration 包装了所有需要的参数，这通常使用 struct 完成。

但是，不同请求的 Configuration 是不一样的，该怎么办？

幸运的是，protocol 支持“泛型”，我们只需要针对不同的请求定义不同的 Configuration 类就可以了。同理，每个请求应该有对应的 Response 类型。另外，为了方便处理错误，添加一个 Error 类型，其遵循 Swift 中 Error 协议，用来指定具体的错误。新的设计如下：

protocol Request {
 associatedtype Configuration
 associatedtype Response
 associatedtype Error: Swift.Error

 // 储存参数信息
 var configuration: Configuration { get set }

 init(configuration: Configuration)
 func performRequest(completion: @escaping (Response?, Error?) -> Void)
}

我们可以开始实现具体的请求了。比如，对于编辑收藏的请求：

struct EditAttentionRequest: Request {
 struct Configuration {
 var token: String
 var postId: Int
 var switchToAttention: Bool
 }

 struct Response {
 // 暂时省略
 ...
 }

 enum Error: Swift.Error {
 case tokenExpired,
 case ...
 }

 var configuration: Configuration

 init(configuration: Configuration) {
 self.configuration = configuration
 }

 func performRequest(completion: @escaping (Response?, Error?) -> Void) {
 let urlPath = "v3/edit/attention"
 ...
 }
}

这样，对于调用者来说就轻松很多了，不再需要翻文档来传参数，也不需要自己来解析 JSON 字符串，只需要根据 Configuration 的构造函数传递参数，并利用得到的 Response 即可：

let configuration = EditAttentionRequest.Configuration(...)
let request = EditAttentionRequest(configuration: configuration)

request.performRequest { response, error in
 ...
}

这个版本的 Request 基本上实现了我们设计一个统一接口的目标。

v2.1：Response 的界定

注意到上面的 EditAttentionRequest 中省略了 Response 的定义。我们需要明确 Response 是什么。

从调用者的角度，Response 应该是可以直接利用，而不需要再进行处理的数据；而从请求本身的角度，Response 指的是服务器返回的 JSON 字符串解析出来的对象。但是，这两个概念并不总是一样的：服务器返回的结果往往需要进一步处理，比如指示请求状态的 code，错误信息 msg 等。

于是，Response 的概念需要分成两部分：服务器返回的结果 Result，和处理后最终返回的可以直接使用的数据 ResultData：

protocol Request {
 associatedtype Configuration
 associatedtype Result
 associatedtype ResultData
 associatedtype Error: Swift.Error

 init(configuration: Configuration)
 func performRequest(completion: @escaping (ResultData?, Error?) -> Void)
}

相对应地，EditAttentionRequest 中 Result 和 ResultData 分别定义为：

struct Result: DefaultRequestResult {
 var code: Int
 var msg: String?
 var data: Post?
}

typealias ResultData = Post

在编辑完关注状态后，服务器会返回完整的树洞信息 Post，以及 code 和 msg。我们不需要 code 和 msg（错误已经在请求内部处理），于是 Post 作为 ResultData 就可以了。

定义 Result 类型是很有必要的：我们一般直接使用 JSONDecoder 将 JSON 反序列化为对象，这需要我们提供解析的模版，即 Result。

至此，我们的协议声明已经基本上完成了。所有遵循 Request 协议的类型都对外提供了统一的接口，并且利用泛型实现了对参数输入、服务器返回数据、最终输出和错误的严格规定。

代码复用与接口扩展

上面我们花了大力气来规定 Request 的各种类型，但除了统一了接口、约束输入输出外并没有什么特别的作用。实际上，协议 + 泛型的巨大威力体现在代码复用和接口扩展上。

代码复用

上面的 Request 只是规定了接口，我们还要逐一实现每个请求的 performRequest。如果分别独立写 HTTP 请求代码，将十分繁琐，而且会大量重复相同代码。为此，我们需要进行一些默认实现。

大多数请求满足两个共性：

从 JSON 反序列化为对象的要求很简单：Result 类型遵循 Decodable 即可。对于这些请求，由获得的 JSON 生成 Result 的方法是固定的。
返回包括 code 和 msg，用来传递查询结果和错误信息。因此，从 Result 生成 Error 的方法是固定的。而大多数的 Error 类型也是相同的。

利用这两点，我们可以在 Request 的基础上，针对这些请求进行 performRequest 的默认实现。对这些请求，我们定义一个新的协议 DefaultRequest，遵循 Request：

protocol DefaultRequest: Request
 where Error == DefaultRequestError, Result: DefaultRequestResult { }

Error 为 DefaultRequestError，是一个涵盖了所有错误类型的 enum：

enum DefaultRequestError: Swift.Error, LocalizedError {
 case decodeFailed
 case tokenExpiredError
 case fileTooLarge
 case unknown
 case noSuchPost
 case other(description: String)

 init(errorCode: Int, description: String?) {...}
}

Result 遵循 DefaultRequestResult，其定义如下：

protocol DefaultRequestResult: Codable {
 var code: Int { get }
 var msg: String? { get }
}

分别对应上述两个共同点。

于是，我们就可以进行 performRequest 的默认实现了。在 DefaultRequest 的 extension¹ 中：

extension DefaultRequest {
 func performRequest(
 urlRoot: String,
 urlPath: String,
 parameters: [String : Any]? = nil,
 headers: HTTPHeaders? = nil,
 method: HTTPMethod,
 transformer: @escaping (Result) -> ResultData?,
 completion: @escaping (ResultData?, Error?) -> Void
 ) {...}
}

在函数内，我们需要实现：

将网络请求得到的 JSON 反序列化为对象，由 DefaultRequestResult 遵循 Codable 满足

let jsonDecoder = JSONDecoder()
let result = try jsonDecoder.decode(Result.self, from: data)

将 Result 中包含的错误信息转化为 Error 返回，由 Error 类型已知以及 DefaultRequestResult 中要求 code 和 msg 满足
```
let error = DefaultRequestError(errorCode: result.code, description: result.msg)
```

将 Result 转化为 ResultData，由传入的参数 transformer 提供

if let data = transformer(result) {
 completion(data, nil)
}

我们在对 protocol 的泛型作了一定的约束后，获得了更多的信息，使得我们可以在不知道请求的具体类型的情况下进行默认实现。

完整代码如下：

func performRequest(
 urlRoot: String,
 urlPath: String,
 parameters: [String : Any]? = nil,
 headers: HTTPHeaders? = nil,
 method: HTTPMethod,
 transformer: @escaping (Result) -> ResultData?,
 completion: @escaping (ResultData?, Error?) -> Void
) {
 AF.request(
 urlRoot + urlPath,
 method: method,
 parameters: parameters,
 encoding: URLEncoding.default,
 headers: headers
 )
 .validate()
 .responseJSON { response in
 switch response.result {
 case .success:
 let jsonDecoder = JSONDecoder()
 jsonDecoder.keyDecodingStrategy = .convertFromSnakeCase
 do {
 guard let data = response.data else {
 completion(nil, .unknown)
 return
 }
 let result = try jsonDecoder.decode(Result.self, from: data)
 if result.code >= 0 {
 // result code >= 0 valid!
 if let data = transformer(result) {
 completion(data, nil)
 } else {
 completion(nil, .unknown)
 }
 } else {
 let error = DefaultRequestError(errorCode: result.code, description: result.msg)
 completion(nil, error)
 return
 }

 } catch {
 completion(nil, .decodeFailed)
 return
 }

 case let .failure(error):
 if let errorCode = error.responseCode, errorCode == 413 {
 completion(nil, .fileTooLarge)
 return
 } else {
 completion(nil, .other(description: error.localizedDescription))
 return
 }
 }
 }
}

现在，我们可以轻松实现具体类型的 performRequest 了，如 EditAttentionRequest：

func performRequest(completion: @escaping (ResultData?, Error?) -> Void) {
 let urlPath = "v3/edit/attention" + Constants.urlSuffix

 let headers: HTTPHeaders = [
 "TOKEN": self.configuration.token,
 "Accept": "application/json"
 ]

 let parameters: [String : Encodable] = [
 "pid" : self.configuration.postId,
 "switch": self.configuration.switchToAttention ? 1 : 0,
 ]

 performRequest(
 urlRoot: self.configuration.apiRoot,
 urlPath: urlPath,
 parameters: parameters,
 headers: headers,
 method: .post,
 transformer: { $0.data },
 completion: completion
 )
}

我们只需要将 Configuration 转换为字典就可以了。在实际项目中，几乎所有的请求都可以遵循 DefaultRequest，只需要写一次网络请求的代码，就可以实现所有的网络请求。这就是 protocol + 泛型 + 限制条件的魅力。

接口扩展

利用 protocol 的泛型，还有个好处在于扩展接口十分方便。例如，针对 Swift 5.5 的 async/await，我们很容易为 Request 添加异步接口：

extension Request {
 func result() async -> (ResultData?, Error?) {
 return await withCheckedContinuation { continuation in
 performRequest { result in
 continuation.resume(returning: result)
 }
 }
 }
}

几乎不需要写任何代码。

总结

Swift 的 protocol 相当于 C++ 的抽象类，不过相比 C++ 更加严谨、灵活。protocol 本身有规定接口的功能，再加上泛型，能够很好地实现多态，实现高效的代码复用，同时保持良好的可维护性和可扩展性。

Protocols — The Swift Programming Language (Swift 5.5) ↩︎

coding on liang2kl's Blog

WWDC22 Sessions 记录

Meet Swift Regex

Meet desktop class iPad

The SwiftUI cookbook for navigation

Hello Swift Charts

What’s new in SwiftUI

Window 和 Menu bar extras

Resizable sheets

其他

What’s new in UIKit

Compose custom layouts with SwiftUI

Grid

自定义布局

sizeThatFits

placeSubviews

传递额外信息

自适应布局

AnyLayout

Swift Charts: Raise the bar

Embrace Swift generics

Design protocol interfaces in Swift

Type erasure

Hide implementation details

关于 type(of:)

协程上下文切换

上下文切换

调用栈结构

程序

例子 #1

例子 #2

汇编结果

Jinja 继承、函数和块

继承：extends

函数：macro

重写：block

放在一起

做一个 MkDocs 博客插件

MkDocs 的插件是怎么工作的

设计与实现

插件类与用户配置

获取博客文件

页面生成

页面插入

总结

用 Property Wrapper 包装网络请求参数

理想效果

设计与实现

包装参数

获取信息

后续

协议 + 泛型：威力巨大的组合

协议的设计

目标

v1.0：最初尝试

v2.0：添加请求信息

v2.1：Response 的界定

代码复用与接口扩展

代码复用

接口扩展

总结

关于 `type(of:)`

继承：`extends`

函数：`macro`

重写：`block`