当前位置：首页 > news >正文

Swift 宏（Macro）入门趣谈（五）

news 2025/7/7 20:30:34

在这里插入图片描述

概述

苹果在去年 WWDC 23 中就为 Swift 语言新增了“其利断金”的重要小伙伴 Swift 宏（Swift Macro）。为此，苹果特地用 2 段视频（入门和进阶）颇为隆重的介绍了它。

在这里插入图片描述

那么到底 Swift 宏是什么？有什么用？它和 C/C++ 语言中的宏又有什么异同呢？本系列博文将会尝试为小伙伴们揭开 Swift 宏的神秘面纱。

在本篇博文中，您将学到如下内容：

概述
- 5.4 完成宏主体
- 5.5 验证宏展开后的结果
6. 另一个简洁的解决方案
7. 目前 Swift 宏的不足之处
总结

相信学完本系列博文后，Swift Macro 会从大家心中的“阳春白雪”变为“阳阿薤露”，小伙伴们必可以将它们运用的“如臂使指”。

那还等什么呢？Let‘s go！！！😉

5.4 完成宏主体

在完成了 @nilable 宏接口、客户端代码以及宏主体初步结构的搭建之后，现在回到 NilableMacro 结构的定义中，我们现在可以尝试补全 expansion() 方法中所有展开代码了。

不过在撸码之前，我们有必要先来了解一下 expansion() 方法传入实参所扮演的角色。在这个例子中，我们只关心其中的 declaration 参数，它是一个 some DeclSyntaxProtocol 类型：

providingPeersOf declaration: some DeclSyntaxProtocol

在 Xcode 调试控制台中，我们利用 po 命令可以列出它的结构细节：

FunctionDeclSyntax
├─attributes: AttributeListSyntax
│ ╰─[0]: AttributeSyntax
│   ├─atSign: atSign
│   ╰─attributeName: IdentifierTypeSyntax
│     ╰─name: identifier("nilable")
├─modifiers: DeclModifierListSyntax
│ ├─[0]: DeclModifierSyntax
│ │ ╰─name: keyword(SwiftSyntax.Keyword.static)
│ ╰─[1]: DeclModifierSyntax
│   ╰─name: keyword(SwiftSyntax.Keyword.private)
├─funcKeyword: keyword(SwiftSyntax.Keyword.func)
├─name: identifier("test")
├─genericParameterClause: GenericParameterClauseSyntax
│ ├─leftAngle: leftAngle
│ ├─parameters: GenericParameterListSyntax
│ │ ├─[0]: GenericParameterSyntax
│ │ │ ├─attributes: AttributeListSyntax
│ │ │ ├─name: identifier("Root")
│ │ │ ╰─trailingComma: comma
│ │ ╰─[1]: GenericParameterSyntax
│ │   ├─attributes: AttributeListSyntax
│ │   ├─name: identifier("Value")
│ │   ├─colon: colon
│ │   ╰─inheritedType: IdentifierTypeSyntax
│ │     ╰─name: identifier("Comparable")
│ ╰─rightAngle: rightAngle
├─signature: FunctionSignatureSyntax
│ ├─parameterClause: FunctionParameterClauseSyntax
│ │ ├─leftParen: leftParen
│ │ ├─parameters: FunctionParameterListSyntax
│ │ │ ├─[0]: FunctionParameterSyntax
│ │ │ │ ├─attributes: AttributeListSyntax
│ │ │ │ ├─modifiers: DeclModifierListSyntax
│ │ │ │ ├─firstName: identifier("dump")
│ │ │ │ ├─secondName: identifier("a")
│ │ │ │ ├─colon: colon
│ │ │ │ ├─type: IdentifierTypeSyntax
│ │ │ │ │ ├─name: identifier("KeyPath")
│ │ │ │ │ ╰─genericArgumentClause: GenericArgumentClauseSyntax
│ │ │ │ │   ├─leftAngle: leftAngle
│ │ │ │ │   ├─arguments: GenericArgumentListSyntax
│ │ │ │ │   │ ├─[0]: GenericArgumentSyntax
│ │ │ │ │   │ │ ├─argument: IdentifierTypeSyntax
│ │ │ │ │   │ │ │ ╰─name: identifier("Root")
│ │ │ │ │   │ │ ╰─trailingComma: comma
│ │ │ │ │   │ ╰─[1]: GenericArgumentSyntax
│ │ │ │ │   │   ╰─argument: IdentifierTypeSyntax
│ │ │ │ │   │     ╰─name: identifier("Value")
│ │ │ │ │   ╰─rightAngle: rightAngle
│ │ │ │ ╰─trailingComma: comma
│ │ │ ├─[1]: FunctionParameterSyntax
│ │ │ │ ├─attributes: AttributeListSyntax
│ │ │ │ ├─modifiers: DeclModifierListSyntax
│ │ │ │ ├─firstName: identifier("b")
│ │ │ │ ├─colon: colon
│ │ │ │ ├─type: IdentifierTypeSyntax
│ │ │ │ │ ╰─name: identifier("String")
│ │ │ │ ╰─trailingComma: comma
│ │ │ ╰─[2]: FunctionParameterSyntax
│ │ │   ├─attributes: AttributeListSyntax
│ │ │   ├─modifiers: DeclModifierListSyntax
│ │ │   ├─firstName: identifier("c")
│ │ │   ├─colon: colon
│ │ │   ╰─type: IdentifierTypeSyntax
│ │ │     ╰─name: identifier("Int")
│ │ ╰─rightParen: rightParen
│ ├─effectSpecifiers: FunctionEffectSpecifiersSyntax
│ │ ╰─throwsClause: ThrowsClauseSyntax
│ │   ╰─throwsSpecifier: keyword(SwiftSyntax.Keyword.throws)
│ ╰─returnClause: ReturnClauseSyntax
│   ├─arrow: arrow
│   ╰─type: IdentifierTypeSyntax
│     ╰─name: identifier("Bool")
╰─body: CodeBlockSyntax├─leftBrace: leftBrace├─statements: CodeBlockItemListSyntax│ ╰─[0]: CodeBlockItemSyntax│   ╰─item: PrefixOperatorExprSyntax│     ├─operator: prefixOperator("!")│     ╰─expression: MemberAccessExprSyntax│       ├─base: DeclReferenceExprSyntax│       │ ╰─baseName: identifier("b")│       ├─period: period│       ╰─declName: DeclReferenceExprSyntax│         ╰─baseName: identifier("isEmpty")╰─rightBrace: rightBrace

代码看起来很长，似乎有点儿“一望无际”。不过如果我们查看它的 description 属性就会恍然大悟：它其实就是 @nilable 宏修饰方法所对应的语法树。

在这里插入图片描述

所以基本上来说，我们只需要将 declaration 的内容“修剪”为想要的结果即可。对于我们这个例子，就是将 declaration 中第一个 KeyPath 参数中的 Value 变为可选类型 Value?。

下面是我们第一种实现，因为考虑到了“调皮的”用户可能犯的各种错误，所以比较冗长。不过别急，后面我们会给出精简后的方案：

public static func expansion(of node: AttributeSyntax, providingPeersOf declaration: some DeclSyntaxProtocol, in context: some MacroExpansionContext) throws -> [DeclSyntax] {guard let funcDecl = declaration.as(FunctionDeclSyntax.self) else {throw MacroExpansionErrorMessage("必须在方法上使用我哦！")}let funcName = funcDecl.namelet funcModifiers = funcDecl.modifierslet funcGenericParameterClause = funcDecl.genericParameterClauselet funcEffecSpecifier = funcDecl.signature.effectSpecifiers?.description ?? ""let funcReturnClause = funcDecl.signature.returnClause?.description ?? ""let funcBody = funcDecl.bodyguard let funcFirstParamenter = funcDecl.signature.parameterClause.parameters.first else {throw MacroExpansionErrorMessage("方法必须至少要有 1 个参数哦！")}guard let funcFirstParamenterType = funcFirstParamenter.type.as(IdentifierTypeSyntax.self) else {throw MacroExpansionErrorMessage("方法参数格式错误哦！")}guard funcFirstParamenterType.name.description == "KeyPath" else {throw MacroExpansionErrorMessage("方法的第一个参数必须是 KeyPath 类型哦！")}guard let secondArgment = funcFirstParamenterType.genericArgumentClause?.arguments.last, secondArgment.argument.as(OptionalTypeSyntax.self) == nil else {throw MacroExpansionErrorMessage("方法 KeyPath 参数中的 Value 不是 Optional 类型哦！")}let firstName = funcFirstParamenter.firstName.descriptionvar firstArg = if let secondName = funcFirstParamenter.secondName?.description {"\(firstName)\(secondName): "} else {"\(firstName): "}let rootName = funcFirstParamenterType.genericArgumentClause!.arguments.first!.argument.as(IdentifierTypeSyntax.self)!.name.descriptionlet valueName = secondArgment.argument.as(IdentifierTypeSyntax.self)!.descriptionfirstArg += "KeyPath<\(rootName), \(valueName)?>"let parameters = funcDecl.signature.parameterClause.parametersvar otherParametersDesc = ""if parameters.count > 1 {for parameter in parameters.dropFirst() {otherParametersDesc += "\(parameter.description)"}}let nilFuncDecl = try FunctionDeclSyntax("\(funcModifiers)func \(funcName)\(funcGenericParameterClause)(\(raw: firstArg), \(raw: otherParametersDesc)) \(raw: funcEffecSpecifier)\(raw: funcReturnClause) \(funcBody)")return [.init(nilFuncDecl)]
}

在上面的代码中，我们做了这样几件事：

为用户在构造宏所修饰的表达式时可能犯的各种错误（比如用户在属性而不是方法上应用 @nilable 宏）提供贴心的提示；
确定 KeyPath 中 Value 的名称；
考虑到 KeyPath 参数可能出现的名称前缀；
确定方法签名中的其它信息（比如其它参数类型和返回类型）；
考虑到方法本身可能存在一些 modifier 和 effectSpecifiers 修饰器（比如 static、private、throws 等）；

5.5 验证宏展开后的结果

回到 main.swift 源代码文件中，在选中 @nilable 宏关键字后将其展开，如果不出意外我们应该可以正确创建 sortItemsBy 排序方法的 KeyPath 可选 Value 版本（Value？）：

在这里插入图片描述

这意味着，下面这些代码都可以顺利编译通过了：

let itemsByName = try! model.sortItemsBy(keyPath: \.name)
let itmesByNickname = try! model.sortItemsBy(keyPath: \.nickname)

棒棒哒！成就感爆棚的小伙伴们赶快给自已一个大大的赞吧！👍🏻

其实验证 Swift 宏展开结果最好的方法是使用单元测试，但由于目前宏单元测试略显“呆滞和笨拙”，所以暂时略去不表。

6. 另一个简洁的解决方案

虽然我们解决了问题，但上述实现实在是有点“臃肿不堪”。

让我们马上再做一次头脑风暴：我们实际只是想修改 sortItemsBy() 方法 KeyPath 形参中的 Value，如果只考虑几种可能出现的错误，仅需一个简单的字符串内容替换操作即可大功告成！

下面是我们 expansion() 方法简化后的新实现：

public static func expansion(of node: AttributeSyntax, providingPeersOf declaration: some DeclSyntaxProtocol, in context: some MacroExpansionContext) throws -> [DeclSyntax] {guard let funcDecl = declaration.as(FunctionDeclSyntax.self) else {throw MacroExpansionErrorMessage("必须在方法上使用我哦！")}var funcDesc = funcDecl.descriptionfuncDesc.replace(/@nilable/, with: "")let valueFinder = /.*KeyPath<.+?,\s*(.+)>,/guard let value = try valueFinder.firstMatch(in: funcDesc)?.output.1 else {throw MacroExpansionErrorMessage("找不到 KeyPath ！")}funcDesc.replaceSubrange(value.startIndex..<value.endIndex, with: "\(value)?")    return [.init(try FunctionDeclSyntax("\(raw: funcDesc)"))]
}