Swift Macros 元编程为Codable解码提供默认值

前言

在WWDC2023中，Apple向我们介绍了Swift官方的元编程工具”Swift Macros”，与之前社区中的Sourcery相比，具有以下几个优点：

1. 调用便捷：使用Swift Macros时，编译器会提供提示，无需硬编码。
2. 支持注解：类似Sourcery的注解，Swift Macros支持通过自定义宏实现注解，几乎可以实现任何功能。
3. 宏展开细节隐藏：Swift Macros完全隐藏了宏展开之后的代码，并支持随时在XCode中展开宏以查看具体代码。
4. 使用Swift编写：编写宏的过程完全使用Swift语言，上手难度低，并且支持在单元测试中进行断点调试，方便调试。
5. 支持单元测试：Swift Macros提供了对单元测试的支持。
6. 完全开源：swift-syntax 是一个开源库。

但是目前Swift Macros的依赖库 github.com/apple/swift… 不支持Cocoapods，目前仅支持SPM集成。

本文介绍了如何使用 Swift Macros 去解决 Swift Codable 解码时难以设置默认值的问题。

Codable

当将一个 JSON/Dictionary 数据转化为 Swift 的 Model 时，我们优先考虑使用Codable，但是如果在解码过程中，原数据中缺少某个值（container中key不存在）或者某个值解码失败（key存在，但是对应的值类型不对）都会导致整个解析链失败。理想的状态下我们希望为一个属性设置一个默认值，当其解码失败时，直接取默认值即可。

下面是一个使用Codable解码的例子：

struct People: Codable {
	let name: String
	let age: Int
}


let peopleDic: [String: Any] = ["name": "lfc", "age": 25]



do {
  let value: People = try decode(peopleDic)
  print(value)
} catch {
  print("Error: \(error)")
}


func decode<T: Codable>(_ dic: [String: Any]) throws -> T {
  let jsonData = try JSONSerialization.data(withJSONObject: dic, options: [])
  return try JSONDecoder().decode(T.self, from: jsonData)
}

但是如果字典中缺少某个属性对应的key，比如：

let dic: [String: Any] = ["name": "lfc"]

或者某个key对应的值无法正常解析:

let dic: [String: Any] = ["name": 123, age: true]

都会导致整个值解析失败。对于缺少key的情况，一种简单的方案是使用可选值：

struct People: Codable {
	let name: String?
	let age: Int?
}

这样在从container寻找不到key的时候，会默认赋值为nil，但这样导致使用起来相当麻烦，每次使用此可选值都要进行解包，或者在上层进行封装。

而且如果container 中 key存在但对应的值是个错误类型（或其他情况导致此值解码失败），整个值依旧会解析失败，因为只要key在container中存在，对应的解码就会发生。

一种最可靠的方法是手动为People实现Codable：

extension People: Codable {
	public enum CodingKeys: String, CodingKey {
    case name
    case age
  }

  public init(from decoder: Decoder) throws {
    let container = try decoder.container(keyedBy: CodingKeys.self)
    name = (try? container.decode(String.self, forKey: .name)) ?? ""
    age = (try? container.decode(Int.self, forKey: .age)) ?? 0
  }


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

}

这样不但可以在某个值解析失败的时候赋一个默认值，还可以自定义 codingKey。但需要为每一个需要编解码的模型实现这部分的代码，虽然新版的XCode已经可以自动补全这些方法，但是后续改动数据结构，都需要去重新更改每一个方法的细节，想一想就是一件很恶心的事情。那么有没有更好的方式去为 Decodable 的属性添加解码的默认值呢。

属性包装器

有一种方式是通过属性包装器在 Decodable 属性的 getter 方法中进行处理，详细细节可以参考：onevcat.com/2020/11/cod…

但这种方式有以下弊端：

• 需要手动为每一个属性添加属性包装器。
• 无法自定义 CodingKeys。
• 由于默认值在 init(from: Decoder) 中赋值，此时无法获取property wrapper传入的参数值，所以默认值只能提前定义好全局静态变量，不够灵活，对于不同的业务场景需要不同的默认值时，只能不停的添加新的全局静态变量。

元编程Sourcery

Sourcery 是一个 Swift 代码生成的开源命令行工具，它 (通过 SourceKitten) 使用 Apple 的 SourceKit 框架，来分析你的源码中的各种声明和标注，然后套用你预先定义的 Stencil 模板 (一种语法和 Mustache 很相似的 Swift 模板语言) 进行代码生成。

安装 Sourcery 非常简单，brew install sourcery 即可。不过，如果你想要在实际项目中使用这个工具的话，建议直接从发布页面下载二进制文件，放到 Xcode 项目目录中，然后添加 Run Script 的 Build Phase 来在每次编译的时候自动生成。

可以通过编写模版代码的方式为Codale的类型自动生成CodingKeys init(from: Decoder) 以及encode(to: Encoder)。

Codable 替换方案

sourcery的缺点如下：

• 编写模版时不能调试，编写/上手困难，后续维护难度大。
• 多个cocoapod库依赖同一个模版时，偶尔发生将A库的代码生成的B库中的错误。

Swift Macros

下面我们详细介绍如何使用 Swift Macros 为Codable添加默认值。

自动生成默认值的宏

定义 IcarusCodable 协议

循序渐进，我们首先自定义一个协议 IcarusCodable 这个协议继承自Codable并包含一个默认值的方法：

public portocol IcarusCodable: Codable {
	static var defaultValue: Self { get }
}

所有遵循此协议的方法都可以通过 .defaultVaule 获取默认值。

为基本类型实现 IcarusCodable

我们为一些常用的基本类型实现此协议，这很有用，使得接下来的实现中，所有由这些基本类型构成的类型都可以自动生成自己的默认值:

extension Int: IcarusCodable {
  public static var defaultValue: Int { 0 }
}


extension String: IcarusCodable {
  public static var defaultValue: String { "" }
}

extension Double: IcarusCodable {
  public static var defaultValue: Double { 0.0 }
}


extension Bool: IcarusCodable {
  public static var defaultValue: Bool { false }
}


extension Optional: IcarusCodable where Wrapped: IcarusCodable {
  public static var defaultValue: Optional<Wrapped> { .none }
}


extension Dictionary: IcarusCodable where Value: IcarusCodable, Key: IcarusCodable {
  public static var defaultValue: Dictionary<Key, Value> { [:] }
}

extension Array: IcarusCodable where Element: IcarusCodable {
  public static var defaultValue: Array<Element> { [] }
}

实现添加默认值的宏

下面我们就可以为所有属性都为 IcarusCodable 的类型实现一个自动添加默认值的宏，效果大概像这样：

@icarusCodable

struct Student {

  let name: String

  let age: Int
  let address: String?
  let isBoarder: Bool
	// === 宏展开开始 ===
	private init(_name: String, _age: Int, _address: String?, _isBoarder: Bool) {
    self.name = _name
    self.age = _age
    self.address = _address
    self.isBoarder = _isBoarder
	}


	public static var defaultValue: Self {
    Self (_name: String.defaultValue, _age: Int.defaultValue, _address: String?.defaultValue, _isBoarder: Bool.defaultValue)
	}
	// === 宏展开结束 ===
}

// === 宏展开开始 ===
extension Student : IcarusCodable
// === 宏展开结束 ===

• 首先实现 ConformanceMacro 自动展开 extension XXX : IcarusCodable { }:

  public struct AutoCodableMacro: ConformanceMacro { 
  	public static func expansion(
  
      of node: AttributeSyntax,
  
      providingConformancesOf declaration: some DeclGroupSyntax,
      in context: some MacroExpansionContext) throws -> [(TypeSyntax, GenericWhereClauseSyntax?)] {
        let type = TypeSyntax(stringLiteral: "IcarusCodable")
        return [(type, nil)]
      }
  
  }
  
  
  

  ConformanceMacro 用于使某个类型遵循某个协议。

  需要在 expansion 方法中返回遵循的协议类型和协议泛型限定描述的元组的一个数组 [(TypeSyntax, GenericWhereClauseSyntax?)] ，每一个元组都会为类型添加一个 conformance。

  这里我们只需要让类型遵循 IcarusCodable 即可，所以只需要返回

  [(TypeSyntax(stringLiteral: "IcarusCodable"), nil)]
  

• 然后实现 defaultValue，由于class/struct 不一定存在默认通用的构造器，我们自定义一个私有构造器，并使用’_’避免重名：

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

  MemberMacro 用于为对象添加成员属性/方法。

  我们一共需要添加两个 member，一个私有构造器，以及一个get only的计算属性。

  • 首先我们从 DeclGroupSyntax 中获取类型的存储属性：

    // get stored properties
        let storedProperties: [VariableDeclSyntax] = try {
          if let classDeclaration = declaration.as(ClassDeclSyntax.self) {
            return classDeclaration.storedProperties()
          } else if let structDeclaration = declaration.as(StructDeclSyntax.self) {
            return structDeclaration.storedProperties()
          } else {
            throw CodableError.invalidInputType
          }
        }()
    

    此处我们将 DeclGroupSyntax 转化为 ClassDeclSyntax或StructDeclSyntax 并获取其存储属性。(storedProperties()是一个拓展方法，具体见完整代码)

  • 然后我们获取存储属性的属性名和类型：

    // unpacking the property name and type of a stored property
        let arguments = storedProperties.compactMap { property -> (name: String, type: TypeSyntax)? in
          guard let name = property.name, let type = property.type
          else { return nil } 
          return (name: name, type: type)
    

    其中 property.name 和 property.type 为拓展计算属性，具体见完整代码。

  • 然后构造私有构造器：

    // MARK: - _init
        let _initBody: ExprSyntax = "\(raw: arguments.map { "self.\($0.name) = _\($0.name)" }.joined(separator: "\n"))"
        let _initDeclSyntax = try InitializerDeclSyntax(
          PartialSyntaxNodeString(stringLiteral: "private init(\(arguments.map { "_\($0.name): \($0.type)" }.joined(separator: ", ")))"),
          bodyBuilder: {
            _initBody
          }
        )
    

    InitializerDeclSyntax 用于描述构造器节点，ExprSyntax 用于描述表达式节点。

  • 构造计算属性：

    // MARK: - defaultValue
        let defaultBody: ExprSyntax = "Self(\(raw: arguments.map { "_\($0.name): \($0.defaultValue ?? $0.type.defaultValueExpression)" }.joined(separator: ",")))"
        let defaultDeclSyntax: VariableDeclSyntax = try VariableDeclSyntax("public static var defaultValue: Self") {
          defaultBody
        }
    

    VariableDeclSyntax 用于描述变量节点

  • 最后将这两个 DeclSyntax 返回即可:

    return [
    	DeclSyntax(_initDeclSyntax),
    	DeclSyntax(defaultDeclSyntax)
    ]
    

• 最后我们需要在桥接文件中声明这个宏：

  @attached(conformance)
  
  @attached(member, names: named(`init`), named(defaultValue))
  public macro icarusCodable() = #externalMacro(module: "IcarusMacros", type: "AutoCodableMacro")
  
  

  这表示这个宏不需要参数，并且为类型添加了新的 conformance，以及添加了两个新的成员：init 和defaultValue 。

语法树

如果你不了解 StructDeclSyntax 的具体结构，可以通过编写单元测试，然后进行断点调试：

func testAutoCodable() {
    assertMacroExpansion(
      #"""
      struct People { }
      
      @icarusCodable
      struct Student{
        let name: String
        let age: Int
        let address: String?
        let isBoarder: Bool
      }
      """#
      ,
      expandedSource: "",
      macros: testMacros)
  }

通过断点调试输出语法树，我们可以看到 StructDeclSyntax 的语法树大概长这样：

其中每个节点的含义：

• AttributeListSyntax：添加的宏列表，你可以在这里找到所有添加的宏以及描述宏的参数，比如上面的例子中可以看到一个 name 为 icarusCodable 的宏。
• structKeyword：表示其类型为 struct。
• identifier：对象名。
• MemberDeclBlockSyntax： 成员构造节点。
• MemberDeclListSyntax：成员列表。
• MemberDeclListItemSyntax： 每一个成员的详细信息。

在其中可以解析出每个存储属性的属性名和类型。

通过自定义注解宏注入参数

现在我们实现了一个可以自动生成默认值的宏，但是生成的默认值都是提前定义好的不变的值，我们希望可以任意自定义默认值以应对不同的业务场景。

通过语法树解析，可以知道在类型节点的 AttributeListSyntax 中可以获取到自定义宏的详细信息，于是我们自定义一个不做展开的注解宏：

// Annotation macro, unexpanded
public struct AutoCodableAnnotation: PeerMacro {
  public static func expansion(
    of node: AttributeSyntax,
    providingPeersOf declaration: some DeclSyntaxProtocol,
    in context: some MacroExpansionContext) throws -> [DeclSyntax] {
      return []
    }

}

在桥接文件中我们声明这个宏：

@attached(peer)

public macro icarusAnnotation<T: IcarusCodable>(default: T) = #externalMacro(module: "IcarusMacros", type: "AutoCodableAnnotation")

这表示这个宏接受一个 IcarusCodable 类型的参数。

接下来我们对 AutoCodableMacro 稍作修改，去获取添加在存储属性上的 icarusAnnotation。

let arguments = storedProperties.compactMap { property -> (name: String, type: TypeSyntax, defaultValue: String?)? in
      guard let name = property.name, let type = property.type
      else { return nil }
      var defaultValue: String?
      // find the icarusAnnotation annotation tag
      guard let attribute = property.attributes?.first(where: { $0.as(AttributeSyntax.self)!.attributeName.description == "icarusAnnotation" })?.as(AttributeSyntax.self),
            let arguments = attribute.argument?.as(TupleExprElementListSyntax.self)
      else { return (name: name, type: type, defaultValue: defaultValue) }
      // extracting the key and default values from the annotation and parsing them according to the syntax tree structure.
      arguments.forEach {
        let argument = $0.as(TupleExprElementSyntax.self)
        let expression = argument?.expression.as(StringLiteralExprSyntax.self)
        let segments = expression?.segments.first?.as(StringSegmentSyntax.self)
        switch argument?.label?.text {
        case "default": defaultValue = argument?.expression.description
        default: break
        }
      }
      // the property name is used as the default key
      return (name: name, type: type, defaultValue: defaultValue)
    }

通过property.attributes 我们获取到添加在存储属性上，名为icarusAnnotation 的宏的参数列表中 default 的值。当然，这是一个可选值，当它不存在时，默认使用IcarusCoable.defaultValue。

let defaultBody: ExprSyntax = "Self(\(raw: arguments.map { "_\($0.name): \($0.defaultValue ?? $0.type.defaultValueExpression)" }.joined(separator: ",")))"

效果如下：

@icarusCodable

struct Student {

  let name: String

  @icarusAnnotation(default: 100)
  let age: Int
  let address: String?
  @icarusAnnotation(default: true)
  let isBoarder: Bool
// === 宏展开开始 ===
	private init(_name: String, _age: Int, _address: String?, _isBoarder: Bool) {
    self.name = _name
    self.age = _age
    self.address = _address
    self.isBoarder = _isBoarder
	}


	public static var defaultValue: Self {
    Self (_name: String.defaultValue, _age: 100, _address: String?.defaultValue, _isBoarder: true)
	}
// === 宏展开结束 ===
}
// === 宏展开开始 ===
extension Student : IcarusCodable  {}
// === 宏展开结束 ===

为 IcarusCodable 实现 Codable

在此基础之上，我们继续为 AutoCodableMacro 添加三个成员: CodingKeys init(from: Decoder) encode(to: Encoder) ，同时为了可以实现自定义CodingKeys，首先给注解宏增加一个参数：

@attached(peer)

public macro icarusAnnotation<T: IcarusCodable>(key: String? = nil, default: T) = #externalMacro(module: "IcarusMacros", type: "AutoCodableAnnotation")
@attached(peer)
public macro icarusAnnotation(key: String) = #externalMacro(module: "IcarusMacros", type: "AutoCodableAnnotation")

新增参数 key: String? 表示此属性对应的编码键值，为可选类型，未设置时，默认取变量名。

• CodingKeys:

  // MARK: - CodingKeys
  let defineCodingKeys = try EnumDeclSyntax(PartialSyntaxNodeString(stringLiteral: "public enum CodingKeys: String, CodingKey"), membersBuilder: {
    DeclSyntax(stringLiteral: "\(arguments.map { "case \($0.key)" }.joined(separator: "\n"))")
  })
  

• Decoder:

  // MARK: - Decoder
  let decoder = try InitializerDeclSyntax(PartialSyntaxNodeString(stringLiteral: "public init(from decoder: Decoder) throws"), bodyBuilder: {
    DeclSyntax(stringLiteral: "let container = try decoder.container(keyedBy: CodingKeys.self)")
  	for argument in arguments {
  	  ExprSyntax(stringLiteral: "\(argument.name) = (try? container.decode(\(argument.type).self, forKey: .\(argument.key))) ?? \(argument.defaultValue ?? argument.type.defaultValueExpression)")
  	}
  })
  

• Encoder:

  // MARK: - Encoder
  let encoder = try FunctionDeclSyntax(PartialSyntaxNodeString(stringLiteral: "public func encode(to encoder: Encoder) throws"), bodyBuilder: {
    let expr: String = "var container = encoder.container(keyedBy: CodingKeys.self)\n\(arguments.map { "try container.encode(\($0.name), forKey: .\($0.key))" }.joined(separator: "\n"))"
  	DeclSyntax(stringLiteral: expr)
  })
  

拓展桥接文件的宏声明:

@attached(conformance)

@attached(member, names: named(`init`), named(defaultValue), named(CodingKeys), named(encode(to:)), named(init(from:)))
public macro icarusCodable() = #externalMacro(module: "IcarusMacros", type: "AutoCodableMacro")

最终效果：

@icarusCodable

struct Student {
  @icarusAnnotation(key: "new_name")
  let name: String
  @icarusAnnotation(default: 100)
  let age: Int
  @icarusAnnotation(key: "new_address", default: "abc")
  let address: String?
  @icarusAnnotation(default: true)
  let isBoarder: Bool
// === 宏展开开始 ===
public enum CodingKeys: String, CodingKey {
    case new_name
    case age
    case new_address
    case isBoarder
}


public init(from decoder: Decoder) throws {
    let container = try decoder.container(keyedBy: CodingKeys.self)
    name = (try? container.decode(String.self, forKey: .new_name)) ?? String.defaultValue
    age = (try? container.decode(Int.self, forKey: .age)) ?? 100
    address = (try? container.decode(String?.self, forKey: .new_address)) ?? "abc"
    isBoarder = (try? container.decode(Bool.self, forKey: .isBoarder)) ?? true
}

public func encode(to encoder: Encoder) throws {
    var container = encoder.container(keyedBy: CodingKeys.self)
    try container.encode(name, forKey: .new_name)
    try container.encode(age, forKey: .age)
    try container.encode(address, forKey: .new_address)
    try container.encode(isBoarder, forKey: .isBoarder)
}

private init(_name: String, _age: Int, _address: String?, _isBoarder: Bool) {
    self.name = _name
    self.age = _age
    self.address = _address
    self.isBoarder = _isBoarder
}

public static var defaultValue: Self {
    Self (_name: String.defaultValue, _age: 100, _address: "abc", _isBoarder: true)
}
// === 宏展开结束 ===
}
// === 宏展开开始 ===
extension Student : IcarusCodable  {}
// === 宏展开结束 ===

可以看到，在从container中解码失败时，会自动赋值为默认值，而不会抛出错误导致整个类型解码失败。

关于默认的默认值

默认的默认值是指没有在注解中特地声明默认值时，宏所获取的默认值。它默认从IcarusCodable协议中的 defaultValue 中取值，所以在使用时，需要提前为所有的基本类型实现此协议，并声明这些 默认的默认值。

你可以在你的项目中自由的定义这些默认的默认值。

类型中包含自定义类型

只要包含的自定义类型也是 IcarusCodable 类型，那么宏就可以正常展开，否则，你需要手动为此类型实现 IcarusCodable 协议。

@icarusCodable

struct Address {
  let country: String
  let province: String
  let city: String
}




@icarusCodable
struct Student {
  @icarusAnnotation(key: "new_name")

  let name: String

  @icarusAnnotation(default: 100)

  let age: Int

  let address: Address

  @icarusAnnotation(default: true)

  let isBoarder: Bool

}

关于枚举

宏不适用于枚举类型，但如果自定义类型中包含枚举类型，请使此枚举遵循并手动实现 IcarusCodable:

enum Sex: IcarusCodable {
  case male
  case female
  
  static var defaultValue: Sex { .male }
}




@icarusCodable
struct Student {
  @icarusAnnotation(key: "new_name")

  let name: String

  @icarusAnnotation(default: 100)

  let age: Int

  let address: Address

  @icarusAnnotation(default: true)

  let isBoarder: Bool

  let sex: Sex
}

总结

使用宏为codable自动生成默认值的优缺点：

• 优点：

  • 可以自定义CodingKeys。
  • 可以任意自定义默认值。
  • 开发宏时支持断点调试、支持宏的单元测试，后续维护简单。
  • 宏完全使用swift编写。

• 缺点：

  • swift-syntax 目前不支持 cocoapods，仅能通过SPM集成。

如果你的项目支持 SPM，那么使用宏会让你的代码更加简洁漂亮。

文中使用的完整代码：github.com/ssly1997/Ic…