聊聊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("编译异常")
        }
    }
}

@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的用法吧，希望本篇文章可以为你带来一些帮助和启发，感谢你使用宝贵时间阅读。