前言 最近帮客户处理4.3上架问题，所以没怎么在意后台留言。刚刚空了发现有一个留言很稚嫩。正好也跟各位粉丝聊一下为什么收费这事儿。 文章、咨询付费 首先，免费的文章可以理解是我在没有成本下的试错，包括

Swift学习总结，本阶段完成Swift基础内容的总结。本篇幅包括：认识Swift，Swift编译器等。

简要： IQKeyboardManagerSwift：自动管理键盘，防止覆盖输入框，无需代码，适合快速集成。 IQKeyboardCore：提供辅助功能，非独立使用，包含视图扩展和协议。 IQKeyb

iOS 实现自定义对象深拷贝(OC/Swift) 在 OC 中，对象的赋值操作是浅拷贝（指针复制），创建一个指针，旧对象引用对象计数加 1。在 Swift 中，类是引用类型，引用类型在赋值和传参时都是

题记：前文介绍OpenCV的基本操作，本节会继续介绍OpenCV的更多效果。图像处理需要用到很多专业的算法，本人业余学习略知皮毛，只是庶竭驽钝叙其所得，在音视频学习Demo有一些的示例。文章或代码若有

深入探讨iOS中forin循环的底层实现原理，从NSFastEnumeration协议到快速枚举器的实现细节。通过源码分析，揭示forin循环如何高效地遍历集合对象，以及它与普通for循环的性能差异。

Kingfisher 是一个功能强大的 Swift 图像处理库，专注于从网络加载、缓存和显示图像，广泛用于 iOS 开发。其 GitHub 仓库提供了丰富的文档和示例，方便开发者快速集成和使用。 方法

访问 weekly.fatbobman.com 订阅 "肘子的 Swift 周报" 邮件版本。周报将向您介绍近期有关 Swift、SwiftUI、Core Data、SwiftData 等优秀的文章

在 iOS 开发中，截取或分割音视频是常见需求，适用于短视频剪辑、语音消息裁剪、媒体内容编辑等场景。使用 AVFoundation 框架可以高效实现这一功能。下面将详细介绍如何在 iOS 中截取或分割音视频，并提供完整的代码示例和使用方法。

---

✅ 核心思路

截取或分割音视频的核心步骤如下：

1. 加载原始音视频文件（AVURLAsset）
2. 设置时间范围（CMTimeRange）指定要截取的起始时间与持续时间
3. 创建导出会话（AVAssetExportSession）
4. 导出目标文件（支持 .mp4、.m4a 等格式）
5. 处理异步导出完成回调

---

🎬 视频截取示例（Objective-C）

- (void)trimVideoFromURL:(NSURL *)inputURL startTime:(NSTimeInterval)startTime duration:(NSTimeInterval)duration completion:(void (^)(NSURL *outputURL, NSError *error))completion {
    AVURLAsset *asset = [AVURLAsset URLAssetWithURL:inputURL options:nil];
    
    // 1. 创建导出会话
    AVAssetExportSession *exportSession = [[AVAssetExportSession alloc] initWithAsset:asset presetName:AVAssetExportPresetHighestQuality];
    
    // 2. 设置输出路径和文件格式
    NSString *outputPath = [NSTemporaryDirectory() stringByAppendingPathComponent:@"trimmedVideo.mp4"];
    exportSession.outputURL = [NSURL fileURLWithPath:outputPath];
    exportSession.outputFileType = AVFileTypeMPEG4;
    
    // 3. 设置时间范围（start ~ start + duration）
    CMTime startCMTime = CMTimeMakeWithSeconds(startTime, 600);
    CMTime durationCMTime = CMTimeMakeWithSeconds(duration, 600);
    CMTimeRange timeRange = CMTimeRangeMake(startCMTime, durationCMTime);
    exportSession.timeRange = timeRange;
    
    // 4. 异步导出
    [exportSession exportAsynchronouslyWithCompletionHandler:^{
        if (exportSession.status == AVAssetExportSessionStatusCompleted) {
            NSLog(@"视频截取成功: %@", outputPath);
            if (completion) completion([NSURL fileURLWithPath:outputPath], nil);
        } else {
            NSError *error = exportSession.error;
            NSLog(@"视频截取失败: %@", error.localizedDescription);
            if (completion) completion(nil, error);
        }
    }];
}

✅ 使用方法

NSURL *videoURL = [NSURL fileURLWithPath:[[NSBundle mainBundle] pathForResource:@"myVideo" ofType:@"mp4"]];
[self trimVideoFromURL:videoURL startTime:5.0 duration:10.0 completion:^(NSURL *outputURL, NSError *error) {
    if (outputURL) {
        NSLog(@"截取后的视频路径: %@", outputURL.path);
    }
}];

---

🎵 音频截取示例（Objective-C）

- (void)trimAudioFromURL:(NSURL *)inputURL startTime:(NSTimeInterval)startTime duration:(NSTimeInterval)duration completion:(void (^)(NSURL *outputURL, NSError *error))completion {
    AVURLAsset *asset = [AVURLAsset URLAssetWithURL:inputURL options:nil];
    
    AVAssetExportSession *exportSession = [[AVAssetExportSession alloc] initWithAsset:asset presetName:AVAssetExportPresetAppleM4A];
    
    NSString *outputPath = [NSTemporaryDirectory() stringByAppendingPathComponent:@"trimmedAudio.m4a"];
    exportSession.outputURL = [NSURL fileURLWithPath:outputPath];
    exportSession.outputFileType = AVFileTypeAppleM4A;
    
    CMTime startCMTime = CMTimeMakeWithSeconds(startTime, 600);
    CMTime durationCMTime = CMTimeMakeWithSeconds(duration, 600);
    CMTimeRange timeRange = CMTimeRangeMake(startCMTime, durationCMTime);
    exportSession.timeRange = timeRange;
    
    [exportSession exportAsynchronouslyWithCompletionHandler:^{
        if (exportSession.status == AVAssetExportSessionStatusCompleted) {
            NSLog(@"音频截取成功: %@", outputPath);
            if (completion) completion([NSURL fileURLWithPath:outputPath], nil);
        } else {
            NSError *error = exportSession.error;
            NSLog(@"音频截取失败: %@", error.localizedDescription);
            if (completion) completion(nil, error);
        }
    }];
}

✅ 使用方法

NSURL *audioURL = [NSURL fileURLWithPath:[[NSBundle mainBundle] pathForResource:@"myAudio" ofType:@"mp3"]];
[self trimAudioFromURL:audioURL startTime:3.0 duration:5.0 completion:^(NSURL *outputURL, NSError *error) {
    if (outputURL) {
        NSLog(@"截取后的音频路径: %@", outputURL.path);
    }
}];

---

📌 注意事项

项目	说明
时间单位	使用 CMTimeMakeWithSeconds 将秒数转换为 CMTime
输出路径	使用 NSTemporaryDirectory() 可避免存储问题
输出格式	视频推荐 .mp4，音频推荐 .m4a 或 .caf
导出性能	使用 AVAssetExportPresetLowQuality 可提升处理速度
错误处理	检查 exportSession.status 和 exportSession.error

---

🚀 扩展建议

• 多片段拼接：可结合 AVMutableComposition 实现多段裁剪后的内容拼接。
• 后台导出：大文件建议在后台线程执行，避免阻塞主线程。
• 第三方库：如需更复杂剪辑功能，可使用 FFmpeg-iOS 或 GPUImage。

---

✅ 总结

通过 AVAssetExportSession 的 timeRange 属性，你可以轻松地从音视频文件中截取任意时间段的内容。这个方法既适用于音频也适用于视频，具有良好的兼容性和性能表现，是 iOS 音视频处理中的基础技能之一。

在 iOS 开发中，音频和视频的格式选择直接影响性能、兼容性和用户体验。以下是常见的音频和视频格式，以及实际开发中常用的场景： --- ### **一、音频格式** #### **1. 常见音频格

在 Swift 宏体系中，BodyMacro 是一种专门用于替换方法体实现的宏协议。通过 BodyMacro，开发者可以为已有方法、构造器等提供新的实现代码，减少重复代码的书写，并将功能逻辑更加灵活地

Swift 宏系统中，MemberAttributeMacro 是一种用于为类型中的成员声明自动附加属性标记的宏。它适用于需要为多个成员统一附加如 @available、@objc、@discarda

在 Swift 宏系统中，ExtensionMacro 是一种用于自动生成扩展（extension）代码块的宏协议，适用于为类型生成协议实现、工具方法、便捷功能等 “类型之外”的附加内容。它是 Swi

在 Swift 宏体系中，AccessorMacro 是一种专用于自动生成属性访问器（如 getter、setter、willSet、didSet 等） 的宏协议。它适用于那些希望对属性访问行为进行自

在 Swift 宏体系中，PeerMacro 是一种非常灵活且强大的宏协议，专用于生成与绑定声明处于同一作用域的“对等”声明，常用于自动扩展同级的变量、函数或类型定义。

本节将深入介绍 PeerMacro 的用途、定义、参数结构以及实际示例，帮助你理解它在元编程场景中的独特价值。

建议结合《Swift Macros - 宏之全貌》和《Swift Macros - 宏之协议》一并阅读，便于全面理解宏系统的角色协作模型。

1. PeerMacro 的定义

标准库中 PeerMacro 的定义如下：

 public protocol PeerMacro: AttachedMacro {
  static func expansion(
    of node: AttributeSyntax,
    attachedTo declaration: some DeclSyntaxProtocol,
    in context: some MacroExpansionContext
  ) throws -> [DeclSyntax]
 }

这意味着：

• 它是一个 附加宏（attached macro） ；
• 不能生成成员，而是生成与附着声明同级的其他声明；
• 它的返回值为 [DeclSyntax]，即可以注入多个顶层/局部声明；
• 使用范围包括变量、函数、类型、扩展等几乎所有可声明位置。

---

2. PeerMacro 的典型用途

Peer 宏的应用场景非常广泛，常用于：

场景	示例	说明
自动生成伴生变量	@WithWrapper	为属性生成 _xxx 存储变量
自动生成伴生函数	@BindAction	为属性自动生成相关行为函数
生成衍生声明	@AutoObservable	为属性自动生成观察者包装及通知机制
声明反射信息	@Reflectable	自动生成结构体元信息注册代码

特别适合那些需要基于现有声明生成“相关声明”的情境，但不适合直接插入原声明体内的场合。

---

3. 参数详解

of node: AttributeSyntax

代表宏的语法标记本身，例如 @WithWrapper。可用于：

• 宏参数提取；
• 判断具体调用语法。

---

attachedTo declaration: some DeclSyntaxProtocol

• 表示宏附着的原始声明节点；
• 类型是 DeclSyntaxProtocol，表示可以是变量、函数、类型等；
• 你可以从中提取关键元信息（如变量名、类型名、访问级别等）。

---

in context: some MacroExpansionContext

上下文对象，常用于：

• 生成唯一名称（防止冲突）；
• 获取源文件路径、位置；
• 报告诊断信息（如参数错误）。

---

4. 对等声明的展开位置

Peer 宏生成的声明会插入到与原声明相同的作用域中，而不是类型或函数内部。

例如：

 @WithWrapper
 var name: String

展开后等同于：

 var name: String
 private var _name: String = ""

即：_name 是 name 的“对等声明”，它们在同一语法级别上。

---

5. 示例解析

示例：为变量自动生成属性

用法

 struct User {
    @DebugEqual
    var userName: String = ""
 }
 
 // 展开后
 struct User {
    var userName: String = ""
     
    var debug_userName: String {
        "userName = (userName)"
    }
 }

实现

 @attached(peer, names: arbitrary)
 public macro DebugEqual() = #externalMacro(module: "McccMacros", type: "DebugEqualMacro")
 
 public struct DebugEqualMacro: PeerMacro {
    public static func expansion(
        of node: AttributeSyntax,
        providingPeersOf declaration: some DeclSyntaxProtocol,
        in context: some MacroExpansionContext
    ) throws -> [DeclSyntax] {
        // 把通用声明转成变量声明
        guard let varDecl = declaration.as(VariableDeclSyntax.self),
              // 变量可鞥有多个绑定（var a = 1, b = 2）,这里获取第一个。
              let binding = varDecl.bindings.first,
              // 获取变量名，比如”userName“
              let identifier = binding.pattern.as(IdentifierPatternSyntax.self)?.identifier.text
        else {
            return []
        }
 
 
        // 生成新的变量名，如 debug_username
        // raw: 的作用？原样插入这个标识符文本，不会加引号，也不会逃逸。这是写 Swift 宏时推荐的写法之一。
        return [
            """
            var debug_(raw: identifier): String {
                "(raw: identifier) = \((raw: identifier))"
            }
            """
        ]
    }
 }

6. 注意事项

• PeerMacro 会生成多个完整的顶层声明节点，开发者需手动控制命名与作用域；
• 若生成的名称不一致，建议配合 names: 标注宏声明；
• 生成类型或函数声明时，需手动处理访问修饰符和重名冲突。

7. 总结

PeerMacro 是 Swift 宏系统中“横向扩展”的核心工具，它允许开发者在不修改原始声明的前提下添加紧密关联的辅助声明。适用于：

• 分离逻辑与存储
• 为现有属性扩展行为能力
• 构建声明式属性模型

当你需要构建“围绕声明的附属结构”，PeerMacro 就是你的利器。

在 Swift 中，结构体和类的声明体（即 {} 中的内容）常常会包含许多重复或模式化的成员声明。为了提升开发效率并避免重复劳动，Swift 宏系统提供了一种用于自动生成成员声明的宏协议：MemberMacro。在 Swift 宏体系中，MemberMacro 是一种具有极高实用价值的宏协议，它专门用于在类型声明内部生成新的成员（如属性、方法、构造器等）。这种宏是典型的附加宏（attached macro） ，能够大幅减少重复成员定义的样板代码，提高类型声明的表达能力。

本节建议结合《Swift Macros - 宏之全貌》和《Swift Macros - 宏之协议》一并阅读，以便更好地理解宏在声明结构中的角色。

1. MemberMacro 的定义

MemberMacro 是一种 附加宏协议，用于将成员注入至类型声明体中。它只作用于结构体、类、actor、枚举这些具备声明体的类型定义，不能用于函数、变量或其他非类型声明。

它在 Swift 中的声明为：

 public protocol MemberMacro: AttachedMacro {
  static func expansion(
    of node: AttributeSyntax,
    providingMembersOf declaration: some DeclGroupSyntax,
    in context: some MacroExpansionContext
  ) throws -> [DeclSyntax]
 }

参数名	类型	说明
node	AttributeSyntax	当前宏调用的语法节点（包含宏名与参数）
declaration	some DeclGroupSyntax	宏所附加的类型声明体，例如 struct 或 class
context	some MacroExpansionContext	提供诊断、源文件信息等上下文能力

你可以通过 MacroExpansionContext 提供的 diagnose() 方法抛出编译错误，也可以用 context.location(of:) 进行精确定位。

返回值为 [DeclSyntax]，表示你希望宏注入的成员声明数组。例如你可以生成变量、函数、嵌套类型等内容：

 return [  "var id: String = UUID().uuidString",  "func reset() { self.id = UUID().uuidString }" ]
 .map { DeclSyntax(stringLiteral: $0) }

💡 注意：返回的成员会插入到原始类型声明体中，因此要避免命名冲突。

📌 使用限制

• 只可用于具有声明体（{}）的类型定义：struct、class、enum、actor
• 不可用于 func、var、extension 等其他声明
• 若注入的成员包含具名声明（如 var id），必须在宏声明中通过 names: 显式声明，以避免命名未覆盖错误（Declaration name 'id' is not covered by macro）

2. 使用场景分析

MemberMacro 适用于所有需要自动生成类型成员的场景，特别是：

场景	示例	说明
自动生成协议实现	@AutoEquatable	自动实现 Equatable 的 == 方法
自动添加辅助属性	@Observe	为属性生成 _xxx 存储与监控 getter
自动实现构造器	@AutoInit	基于属性自动生成初始化函数
自动生成默认值	@WithDefaults	为成员属性自动附加默认实现

3. 示例解析

示例1：AddID

用法：

 @AddID
 struct User {
  var name: String
 }
 
 // 等价于
 struct User {
  var name: String
  var id = UUID().uuidString
 }

实现：

 @attached(member, names: named(id))
 public macro AddID() = #externalMacro(
  module: "MyMacroImpl",
  type: "AddIDMacro"
 )
 
 public struct AddIDMacro: MemberMacro {
  public static func expansion(
    of node: AttributeSyntax,
    providingMembersOf declaration: some DeclGroupSyntax,
    in context: some MacroExpansionContext
  ) throws -> [DeclSyntax] {
    return [
      "var id = UUID().uuidString"
    ].map { DeclSyntax(stringLiteral: $0) }
  }
 }

如果不明确名称

 @attached(member)

运行会报错：

 ❗️Declaration name 'id' is not covered by macro 'AddID'

说明你使用的是 @attached(member) 宏，但没有在宏声明中说明要生成的成员名字，Swift 宏系统默认是不允许你偷偷“注入”成员名的，除非你通过 names: 明确标注。

示例2：CodableSubclass

对于继承自某个父类的子类，我们希望自动生成 CodingKeys 与 init(from:) 方法.

用法

 class BaseModel: Codable {
    var name: String = ""
 }
 
 @CodableSubclass
 class StudentModel: BaseModel {
    var age: Int = 0
 }
 
 
 // 宏展开后等效于
 class StudentModel: BaseModel {
    var age: Int = 0
     
    private enum CodingKeys: String, CodingKey {
        case age
    }
 
    required init(from decoder: Decoder) throws {
        try super.init(from: decoder)
        let container = try decoder.container(keyedBy: CodingKeys.self)
        self.age = try container.decode(Int.self, forKey: .age)
    }
 }

实现

 @attached(member, names: named(init(from:)), named(CodingKeys))
 public macro CodableSubclass() = #externalMacro(module: "McccMacros", type: "CodableSubclassMacro")
 
 
 public struct CodableSubclassMacro: MemberMacro {
    public static func expansion(
        of node: AttributeSyntax,
        providingMembersOf declaration: some DeclGroupSyntax,
        in context: some MacroExpansionContext
    ) throws -> [DeclSyntax] {
        // 1. 验证是否是类声明
        guard let classDecl = declaration.as(ClassDeclSyntax.self) else {
            throw MacroError.message("@CodableSubclass 只能用于类")
        }
         
        // 2. 验证是否有父类
        guard let inheritanceClause = classDecl.inheritanceClause,
              inheritanceClause.inheritedTypes.contains(where: { type in
                  type.type.trimmedDescription == "BaseModel" ||
                  type.type.trimmedDescription.contains("Codable")
              }) else {
            throw MacroError.message("@CodableSubclass 需要继承自 Codable 父类")
        }
         
        // 3. 收集所有存储属性
        let storedProperties = classDecl.memberBlock.members
            .compactMap { $0.decl.as(VariableDeclSyntax.self) }
            .filter { $0.bindingSpecifier.text == "var" }
            .flatMap { $0.bindings }
            .compactMap { binding -> String? in
                guard let pattern = binding.pattern.as(IdentifierPatternSyntax.self) else {
                    return nil
                }
                return pattern.identifier.text
            }
         
        // 4. 生成 CodingKeys 枚举
        let codingKeysEnum = try EnumDeclSyntax("private enum CodingKeys: String, CodingKey") {
            for property in storedProperties {
                "case (raw: property)"
            }
        }
         
        // 5. 生成 init(from:) 方法
        let initializer = try InitializerDeclSyntax("required init(from decoder: Decoder) throws") {
            // 调用父类解码器
            "try super.init(from: decoder)"
             
            // 创建容器
            "let container = try decoder.container(keyedBy: CodingKeys.self)"
             
            // 解码每个属性
            for property in storedProperties {
                "self.(raw: property) = try container.decode((raw: getTypeName(for: property, in: declaration)).self, forKey: .(raw: property))"
            }
        }
         
        return [DeclSyntax(codingKeysEnum), DeclSyntax(initializer)]
    }
     
    private static func getTypeName(for property: String, in declaration: some DeclGroupSyntax) -> String {
        for member in declaration.memberBlock.members {
            guard let varDecl = member.decl.as(VariableDeclSyntax.self) else { continue }
             
            for binding in varDecl.bindings {
                guard let identifierPattern = binding.pattern.as(IdentifierPatternSyntax.self),
                      identifierPattern.identifier.text == property else {
                    continue
                }
                 
                if let typeAnnotation = binding.typeAnnotation {
                    return typeAnnotation.type.trimmedDescription
                }
            }
        }
         
        // 默认返回 Any，如果找不到匹配
        return "Any"
    }
 }
 
 public enum MacroError: Error, CustomStringConvertible {
    case message(String)
     
    public var description: String {
        switch self {
        case .message(let text):
            return text
        }
    }
 }

4. 总结

MemberMacro 是 Swift 宏体系中连接语法结构与声明注入的关键机制。它让开发者能够根据类型结构自动生成成员，真正实现：

• 结构自动扩展；
• 代码样板消除；
• 类型驱动式逻辑推导。

未来你可以将它与 AccessorMacro、PeerMacro 等组合使用，构建更高层次的声明式元编程能力。

在 Swift 宏体系中，DeclarationMacro 是一种用途广泛的角色，专门用于生成声明级别的代码，如变量、函数、结构体等。它同样属于自由悬挂宏（freestanding macro）的一种

在 Swift 宏体系中，ExpressionMacro 是一种非常重要且常用的角色。它专门用于生成表达式级别的代码，并且属于独立宏（freestanding macro） 的一种。 本节将深入讲解

Swift 宏的强大源于其背后一套精巧严谨的协议体系。这些协议定义了：

• 宏的行为规范：如何与编译器通信，如何生成语法树
• 宏的能力边界：什么宏可以插入什么样的结构
• 宏的输入输出约束：需要接受什么样的输入，返回什么样的输出

在 Swift 中， “宏 = 协议方法的实现” 。宏不会在运行时参与逻辑，而是在编译期间将协议方法转换为结构化代码。

本篇将深入解析这些协议的共性特征与调用方式，为你在后续实现各种角色宏打下统一的基础。

Swift 宏协议的共性特征

Swift 宏虽然分工明确（表达式宏、声明宏、成员宏等），但它们的实现方式高度统一，主要体现为以下特征：

编号	特征	描述
1	方法统一命名为 expansion	所有宏协议都实现 static func expansion(...) 作为展开主入口。
2	支持 throws 异常机制	展开过程中可中止并抛出诊断错误。
3	必带 context 参数	提供编译期上下文信息，是宏的“工具箱”。
4	必带 node 参数	表示宏的调用现场，如 #宏名(...) 或 @宏名。
5	输入输出皆为 Syntax 类型	宏只操作语法树，输入输出都是 SwiftSyntax 节点。
6	仅在编译期执行	宏不能访问运行时信息，所有逻辑基于静态源码。
7	返回类型严格固定	每种宏角色返回类型不同，且不可交叉使用。

1. 所有宏都实现 static func expansion(...)

Swift 宏协议统一使用 expansion 方法命名，使得不同类型的宏拥有相似的签名与调用习惯，极大降低学习与维护成本。

 // 各协议方法签名示例
 protocol ExpressionMacro {
    static func expansion(...) throws -> ExprSyntax
 }
 
 protocol DeclarationMacro {
    static func expansion(...) throws -> [DeclSyntax]
 }

• 方法总是 static，因为宏不依赖实例
• 输入是调用现场 node + 编译上下文 context
• 输出是结构化语法树，如 ExprSyntax、DeclSyntax 等

2. 宏支持 throws，可中止并报告错误

所有宏的 expansion 方法都支持 throws，允许在发现语义错误时立即中止，并通过 context.diagnose(...) 抛出诊断信息，提升宏的可维护性与用户友好度。

只需要在适当的地方抛出异常，你可以自行编辑异常的message，以便使用者更好的理解该异常。

 public struct StringifyMacro: ExpressionMacro {
    public static func expansion(
        of node: some FreestandingMacroExpansionSyntax,
        in context: some MacroExpansionContext
    ) throws -> ExprSyntax {
        throw ASTError("错误提示: the macro does not have any arguments")
    }
 }

你可以通过自定义错误类型（如 ASTError）提供清晰的人类可读信息，IDE 也会高亮定位到宏调用位置，提升调试体验。

3. context 宏的工具箱

每个宏都会收到一个 context 参数（类型为 some MacroExpansionContext），这是宏与编译器交互的主要手段，具备多项能力：

 public protocol MacroExpansionContext: AnyObject {
  func makeUniqueName(_ name: String) -> TokenSyntax
  func diagnose(_ diagnostic: Diagnostic)
  func location(of node: some SyntaxProtocol, at position: PositionInSyntaxNode, filePathMode: SourceLocationFilePathMode) -> AbstractSourceLocation?
  var lexicalContext: [Syntax] { get }
 }

它是宏与编译器沟通的桥梁，也是实现宏逻辑动态化的关键接口。以下是 Swift 宏系统中 MacroExpansionContext 协议四个核心成员的作用详解，按重要性分层说明：

3.1 命名避冲突：makeUniqueName(_:)

自动生成唯一标识符，避免命名冲突

 // 使用场景：临时变量、缓存值、内部标识符等场景。
 let uniqueVar = context.makeUniqueName("result")
 // 输出结果可能是 `result_7FE3A1` 之类的唯一名称

3.2 诊断报告：diagnose(_:)

核心作用：编译时错误报告系统

• 多级诊断：支持 error / warning / note 三种严重级别
• 精准定位：关联到具体语法节点（如高亮错误位置）
• 修复建议：可附加自动修复方案（FixIt）

 public struct StringifyMacro: ExpressionMacro {
    public static func expansion(
        of node: some FreestandingMacroExpansionSyntax,
        in context: some MacroExpansionContext
    ) throws -> ExprSyntax {
     
        context.diagnose(Diagnostic(node: node, message: MacroDiagnostic.deprecatedUsage))
        throw ASTError("错误提示: xxxxxx")
    }
 }

某些宏过期时，可以通过 context.diagnose(...) 给于警告提醒。

DiagnosticMessage

这里的 Diagnostic.message 需要一个实现 DiagnosticMessage 协议的实例。

 public protocol DiagnosticMessage: Sendable {
 /// The diagnostic message that should be displayed in the client.
 var message: String { get }
 
 /// See ``MessageID``.
 var diagnosticID: MessageID { get }
 
 var severity: DiagnosticSeverity { get }
 }

• message：诊断信息的信息

• diagnosticID：诊断 ID

• severity：诊断严重程度

   public enum DiagnosticSeverity {
      case error   // 编译错误，阻止构建。
      case warning // 编译警告，不阻止构建。
      case note     // 提示信息，常用于补充说明。
   }
  

3.3 源码定位：location(of:at:filePathMode:)

可定位到调用宏的具体源代码行列，便于诊断、代码导航、日志标注等用途：

 public static func expansion(
    of node: some FreestandingMacroExpansionSyntax,
    in context: some MacroExpansionContext
 ) throws -> ExprSyntax {   
    let loc = context.location(of: node, at: .afterLeadingTrivia, filePathMode: .fileID )
    ......
 }

func location( of node: some SyntaxProtocol, at position: PositionInSyntaxNode, filePathMode: SourceLocationFilePathMode ) -> AbstractSourceLocation?

从 AbstractSourceLocation 返回值中，可以获取以下信息：

public struct AbstractSourceLocation: Sendable {
/// 文件位置
public let file: ExprSyntax

/// 行的位置
public let line: ExprSyntax

/// 字符位置
public let column: ExprSyntax

• 四种定位模式：

  enum PositionInSyntaxNode {
      case beforeLeadingTrivia  // 包含注释/空格
      case afterLeadingTrivia   // 实际代码起始处
      case beforeTrailingTrivia // 实际代码结束处
      case afterTrailingTrivia  // 包含尾部注释
  }
  

• 路径显示控制：

  • .fileID → "ModuleName/FileName.swift"（安全格式）
  • .filePath → 完整系统路径（调试用）

3.4 词法作用域追踪：lexicalContext

核心作用：获取词法作用域上下文

以数组形式，记录从当前节点向外的层层包裹结构；

经过脱敏处理（如移除函数体、清空成员列表）。

// 检查是否在类方法中
let isInClassMethod = context.lexicalContext.contains { 
    $0.is(FunctionDeclSyntax.self) && 
    $0.parent?.is(ClassDeclSyntax.self) != nil
}

4. node 调用现场信息

每个宏的 expansion 方法，除了 context 外，还会接收一个 node 参数，类型通常是 some SyntaxProtocol（如 FreestandingMacroExpansionSyntax、AttributeSyntax 等）。

它代表了宏的调用现场——也就是源码中触发宏展开的那段语法结构。

简单理解：node 就是“#宏名(...)”或“@宏名” 这一整段的解析结果。

以自由宏为例，node 类型通常是 FreestandingMacroExpansionSyntax，它包含了调用宏时的所有组成元素：

public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
  var pound: TokenSyntax { get set }  // "#" 符号
  var macroName: TokenSyntax { get set }  // 宏名
  var genericArgumentClause: GenericArgumentClauseSyntax? { get set } // 泛型参数
  var leftParen: TokenSyntax? { get set }  // 左括号 "("
  var arguments: LabeledExprListSyntax { get set }  // 参数列表
  var rightParen: TokenSyntax? { get set }  // 右括号 ")"
  var trailingClosure: ClosureExprSyntax? { get set }  // 尾随闭包
  var additionalTrailingClosures: MultipleTrailingClosureElementListSyntax { get set }  // 多个尾随闭包
}

具体能做什么？

通过解析 node，可以在宏内部获取宏调用时传递的信息，从而进行自定义生成：

• 提取参数：解析 arguments，得到用户传入的内容；
• 读取宏名：从 macroName 获取调用者使用的名字（有些宏支持重名扩展）；
• 处理泛型：如果 genericArgumentClause 存在，可以根据泛型参数生成不同代码；
• 解析闭包：支持分析和利用用户传递的尾随闭包；
• 实现自定义行为：比如根据传入参数数量、类型、值，决定生成什么样的代码。

示例

public static func expansion(
    of node: some FreestandingMacroExpansionSyntax,
    in context: some MacroExpansionContext
) throws -> ExprSyntax {
    // 取出第一个参数
    guard let firstArg = node.arguments.first?.expression else {
        throw ASTError("缺少参数")
    }
    
    // 根据参数生成不同表达式
    return "print((firstArg))"
}

小结： node = 宏调用时的源码快照， context = 辅助功能工具箱。

两者结合使用，才能让宏既能理解调用现场，又能灵活地生成对应代码。

5. 输入输出皆基于 Syntax 节点

Swift 宏以结构化 AST（抽象语法树）为基础，输入输出都基于 SwiftSyntax 类型，例如：

• 输入：AttributeSyntax、FreestandingMacroExpansionSyntax、DeclSyntaxProtocol；
• 输出：ExprSyntax、[DeclSyntax]、[AccessorDeclSyntax] 等。

这种设计保证了宏生成的代码具备：

• 与手写代码一致的结构完整性；
• 良好的可分析性与可重构性；
• 自动享受 IDE 语法高亮、错误检测等支持。

Swift 宏不是简单拼接字符串，而是真正生成 AST。

6. 宏只运行于编译时

Swift 宏只能在编译期运行，这意味着它们不能访问运行时信息、全局变量、实例状态或外部服务。所有宏的行为都必须建立在静态源代码、类型系统和语法结构之上。

这为宏提供了如下保证：

• 可预测性：展开结果与运行环境无关，确保行为一致；
• 可分析性：工具链可以分析宏行为，进行语法检查与补全；
• 可维护性：宏代码不会隐藏运行时副作用，有利于重构和测试。

开发者在编写宏时，也应遵循“编译时思维”，尽可能将逻辑转化为静态分析与结构转换。

7. 每种宏的返回类型固定

每个宏协议都明确限定了其 expansion 方法的返回类型，这种限制具有强约束力：

宏协议	返回类型
ExpressionMacro	ExprSyntax
DeclarationMacro	[DeclSyntax]
MemberMacro	[DeclSyntax]
AccessorMacro	[AccessorDeclSyntax]
BodyMacro	[CodeBlockItemSyntax]
ExtensionMacro	[ExtensionDeclSyntax]
MemberAttributeMacro	[AttributeSyntax]

这种强约束带来：

• 类型安全；
• 生成结果合法；
• 避免不同宏角色混淆使用。

比如：成员宏只能生成成员声明，不能直接生成表达式或代码块。

总结

Swift 宏协议的结构化设计，使得宏具备了安全、清晰、灵活的特性。无论你编写哪种类型的宏，理解 expansion 的统一调用模式、context 工具箱能力、node 的语法抽象、以及 Syntax 类型的输入输出机制，都是构建可靠宏逻辑的基础。

在接下来的章节中，我们将深入每一种宏协议（如 ExpressionMacro、DeclarationMacro 等），并结合实际案例，帮助你实现更多有趣且实用的 Swift 宏。