Swift Macro #unwrap报错需定义，如何正确编写实现？

WWDC 2023上展示的代码只是这个宏的声明（接口），并没有包含实际的代码展开逻辑——Swift宏要求声明和实现分离，你看到的报错就是因为缺少了宏的实现部分。下面是完整的编写和使用步骤：

1. 明确宏的核心逻辑 #

这个unwrap宏的作用是解包可选值，如果值为nil就触发错误提示。最终它会被展开成类似下面的代码：

if let unwrapped = optionalValue {
    unwrapped
} else {
    fatalError("自定义错误消息")
}

2. 创建独立的宏模块 #

Swift宏必须放在独立的模块中，不能直接写在主项目代码里：

• 在Xcode中新建Swift Package，或者在现有项目中添加Macro Target
• 确保模块依赖SwiftSyntax系列框架（这是Swift宏的核心依赖）

3. 编写宏的声明和实现 #

宏的对外声明 #

在宏模块的源文件中，先定义宏的接口：

import SwiftSyntaxMacros
import SwiftSyntax

@freestanding(expression)
public macro unwrap<Wrapped>(_ expr: Wrapped?, message: String) -> Wrapped = #externalMacro(module: "你的宏模块名称", type: "UnwrapMacro")

注意：WWDC展示的代码省略了@freestanding(expression)注解，以及参数expr的可选类型Wrapped?——这两个是宏正常工作的必要条件。

宏的展开逻辑实现 #

接着编写宏的具体展开逻辑，实现ExpressionMacro协议：

import SwiftSyntax
import SwiftSyntaxMacros
import SwiftSyntaxBuilder
import SwiftDiagnostics

public struct UnwrapMacro: ExpressionMacro {
    public static func expansion(
        of node: some FreestandingMacroExpansionSyntax,
        in context: some MacroExpansionContext
    ) throws -> ExprSyntax {
        // 校验传入的参数格式是否合法
        guard let arguments = node.arguments.as(LabeledExprListSyntax.self),
              arguments.count == 2,
              let exprArg = arguments.first?.expression.as(ExprSyntax.self),
              let messageArg = arguments.last?.expression.as(StringLiteralExprSyntax.self) else {
            throw UnwrapMacroError.invalidArguments
        }
        
        // 生成最终展开的代码
        return ExprSyntax("""
            if let unwrapped = \(exprArg) {
                unwrapped
            } else {
                fatalError(\(messageArg))
            }
            """)
    }
}

// 自定义编译阶段的错误提示
enum UnwrapMacroError: Error, DiagnosticMessage {
    case invalidArguments
    
    var message: String {
        "unwrap宏需要传入两个参数：一个可选值表达式，一个错误消息字符串"
    }
    
    var diagnosticID: MessageID {
        MessageID(domain: "UnwrapMacro", id: "invalidArguments")
    }
    
    var severity: DiagnosticSeverity {
        .error
    }
}

4. 在主项目中使用宏 #

• 将宏模块添加到主项目的依赖列表中
• 在需要使用的文件中导入宏模块，通过#unwrap调用：

import 你的宏模块名称

let optionalString: String? = "Hello"
let unwrappedString = #unwrap(optionalString, message: "字符串解包失败")

关键注意事项 #

• Xcode 15 Beta的宏语法可能存在小版本差异，需确保使用对应版本的SwiftSyntax依赖
• 参数校验能在编译阶段给开发者明确的错误提示，避免运行时才发现问题
• 若在现有项目中添加宏目标，需在项目设置中正确配置模块依赖关系

内容的提问来源于stack exchange，提问作者Vollan