Swift 5.9 宏系统：元编程的新纪元

引言：Swift 终于有了宏！

从 Swift 语言诞生那一刻起，开发者们就一直在等待一个强大的元编程工具。

2022 年，Swift 5.9 正式发布，宏系统（Macros）从预览功能正式落地。这标志着 Swift 进入了元编程的新时代！

今天这篇教程将带你全面掌握 Swift 宏系统，让你能够编写更简洁、更安全的代码。

第一章：为什么需要宏？

1.1 宏的本质

宏（Macro） 是一种在编译时展开的代码生成技术，它允许你：

• 减少样板代码
• 提高代码安全性
• 增强代码可读性
• 实现编译时检查

“`swift
// 没有宏：需要写大量样板代码
struct User: Codable, Identifiable {
let id: String
let name: String
let email: String

init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
id = try container.decode(String.self, forKey: .id)
name = try container.decode(String.self, forKey: .name)
email = try container.decode(String.self, forKey: .email)
}

func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
try container.encode(id, forKey: .id)
try container.encode(name, forKey: .name)
try container.encode(email, forKey: .email)
}
}

// 有宏：一行代码搞定
@available(macOS 13.0, *)
@Macro(User.self)
struct User: Codable, Identifiable {
let id: String
let name: String
let email: String
}

1.2 宏 vs 其他代码生成方式


  

    
方式
    
优点
    
缺点
  
  

    
宏
    
类型安全、编译时检查
    
需要 Swift 5.9+
  
  

    
代码生成工具
    
灵活
    
增加构建步骤、调试困难
  
  

    
运行时反射
    
灵活
    
性能开销、缺少编译时检查
  
  

    
C 预处理器
    
简单
    
无类型检查、调试困难
  


第二章：Swift 宏的类型

2.1 宏的三大类型

Swift 5.9 提供了三种宏类型：

swift
// 1. 声明宏（Declaration Macro）
// 用于修改、替换或删除声明

// 2. 表达式宏（Expression Macro）
// 用于替换表达式

// 3. 类型宏（Type Macro）
// 用于生成类型

2.2 表达式宏示例

swift
import SwiftSyntaxMacros

// 表达式宏示例
public enum StringMacro: ExpressionMacro {
public static func expansion(
of node: some FreestandingMacroExpansionSyntax,
in context: some MacroExpansionContext
) -> ExpressionSyntax {
// 获取字符串字面体
guard let argument = node.arguments.first?.expression,
let stringLiteral = argument.as(StringLiteralExpressionSyntax.self) else {
return “nil”
}

return “\”\(stringLiteral)\”.uppercased()”
}
}

// 使用
@stringify(“hello world”) // 展开为：”hello world”.uppercased()

2.3 声明宏示例

swift
import SwiftSyntaxMacros

// 声明宏示例
public enum SingletonMacro: PeerMacro {
public static func expansion(
of node: AttributeSyntax,
providingPeersOf declaration: some DeclSyntaxProtocol,
in context: some MacroExpansionContext
) throws -> [DeclSyntax] {

guard let classDecl = declaration.as(ClassDeclSyntax.self) else {
return []
}

// 生成 shared 属性
let sharedDecl = “””
static let shared = \(classDecl.name)()
“””

return [DeclSyntax(sharedDecl)]
}
}

// 使用
@singleton
class UserManager {
// 自动生成：static let shared = UserManager()
}

第三章：构建宏

3.1 宏项目结构

MyMacros/
├── Sources/
│ ├── MyMacros/
│ │ └── MyMacros.swift
│ ├── MyMacrosPlugin/
│ │ └── MyMacrosPlugin.swift
│ └── MyMacrosPluginPlugin/
│ └── MyMacrosPluginPlugin.swift
└── Package.swift

3.2 Package.swift 配置

swift
// swift-tools-version:5.9

import PackageDescription

let package = Package(
name: “MyMacros”,
platforms: [
.macOS(.v13),
.iOS(.v16),
.watchOS(.v9),
.tvOS(.v16)
],
products: [
.library(
name: “MyMacros”,
targets: [“MyMacros”]
)
],
dependencies: [
.package(
url: “https://github.com/apple/swift-syntax”,
“509.0.0” ..< "510.0.0" ) ], targets: [ .macro( name: "MyMacros", dependencies: [ .product(name: "SwiftSyntaxMacros", package: "swift-syntax"), .product(name: "SwiftCompilerPlugin", package: "swift-syntax") ] ), .executableTarget( name: "MyMacrosPlugin", dependencies: ["MyMacros"] ), .plugin( name: "MyMacrosPluginPlugin", capability: .buildTool(), dependencies: ["MyMacrosPlugin"] ) ] )

3.3 宏实现

swift
import SwiftSyntax
import SwiftSyntaxBuilder
import SwiftSyntaxMacros

// 表达式宏
public enum StringifyMacro: ExpressionMacro {
public static func expansion(
of node: some FreestandingMacroExpansionSyntax,
in context: some MacroExpansionContext
) -> ExpressionSyntax {
guard let argument = node.arguments.first?.expression else {
return “nil”
}

return “(“\(argument), \(argument))”
}
}

// 声明宏
public enum SingletonMacro: PeerMacro {
public static func expansion(
of node: AttributeSyntax,
providingPeersOf declaration: some DeclSyntaxProtocol,
in context: some MacroExpansionContext
) throws -> [DeclSyntax] {

guard let classDecl = declaration.as(ClassDeclSyntax.self),
classDecl.modifiers.contains(keyword: .final) == false else {
return []
}

let sharedDecl: DeclSyntax = “””
static let shared = \(classDecl.name)()
“””

return [sharedDecl]
}
}

// 附属宏
public enum CodableMacro: MemberMacro {
public static func expansion(
of node: AttributeSyntax,
providingMembersOf declaration: some DeclGroupSyntax,
conformingTo types: [TypeSyntax],
in context: some MacroExpansionContext
) throws -> [DeclSyntax] {

guard let structDecl = declaration.as(StructDeclSyntax.self) else {
return []
}

// 生成编码/解码方法
let methods: [DeclSyntax] = [
“””
init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
\(generateDecodingMethod(from: structDecl))
}
“””,
“””
func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
\(generateEncodingMethod(for: structDecl))
}
“””
]

return methods
}

private func generateDecodingMethod(from decl: StructDeclSyntax) -> String {
// 生成解码代码
return “”
}

private func generateEncodingMethod(for decl: StructDeclSyntax) -> String {
// 生成编码代码
return “”
}
}

第四章：宏的实战应用

4.1 自动实现 Codable

swift
// 手动编写
struct User: Codable {
let id: Int
let name: String
let email: String
}

// 使用宏
@Codable
struct User: Codable {
let id: Int
let name: String
let email: String
}

// 宏生成的代码
struct User: Codable {
let id: Int
let name: String
let email: String

enum CodingKeys: String, CodingKey {
case id = “id”
case name = “name”
case email = “email”
}

init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
id = try container.decode(Int.self, forKey: .id)
name = try container.decode(String.self, forKey: .name)
email = try container.decode(String.self, forKey: .email)
}

func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
try container.encode(id, forKey: .id)
try container.encode(name, forKey: .name)
try container.encode(email, forKey: .email)
}
}

4.2 自动实现 Equatable

swift
// 手动编写
struct Point: Equatable {
let x: Int
let y: Int

static func == (lhs: Point, rhs: Point) -> Bool {
lhs.x == rhs.x && lhs.y == rhs.y
}
}

// 使用宏
@Equatable
struct Point {
let x: Int
let y: Int
}

// 宏生成的代码
struct Point {
let x: Int
let y: Int

static func == (lhs: Point, rhs: Point) -> Bool {
lhs.x == rhs.x && lhs.y == rhs.y
}
}

4.3 验证属性

swift
// 验证邮箱格式
@Validate(\User.email, format: .email)
struct User {
let name: String
let email: String
}

// 验证年龄范围
@Validate(\User.age, range: 0…150)
struct Person {
let name: String
let age: Int
}

// 自定义验证器
@Validate(\User.password, validator: { password in
password.count >= 8 && password.contains { $0.isUppercase }
})
struct User {
let password: String
}

4.4 自动实现 Logger

swift
// 使用宏自动生成日志方法
@Logger
class UserService {
func createUser(_ user: User) {
// 自动包含：
// logger.info(“Creating user: \(user)”)
}

func updateUser(_ user: User) {
// 自动包含：
// logger.info(“Updating user: \(user)”)
}

func deleteUser(_ userId: UUID) {
// 自动包含：
// logger.info(“Deleting user: \(userId)”)
}
}

4.5 依赖注入

swift
// 使用宏自动生成依赖
@InjectDependencies(
database: Database.self,
cache: CacheService.self,
api: APIService.self
)
class UserService {
let database: Database
let cache: CacheService
let api: APIService

init() {
// 自动注入
}
}

// 宏生成的代码
@injectDependencies(
database: Database.self,
cache: CacheService.self,
api: APIService.self
)
class UserService {
let database: Database
let cache: CacheService
let api: APIService

init() {
self.database = .shared
self.cache = .shared
self.api = .shared
}
}

第五章：与 Objective-C 宏对比

5.1 语法对比

objc
// Objective-C 宏（预处理器）
#define MAX_SIZE 100
#define STRINGIFY(x) #x
#define LOG(format, …) NSLog(format, ##__VA_ARGS__)

#define ARRAY_SIZE(array) (sizeof(array) / sizeof(array[0]))

// 使用时
int size = MAX_SIZE;
LOG(“Value: %d”, 42);

swift
// Swift 宏（编译时展开）
@stringify(“hello”) // 编译时展开

@singleton
class MyClass { }

@Codable
struct User {
let name: String
}

// 使用时
let result = stringify(“hello”) // 调用表达式宏
MyClass.shared // 调用声明宏

5.2 类型安全对比

objc
// C 宏：无类型检查
#define SQUARE(x) ((x) * (x))
SQUARE(2 + 3) // 展开为：((2 + 3) * (2 + 3))

// Swift 宏：类型安全
@squared
let x: Int = 5 // 类型检查在编译时进行

5.3 调试对比

objc
// C 宏：调试困难
// #define LOG(…) NSLog(__VA_ARGS__)
// 展开后的代码难以调试

swift
// Swift 宏：调试友好
// 宏展开后的代码可以被 IDE 理解和调试
// 错误信息直接指向宏调用位置

5.4 功能对比

| 功能 | C 宏 | Swift 宏 |
|------|------|---------|
| 类型检查 | ❌ | ✅ |
| 语法高亮 | ❌ | ✅ |
| 自动补全 | ❌ | ✅ |
| 重构支持 | ❌ | ✅ |
| 调试支持 | ❌ | ✅ |
| 泛型支持 | ❌ | ✅ |
| 错误处理 | ❌ | ✅ |

第六章：最佳实践

6.1 何时使用宏

✅ 推荐使用：

减少样板代码
提高代码安全性
实现编译时验证
生成重复代码


❌ 不推荐使用：

简单的代码模式
复杂的运行时逻辑
需要动态修改的代码


6.2 宏设计原则

swift
// ✅ 保持简单
public enum SimpleMacro: ExpressionMacro {
public static func expansion(…) -> ExpressionSyntax {
// 保持逻辑简单
return “result”
}
}

// ❌ 避免复杂逻辑
public enum ComplexMacro: ExpressionMacro {
public static func expansion(…) -> ExpressionSyntax {
// 不要在宏中实现复杂业务逻辑
if condition {
// …
}
return “result”
}
}

6.3 错误处理

swift
public enum SafeMacro: ExpressionMacro {
public static func expansion(
of node: some FreestandingMacroExpansionSyntax,
in context: some MacroExpansionContext
) throws -> ExpressionSyntax {
// 验证输入
guard let argument = node.arguments.first else {
context.diagnose(
Diagnostic(
node: node,
message: MacroErrorMessage(“Missing argument”)
)
)
return “nil”
}

// 类型检查
if argument.type.kind != .int {
context.diagnose(
Diagnostic(
node: argument,
message: MacroErrorMessage(“Expected Int”)
)
)
}

return “expanded”
}
}

6.4 测试宏

swift
import XCTest
import SwiftSyntaxMacros
import SwiftCompilerPlugin

final class MyMacroTests: XCTestCase {
func testStringifyMacro() {
let macro = StringifyMacro()

let input = SyntaxParser.parse(“stringify(value)”)
let output = macro.expansion(of: input) as? ExpressionSyntax

XCTAssertEqual(output?.description, “(value, value)”)
}

func testSingletonMacro() {
let input = SyntaxParser.parse(“””
@singleton
class MyClass {
let value: Int
}
“””)

// 验证生成的代码
// …
}
}

第七章：进阶技巧

7.1 条件宏

swift
@availableIfDebug
@debugLog
class DebugClass {
func doWork() {
// 只在 Debug 模式下编译
}
}

// 宏根据配置展开
#if DEBUG
@debugLog
#endif
class ProductionClass {
func doWork() {
// 只在 Release 模式下编译
}
}

7.2 链式宏

swift
@singleton
@Codable
@Equatable
class User: Identifiable {
let id: UUID
let name: String
}

// 宏依次展开
// @singleton -> 生成 shared
// @Codable -> 生成 Codable 实现
// @Equatable -> 生成 Equatable 实现

7.3 泛型宏

swift
@Repository
class UserService {
let repository: Repository

init() {
// 泛型类型自动推断
}
}

// 宏生成的代码
class UserService {
let repository: Repository

init() {
self.repository = Repository()
}
}

7.4 元数据提取

swift
@ExtractMetadata
class User {
@Property(name: “user_id”)
let id: String

@Property(name: “user_name”)
let name: String
}

// 宏提取属性信息
// 生成：
struct UserMetadata {
static let fields: [Field] = [
Field(name: “user_id”, type: String.self),
Field(name: “user_name”, type: String.self)
]
}
“`

总结：宏是 Swift 的未来

Swift 宏系统为语言提供了强大的元编程能力：

宏的优势：

1. 类型安全：编译时检查，避免运行时错误
2. 代码简洁：消除重复代码
3. 性能优化：编译时生成，无运行时开销
4. IDE 支持：完整的重构和调试支持

使用建议：

• ✅ 优先使用宏减少样板代码
• ✅ 保持宏的逻辑简单
• ✅ 编写完整的单元测试
• ✅ 文档化宏的行为和限制

掌握 Swift 宏系统，让你的代码更加优雅、安全、高效！🚀

—

参考资源：

• [Swift Macros](https://www.swift.org/documentation/macros/)
• [Swift Syntax](https://github.com/apple/swift-syntax)
• [Swift Evolution](https://github.com/apple/swift-evolution)
• [Macro Example Projects](https://github.com/apple/swift-syntax/tree/main/Examples)
打赏赞微海报分享