聊聊Swift中的宏
聊聊Swift中的宏
宏，Macros是一种常见的编程技术，传统的C语言中，即包含了宏功能。宏这种功能，简单来说是在代码的预编译阶段进行静态替换，是一种非运行时的特性。但是往复杂了说，宏实际上也提供了一种”元编程“方式，即对程序本身进行编程。如果真正掌握宏的应用，又比较复杂，以C语言中的宏为例，宏可以有参数，可以进行嵌套展开，要编写质量高的宏，还是非常有难度。这里附上之前的一篇关于Objective-C下宏的应用博文，以供需要的朋友参考：
https://cloud.tencent.com/developer/article/1619700
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("编译异常")
}
}
}
@main
struct 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 mingHello
let 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())
// }
//}
@OverrideForAPM
func myFunc() {
print("MyFuncCall")
}
// 调用将打印：
//2024-04-17 14:44:29 +0000
//MyFuncCall
//2024-04-17 14:44:29 +0000
myFunc(true)使用member宏：
@MemberLog
class CustomClass {
// 将像类中添加方法：
// func logSelf() {
// print(self)
//}
}
let c = CustomClass()
// MyMacroClient.CustomClass
c.logSelf()使用memberAttribute宏：
@Objc
class 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
// 获取计算属性值 2
print(d.prop)使用extension宏：
@EqualProtocol
class MyNumber {
}
// 会在下面展开
//extension MyNumber: Equatable {
// static func == (lhs: MyNumber, rhs: MyNumber) -> Bool {
// lhs == rhs
// }
//}宏的调试与测试
可以发现，宏的代码编写思路与常规的应用开发思路有很大不同，我们主要需要处理的是对Swift代码本身的语法树结构的解析与补充。当然，大部分工作swift-syntax包都帮我们处理好了。在开发宏时，我们可以直接在使用处右键将宏进行展开，可以直接看到宏编译后的结果，例如：
如果宏展开后的结果比较复杂，我们也可以在运行时进行断点，将宏展开，然后直接进行断点调试即可。
另外，如果想要对宏本身进行断点调试，则我们需要通过单元测试来运行宏，模板代码中已经默认生成了测试代码，例如对AppendHello宏进行单测，修改测试文件如下：
import SwiftSyntax
import SwiftSyntaxBuilder
import SwiftSyntaxMacros
import SwiftSyntaxMacrosTestSupport
import 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 node
MacroExpansionExprSyntax
├─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的用法吧，希望本篇文章可以为你带来一些帮助和启发，感谢你使用宝贵时间阅读。
腾讯云开发者
