Swift Macro语法节点构建中\(...)与\(raw:...)的差异及适用场景

核心差异 #

\(raw: node) 和无标签的 \(node) 插值，本质区别在于是否保留语法节点的原始文本格式：

• \(raw: node)：直接插入节点的原始未格式化文本，完全保留源码中的空格、换行、注释等所有细节。
• \(node)：插入时会对节点执行默认格式化，按照Swift标准代码风格调整格式，丢弃非必要的原始格式内容。

适用场景 #

1. \(raw: node) #

• 需要严格复刻原节点格式细节的场景，比如原代码带有自定义缩进、内嵌注释，或者你希望生成代码的格式和原代码完全一致，避免自动格式化破坏原有风格。
• 处理包含特殊格式的复杂语法节点，比如带有多行注释的声明、手动调整过格式的代码片段。

2. \(node) #

• 追求生成代码符合统一Swift代码风格的常规宏场景，不需要保留原节点的自定义格式。
• 大多数普通属性、方法声明插值，默认格式化能让生成的代码更整洁易读。

展开差异显著的情况 #

当原语法节点带有非标准格式时，二者的输出会有明显区别：
例如原变量模式的原始文本为：

myVar  /* 自定义注释 */

• 使用\(raw: binding.pattern)生成的代码：

  var _myVar  /* 自定义注释 */ = 0
  

• 使用\(binding.pattern)生成的代码：

  var _myVar = 0
  

可以看到，默认格式化会移除多余空格和注释，只保留核心语法内容。

带format:参数的重载说明 #

带有format:参数的appendInterpolation重载，并非简单的“是否格式化”差异，而是支持自定义格式化规则：

• 无标签的\(node)使用SwiftSyntax的默认格式化配置。
• 带format:的版本允许传入自定义Format实例，指定缩进宽度、换行规则等细节，既不像raw那样完全保留原始格式，也能灵活控制生成代码的风格，而非只能依赖默认规则。

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