MetaCodable

使用宏增强 Swift 的 Codable 实现。

概述

MetaCodable 框架提供了自定义宏，可用于生成动态 Codable 实现。该框架的核心是 Codable() 宏，它在其他宏提供的数据辅助下生成实现。

MetaCodable 旨在通过提供以下内置功能来增强您的 Codable 实现：

允许使用 CodedAt(_:) 传递单个参数为每个变量声明自定义 CodingKey 值，而不是要求您编写所有 CodingKey 值。
允许使用 CodedAt(_:) 和 CodedIn(_:) 为嵌套的 CodingKey 值创建扁平化模型。
允许使用不带参数的 CodedAt(_:) 创建多个 Codable 类型的组合。
允许使用 CodedAs(_:_:) 提供的额外回退 CodingKey 读取数据。
允许在解码失败时使用 Default(_:) 提供默认值，或仅在缺少值时使用 Default(ifMissing:) 提供默认值。也可以使用 Default(ifMissing:forErrors:) 分别为缺少值和其他错误提供不同的默认值。
允许使用 HelperCoder 创建自定义解码/编码策略，并使用 CodedBy(_:) 应用它们。例如 LossySequenceCoder 等。
允许使用 CodedAs(_:_:) 指定不同的情况值，并使用 CodedAs() 指定与 String 不同的情况值/协议类型标识符类型。
允许使用 CodedAt(_:) 指定枚举情况/协议类型标识符路径，使用 ContentAt(_:_:) 指定情况内容路径。
允许使用 UnTagged() 解码/编码缺少每个情况数据的独特标识符的枚举。
允许使用 IgnoreCoding()、IgnoreDecoding() 和 IgnoreEncoding() 从解码/编码中忽略特定属性/情况。允许使用 IgnoreEncoding(if:) 基于自定义条件忽略编码。
允许根据 Swift API 设计指南为变量使用驼峰命名法，同时允许类型/情况使用 CodingKeys(_:) 支持不同大小写风格的键。
允许使用 IgnoreCodingInitialized() 从解码/编码中忽略类型/情况的所有已初始化属性，除非通过附加任何编码属性（如 CodedIn(_:)、CodedAt(_:)、CodedBy(_:)、Default(_:) 等）明确要求解码/编码。
允许使用 MetaProtocolCodable 构建工具插件从 DynamicCodable 类型生成协议解码/编码 HelperCoder。

要求

平台	最低 Swift 版本	安装	状态
iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+	5.9	Swift Package Manager, CocoaPods	完全测试
Linux	5.9	Swift Package Manager	完全测试
Windows	5.9.1	Swift Package Manager	完全测试

安装

<details> <summary><h3>Swift Package Manager</h3></summary>

Swift Package Manager 是一个用于自动分发 Swift 代码的工具，并集成在 swift 编译器中。

一旦设置好 Swift 包，添加 MetaCodable 作为依赖项就像将其添加到 Package.swift 的 dependencies 值中一样简单。

.package(url: "https://github.com/SwiftyLab/MetaCodable.git", from: "1.0.0"),

然后，您可以通过将 MetaCodable 模块产品添加到 target 的 dependencies 值中，将其作为依赖项添加到您选择的 target 中。

.product(name: "MetaCodable", package: "MetaCodable"),

</details> <details> <summary><h3>CocoaPods</h3></summary>

CocoaPods 是 Cocoa 项目的依赖管理器。有关使用和安装说明，请访问他们的网站。要将 MetaCodable 集成到您的 Xcode 项目中使用 CocoaPods，请在 Podfile 中指定：

pod 'MetaCodable'

</details>

使用

MetaCodable 允许摆脱一些典型的 Codable 实现中经常需要的样板代码，具有以下特性：

<details> <summary>每个变量的自定义 CodingKey 值声明，而不是要求您为所有字段编写。</summary>

例如，在官方文档中，要为 Landmark 类型的 2 个字段定义自定义 CodingKey，你必须编写：

struct Landmark: Codable {
    var name: String
    var foundingYear: Int
    var location: Coordinate
    var vantagePoints: [Coordinate]

    enum CodingKeys: String, CodingKey {
        case name = "title"
        case foundingYear = "founding_date"
        case location
        case vantagePoints
    }
}

但使用 MetaCodable，你只需要编写：

@Codable
struct Landmark {
    @CodedAt("title")
    var name: String
    @CodedAt("founding_date")
    var foundingYear: Int

    var location: Coordinate
    var vantagePoints: [Coordinate]
}

</details> <details> <summary>为嵌套的 CodingKey 值创建扁平化模型。</summary>

例如，在官方文档中，要解码这样的 JSON：

{
  "latitude": 0,
  "longitude": 0,
  "additionalInfo": {
      "elevation": 0
  }
}

你必须编写所有这些样板代码：

struct Coordinate {
    var latitude: Double
    var longitude: Double
    var elevation: Double

    enum CodingKeys: String, CodingKey {
        case latitude
        case longitude
        case additionalInfo
    }

    enum AdditionalInfoKeys: String, CodingKey {
        case elevation
    }
}

extension Coordinate: Decodable {
    init(from decoder: Decoder) throws {
        let values = try decoder.container(keyedBy: CodingKeys.self)
        latitude = try values.decode(Double.self, forKey: .latitude)
        longitude = try values.decode(Double.self, forKey: .longitude)

        let additionalInfo = try values.nestedContainer(keyedBy: AdditionalInfoKeys.self, forKey: .additionalInfo)
        elevation = try additionalInfo.decode(Double.self, forKey: .elevation)
    }
}
extension Coordinate: Encodable {
    func encode(to encoder: Encoder) throws {
        var container = encoder.container(keyedBy: CodingKeys.self)
        try container.encode(latitude, forKey: .latitude)
        try container.encode(longitude, forKey: .longitude)

        var additionalInfo = container.nestedContainer(keyedBy: AdditionalInfoKeys.self, forKey: .additionalInfo)
        try additionalInfo.encode(elevation, forKey: .elevation)
    }
}

但使用`MetaCodable`，你只需要写以下代码：

```swift
@Codable
struct Coordinate {
    var latitude: Double
    var longitude: Double

    @CodedAt("additionalInfo", "elevation")
    var elevation: Double
}

你甚至可以使用CodedIn宏进一步简化，因为最后的CodingKey值与字段名相同：

@Codable
struct Coordinate {
    var latitude: Double
    var longitude: Double

    @CodedIn("additionalInfo")
    var elevation: Double
}

为解码失败时提供默认值。

如果遇到缺失数据或类型不匹配，你可以提供一个默认值来代替抛出错误。以下是使用MetaCodable的定义：

@Codable
struct CodableData {
    @Default("some")
    let field: String
}

当提供空JSON（{}）或类型不匹配的JSON（{ "field": 5 }）时，不会抛出任何错误。在这种情况下，将会赋予默认值。

此外，还可以生成使用该字段默认值的成员初始化器。

@Codable
@MemberInit
struct CodableData {
    @Default("some")
    let field: String
}

生成的成员初始化器将如下所示：

init(field: String = "some") {
    self.field = field
}

使用或创建自定义辅助工具来提供自定义解码/编码。

库提供以下辅助工具来解决常见的自定义解码/编码需求：

LossySequenceCoder用于解码序列中的有效数据，同时忽略无效数据，而不是传统方式完全失败解码。
ValueCoder用于解码Bool、Int、Double、String等基本类型，即使它们以其他类型表示，例如从"1"解码Int，从"yes"解码布尔值等。
使用UNIX时间戳（Since1970DateCoder）或日期格式化器（DateCoder、ISO8601DateCoder）进行自定义日期解码/编码。
Base64Coder用于解码/编码base64字符串表示的数据。

更多详情，请参阅HelperCoders的完整文档。

你甚至可以通过遵循HelperCoder协议来创建自己的辅助工具。

以外部/内部/相邻标记或缺乏任何标记的形式表示具有变化的数据，使用单个枚举，每个case作为一个变体，或使用协议类型（不支持缺乏标记）在模块间通过一致性进行变化。

例如，虽然Swift编译器仅生成假设外部标记枚举的实现，只有以下数据：

[
  {
    "load": {
      "key": "MyKey"
    }
  },
  {
    "store": {
      "key": "MyKey",
      "value": 42
    }
  }
]

可以用当前编译器实现通过以下enum表示：

enum Command {
    case load(key: String)
    case store(key: String, value: Int)
}

而MetaCodable允许以下两种格式的数据也能用上述enum表示：

[
  {
    "type": "load",
    "key": "MyKey"
  },
  {
    "type": "store",
    "key": "MyKey",
    "value": 42
  }
]

[
  {
    "type": "load",
    "content": {
      "key": "MyKey"
    }
  },
  {
    "type": "store",
    "content": {
      "key": "MyKey",
      "value": 42
    }
  }
]