聊聊 Swift 中的宏
宏，Macros 是一种常见的编程技术，传统的 C 语言中，即包含了宏功能。宏这种功能，简单来说是在代码的预编译阶段进行静态替换，是一种非运行时的特性。但是往复杂了说，宏实际上也提供了一种”元编程“方式，即对程序本身进行编程。如果真正掌握宏的应用，又比较复杂，以 C 语言中的宏为例，宏可以有参数，可以进行嵌套展开，要编写质量高的宏，还是非常有难度。这里附上之前的一篇关于 Objective-C 下宏的应用博文，以供需要的朋友参考：
https://my.oschina.net/u/2340880/blog/3357392
Swift 宏简介
最初的 Swift 版本其实并不支持宏，这其实也和 Swift 语言的设计理念有关，C 语言中的宏应用广泛，但是编译时展开的特性会是代码的可读性下降，也会增加代码的漏洞风险。Swift 秉承安全、易理解、易使用的设计初衷，并没有引入宏的概念。但宏的元编程能力可以大大的提高编程的灵活性和复用性，Swift 在 5.9 版本中重新引入了宏功能，并且是以一种全新的方式来定义和实现宏，在提供灵活性的同时保证代码的安全性和可靠性。但这也有一些缺陷，相比与 C 语言的宏，Swift 中的宏的定义非常抽象，实现复杂，不太利于开发者进行理解。本篇文章即基于这一前提，希望可以系统简介的对 Swift 中的宏进行介绍，帮助更多开发者了解它，使用它。
首先，在做详细介绍前，我们需要先牢记几个核心原理：
1 - 宏会在编译代码前进行代码转换，即预编译阶段进行处理。
2 - 宏在展开时，永远只会增加代码，不会修改或删除原始的代码。（重点）
3 - 宏的输入和输出都会经过编译器的检查，保证其语法正确，并且如果宏展开后的实现发现异常，也会被处理为编译时异常。
上述的原理 1 和原理 3 无需特别关注，只需要知道宏是一个编译时的特性即可，原理 2 是非常重要的，当我们想将某个功能点编写为宏时，首先要考虑的是我们是要附加功能还是删改功能，如果是增加功能则非常适合使用宏，如果是删改逻辑则应该早早放弃，宏永远不应该删改原本的代码。
Swift 中的宏分为两类：
1 - 独立宏
2 - 附加宏
其中，独立宏单独出现，单独使用，不会附加到任何声明（可以理解为原始代码）上。附加宏则需要配合声明一起使用，通常是为了向原代码中增加一些功能。从特性上看，独立宏与 C 语言的宏有些类似，做简单的代码展开或静态替换很方便。附加宏则更像是一种装饰器模式的应用，为原始逻辑进行包装，附加功能。这两种宏从声明到用法上都有区别。
独立宏
独立宏使用"#"来调用，因此当你在代码中看到 #相关的语法时，就要意识到这是一个宏，且是一个独立宏。标准库中默认提供了一些独立宏可以直接使用，例如：
class ViewController: UIViewController { override func viewDidLoad() { super.viewDidLoad() print(#file, #function, #line) #warning("系统宏，显示警告信息") }}
复制代码
上面代码中，#file,#function,#line 和 #warning 都是独立宏，前 3 个宏无参数，在编译时分别替换为当前文件名、当前函数名和当前行号，#warning 宏有参数，用来为告诉编译器这里展示一条警告信息。这些宏因为是标准库中的，我们无法查看展开后的样子，如果是自定义宏则可以直接展开查看，后面我们再介绍。
附加宏
使用”@“来调用附加宏，附加宏用来补充其所声明的代码，为原始代码添加新的功能，附加宏比较复杂，后面我们再详细介绍。
宏的声明、定义与实现
Swift 语言和 C 语言的一大区别在于 Swift 一般无需做声明，如函数、变量、类等，直接定义即可使用。但宏却不同，宏必须进行声明，声明的主要作用是指定宏的名称、参数以及类型和使用场景。
与普通的 Swift 功能代码不同，每个宏都是一个单独的 Swift 包，在工程中我们可以创建一个新的 Package，选择 Swift Macro，如下图所示：
宏的实现依赖于 swift-syntax 包，Xcode 会自动帮我们加载好依赖。创建好的的 Package 会自动生成模版文件，我们只需要关系 Sources 和 Tests 文件夹下的内容即可。自动生成的模板中的宏是使用了 swift-syntax 包的 Swift 源代码静态分析能力，略为复杂，增加了理解宏本身的难度。这里我们可以不理会这部分，专注于宏本身的逻辑。
首先，一个宏模块分为声明，实现，测试和使用 4 个部分。下面我们逐一来进行介绍。
宏的声明
独立宏声明
独立宏使用 @freestanding 来进行声明，在声明宏时，需要指定宏的角色。独立宏有两种角色：
expression：创建一段有返回值的代码。
declaration：声明类宏，用来创建声明类的代码。
例如我们声明一个角色为 expression 的宏，如下：
@freestanding(expression)public macro AppendHello(_ msg: String) -> String = #externalMacro(module: "MyMacroMacros", type: "AppendHelloMacro")
复制代码
代码中，@freestanding(expression)指定了当前宏是一个表达式角色的独立宏，#externalMacro 是 Swift 内置的一个宏，指定了当前宏所对应的模块名以及类型标识。
声明一个 declaration 角色的宏如下：
@freestanding(declaration, names: arbitrary)public macro MakeStatic(_ name: String) = #externalMacro(module: "MyMacroMacros", type: "MakeStaticMacro")
复制代码
需要注意，宏在指定角色时，可以通过 names 参数来对要使用的符号进行定义，以上面的宏声明为例，MakeStatic 的作用是会生成一个静态变量，因此会在原代码中新增符号，但是变量的名称是由参数决定的，因此需要将 names 参数设置为 arbitrary，表示要生成的符号是不定的。
names 参数可填为：
1 named(xxx) 具体的符号名称。
2 overloaded 对原符号的重载
3 prefixed(xxx) 增加前缀
4 suffixed(xxx) 增加后缀
5 arbitrary 动态符号名称
附加宏声明
附加宏使用 @attached 来进行声明，与独立宏类似，其也需要指定角色：
peer：对等角色，与所附加的原代码在相同的层级上增加代码，例如增加函数的重载。
member：成员角色，为所附加的原代码增加内部成员，如增加属性等。
memberAttribute：成员属性角色，为所附加的源代码的内部成员增加属性。
accessor：访问器角色，为所附加的源代码增加 Getter，Setter 方法等。
extension（之前为 conformance，最新 swift 版本修改为 extension）：遵守着角色，为所附加的源代码增加协议和约束。
我们先来定义一个 peer 角色类型的宏，用来实现一个自动生成的重载函数，此重载函数会增强原函数的功能，添加函数的执行时间日志。如下：
@attached(peer, names: overloaded)public macro OverrideForAPM() = #externalMacro(module: "MyMacroMacros", type: "OverrideForAPMMacro")
复制代码
这里我们将 names 指定为了 overloaded，表示对原符号的重载操作。后面会有此宏的实现示例。
member 角色的宏通常用来为类或结构增加成员变量或方法等，声明示例如下：
@attached(member, names: named(logSelf))public macro MemberLog() = #externalMacro(module: "MyMacroMacros", type: "MemberLogMacro")
复制代码
其中，我们声明时明确定义了要引入的符号 logSelf，此符号将作为生成的函数名。
memberAttribute 角色宏本质上是作用于类或结构的成员上，用来为成员增加修饰，例如可以定义一个宏为类的成员都默认加上 @objc 修饰：
@attached(memberAttribute)public macro Objc() = #externalMacro(module: "MyMacroMacros", type: "ObjcMacro")
复制代码
accessor 角色宏用在具体的成员上，用来增加访问器逻辑，例如下面的声明，此宏将为访问器自动生成计算属性逻辑：
@attached(accessor)public macro GetLog() = #externalMacro(module: "MyMacroMacros", type: "GetLogMacro")
复制代码
extension 宏用来为原结构增加一些协议或遵守一些规则，例如我们可以定义一个宏，来让所修饰的修改自动实现 Equatable 协议：
@attached(extension, conformances:Equatable ,names: named(==))public macro EqualProtocol() = #externalMacro(module: "MyMacroMacros", type: "EqualProtocolMacro")
复制代码
其中 conformances 参数指定要遵守的协议，因为我们同时要对协议进行实现，会引入新的符号，因此需要 names 参数中也指明。
宏的实现
宏的实现，即也是宏的定义。指定了宏具体要实现的逻辑。
独立宏实现
根据前面 AppendHello 宏的声明，在 MyMacroMacros 可以对其进行实现，代码如下：
public struct AppendHelloMacro: ExpressionMacro { public static func expansion(of node: some FreestandingMacroExpansionSyntax, in context: some MacroExpansionContext) throws -> ExprSyntax { // 解析宏的参数，此宏我们定义了一个msg参数 guard let argument = node.argumentList.first?.expression, let segment = argument.as(StringLiteralExprSyntax.self)?.segments.first else { fatalError("编译异常") } // 我们需要将静态代码内部的字符串数据解析出来 switch segment { case .stringSegment(let string): // 返回一个静态字符串表达式 return ExprSyntax(stringLiteral: "\"\(string.content.text + "Hello")\"") default: fatalError("编译异常") } }}
@mainstruct MyMacroPlugin: CompilerPlugin { let providingMacros: [Macro.Type] = [ AppendHelloMacro.self, ]}
复制代码
所有的表达式角色的独立宏，在定义时需要实现 ExpressionMacro 协议，此协议中的 expansion 函数将返回展开后的结果，我们可以根据逻辑来返回数据即可。需要注意，在编写宏时，我们所有做的操作都是元编程操作，因此需要对 Swift 元代码进行解析与处理，这也是 swift-syntax 主要提供的功能。代码中的解析逻辑你可以暂时无需关注。另外，在 Plugin 的定义中，我们要将此宏类实例进行返回，这里的类与我们前面声明时的类标识要一致。
MakeStatic 宏的定义方法也类似，只是其需要实现 DeclarationMacro 协议，角色为声明类型的宏主要是为原代码增加一些声明，如增加属性，增加方法，增加协议等等。为了演示方便，MakeStatic 的作用是根据传入的字符串生成一个静态变量，如下：
public struct MakeStaticMacro: DeclarationMacro { public static func expansion(of node: some FreestandingMacroExpansionSyntax, in context: some MacroExpansionContext) throws -> [DeclSyntax] { // 解析宏的参数，此宏我们定义了一个name参数 guard let argument = node.argumentList.first?.expression, let segment = argument.as(StringLiteralExprSyntax.self)?.segments.first else { fatalError("编译异常") } // 我们需要将静态代码内部的字符串数据解析出来 switch segment { case .stringSegment(let string): // 返回一个静态字符串表达式 return ["static var \(string): Any?"] default: fatalError("编译异常") } }}
复制代码
附加宏实现
OverrideForAPM 宏的实现如下：
public struct OverrideForAPMMacro: PeerMacro { public static func expansion(of node: AttributeSyntax, providingPeersOf declaration: some DeclSyntaxProtocol, in context: some MacroExpansionContext) throws -> [SwiftSyntax.DeclSyntax] { // 函数的声明部分 guard let functionDecl = declaration.as(FunctionDeclSyntax.self) else { fatalError("编译异常") } // 函数的实现副本 if let body = functionDecl.body { return [ """ func \(functionDecl.name)(_ apm: Bool) { if apm {print(Date())} \(body.statements) if apm {print(Date())} } """ ] } return [] }}
复制代码
MemberLog 宏的实现如下：
public struct MemberLogMacro: MemberMacro { public static func expansion(of node: AttributeSyntax, providingMembersOf declaration: some DeclGroupSyntax, in context: some MacroExpansionContext) throws -> [DeclSyntax] { return [ """ func logSelf(){ print(self) } """ ] }}
复制代码
Objc 宏的实现如下：
public struct ObjcMacro: MemberAttributeMacro { public static func expansion(of node: SwiftSyntax.AttributeSyntax, attachedTo declaration: some SwiftSyntax.DeclGroupSyntax, providingAttributesFor member: some SwiftSyntax.DeclSyntaxProtocol, in context: some SwiftSyntaxMacros.MacroExpansionContext) throws -> [SwiftSyntax.AttributeSyntax] { return ["@objc"] }}
复制代码
GetLog 宏的实现如下：
public struct GetLogMacro: AccessorMacro { public static func expansion(of node: AttributeSyntax, providingAccessorsOf declaration: some DeclSyntaxProtocol, in context: some MacroExpansionContext) throws -> [AccessorDeclSyntax] { // 获取所修饰的符号 guard let property = declaration.as(VariableDeclSyntax.self), let binding = property.bindings.first, let identifier = binding.pattern.as(IdentifierPatternSyntax.self)?.identifier.trimmed else { return [] } return [ """ get { print("获取计算属性值", _\(identifier)) return _\(identifier) } """, """ set { _\(identifier) = newValue } """ ] }}
复制代码
EqualProtocol 宏的实现如下：
public struct EqualProtocolMacro: ExtensionMacro { public static func expansion(of node: AttributeSyntax, attachedTo declaration: some DeclGroupSyntax, providingExtensionsOf type: some TypeSyntaxProtocol, conformingTo protocols: [TypeSyntax], in context: some MacroExpansionContext) throws -> [ExtensionDeclSyntax] { return [try ExtensionDeclSyntax("extension \(type.trimmed): Equatable { static func == (lhs: \(type.trimmed), rhs: \(type.trimmed)) -> Bool { lhs == rhs}}")] }}
复制代码
对于附加宏来说，除了上述示例的场景外，我们也可以对某个宏指定多个角色，例如 member 角色宏和 accessor 角色宏，可以同时为所修饰的原结构增加内部属性和外部访问器方法。多个角色宏的实现也类似，只需要具体的实现多个协议即可了。
宏的使用
宏的使用非常简单，创建的宏 Package 中自动生成了一个 main.swift 文件，我们可以在其中进行使用测试，例如：
使用独立的表达式宏：
// newString将被赋值为 Xiao mingHellolet newString = #AppendHello("Xiao ming ")print(newString)
复制代码
使用独立的声明宏：
class MySingle { // 会被展开为 static var obj: Any? #MakeStatic("obj")}
复制代码
使用 peer 宏：
// 此宏编译后会增加一个新的重载函数，如下：//func myFunc(_ apm: Bool) {// if apm {// print(Date())// }//// print("MyFuncCall")// if apm {// print(Date())// }//}@OverrideForAPMfunc myFunc() { print("MyFuncCall")}// 调用将打印：//2024-04-17 14:44:29 +0000//MyFuncCall//2024-04-17 14:44:29 +0000myFunc(true)
复制代码
使用 member 宏：
@MemberLogclass CustomClass { // 将像类中添加方法： // func logSelf() { // print(self) //}}
let c = CustomClass()// MyMacroClient.CustomClassc.logSelf()
复制代码
使用 memberAttribute 宏：
@Objcclass SwiftObjcClass { // 宏展开有会增加 @objc func func1() {} // 宏展开有会增加 @objc var v1 = 0 // 宏展开有会增加 @objc static let s1 = 0}
复制代码
使用 accessor 宏：
class GetLogDemo { var _prop = 0 @GetLog var prop:Int // 下面将被展开 // { // get { // _prop // } // set { // _prop = newValue // } // }}
let d = GetLogDemo()d.prop = 2// 获取计算属性值 2print(d.prop)
复制代码
使用 extension 宏：
@EqualProtocolclass MyNumber { }// 会在下面展开//extension MyNumber: Equatable {// static func == (lhs: MyNumber, rhs: MyNumber) -> Bool {// lhs == rhs// }//}
复制代码
宏的调试与测试
可以发现，宏的代码编写思路与常规的应用开发思路有很大不同，我们主要需要处理的是对 Swift 代码本身的语法树结构的解析与补充。当然，大部分工作 swift-syntax 包都帮我们处理好了。在开发宏时，我们可以直接在使用处右键将宏进行展开，可以直接看到宏编译后的结果，例如：
如果宏展开后的结果比较复杂，我们也可以在运行时进行断点，将宏展开，然后直接进行断点调试即可。
另外，如果想要对宏本身进行断点调试，则我们需要通过单元测试来运行宏，模板代码中已经默认生成了测试代码，例如对 AppendHello 宏进行单测，修改测试文件如下：
import SwiftSyntaximport SwiftSyntaxBuilderimport SwiftSyntaxMacrosimport SwiftSyntaxMacrosTestSupportimport XCTest
// Macro implementations build for the host, so the corresponding module is not available when cross-compiling. Cross-compiled tests may still make use of the macro itself in end-to-end tests.#if canImport(MyMacroMacros)import MyMacroMacros
let testMacros: [String: Macro.Type] = [ "AppendHello": AppendHelloMacro.self,]#endif
final class MyMacroTests: XCTestCase { func testMacro() throws { #if canImport(MyMacroMacros) assertMacroExpansion( """ #AppendHello("Xiao Li ") """, expandedSource: """ "Xiao Li Hello" """, macros: testMacros ) #else throw XCTSkip("macros are only supported when running tests for the host platform") #endif }}
复制代码
单测的逻辑也比较简单，即我们给一个输入宏，然后与预期的展开结果进行对比即可，因为宏是静态展开，因此非常容易也很适合进行单测。在单测执行时，我们是可以对宏的实现部分进行断点的，通过断点，可以对其输入参数的详细信息进行查看，方便我们宏逻辑的编写，以上述单测为例，断点可以后可查看语法节点数据，如下：
(lldb) po nodeMacroExpansionExprSyntax├─pound: pound├─macroName: identifier("AppendHello")├─leftParen: leftParen├─arguments: LabeledExprListSyntax│ ╰─[0]: LabeledExprSyntax│ ╰─expression: StringLiteralExprSyntax│ ├─openingQuote: stringQuote│ ├─segments: StringLiteralSegmentListSyntax│ │ ╰─[0]: StringSegmentSyntax│ │ ╰─content: stringSegment("Xiao Li ")│ ╰─closingQuote: stringQuote├─rightParen: rightParen╰─additionalTrailingClosures: MultipleTrailingClosureElementListSyntax
复制代码
写在最后
本篇文章，单纯从 Swift 宏的角度介绍了各种宏的使用方法和应用场景，然而真正要写好宏，其实还是比较有难度的，首先在编写时展开结果并不直观，其次要考虑的边界情况也很多，因此单测试一个非常好的保证质量的工具。另外，能够熟练使用 swift-syntax 包也是写好宏的基础。有时间，后面在专门整理 swift-syntax 的用法吧，希望本篇文章可以为你带来一些帮助和启发，感谢你使用宝贵时间阅读。
评论