CodableKit ⚡️

CodableKit 是一个 Swift 宏包，旨在简化 Swift 的 Codable 协议的使用，通过轻松集成默认值来减少您需要编写的辅助代码量。

特性

自定义编码键
缺失数据的默认值
解码失败的处理
字符串到结构体的转码
属性忽略
显式 nil 处理
自定义键属性生成

用法

要使用 Codable 宏，只需将 @Codable 属性添加到您的结构体声明中即可。

@Codable
struct Car {
    let brand: String
    let model: String
    var year: Int = 2024
}

通过将 year 属性的默认值设置为 2024，当原始数据不包含该属性时，该值将为 2024。

高级用法

Codable 宏通过 @CodableKey 属性及其相关选项提供了几个附加功能。

自定义编码键：更改属性的编码键。

@CodableKey("uid")
let id: UUID

CodableKeyOptions：使用各种选项自定义属性的行为。

@CodableKey(options: [.useDefaultOnFailure, .transcodeRawString])
var someProperty: SomeType

您可以在 CodableKeyOptions.swift 文件中找到详细信息。

可用选项

.default：默认选项（空集）。
.ignored：在编码和解码期间将忽略该属性。
.explicitNil：在编码和解码时，该键将被显式设置为 nil (null)，而不是被省略。
.generateCustomKey：在使用自定义 CodableKey 时，生成一个计算属性来访问该键。
.transcodeRawString：在编码和解码期间，在原始字符串和目标类型之间转换该值。
.useDefaultOnFailure：当解码或编码失败时，使用默认值（如果已设置）。

示例

这是一个展示各种功能的综合示例

@Codable
struct User {
    @Codable
    struct Car {
        let brand: String
        let model: String
        let year: Int
    }

    @CodableKey("uid")
    let id: UUID

    let name: String

    var age: Int = 24

    @CodableKey(options: .useDefaultOnFailure)
    var avatar: URL? = nil

    @CodableKey(options: .transcodeRawString)
    var car: Car

    @CodableKey(options: .ignored)
    let thisPropertyWillNotBeIncluded: String = "ignored"

    @CodableKey("custom_email", options: .generateCustomKey)
    var email: String

    @CodableKey(options: .explicitNil)
    var optionalField: String?
}

在此示例中

id 使用自定义编码键 "uid"。
age 具有默认值 24。
avatar 在解码失败时使用默认值。
car 从原始字符串转码为 Car 结构体。
thisPropertyWillNotBeIncluded 在编码和解码期间被忽略。
email 使用自定义键 "custom_email" 并生成一个计算属性来访问它。
当 optionalField 为 nil 时，将显式设置为 null，而不是被省略。

安装

.package(url: "https://github.com/WendellXY/CodableKit.git", from: "1.0.0"),

对于那些仍然使用 Swift 5 或具有需要 Swift 5 或 swift-syntax 510.0.0 的依赖项的人，您可以使用以前的 0.x 版本的 CodableKit，它与 Swift 5 兼容，并且应该涵盖最新版本中的大多数功能。请注意，0.x 版本将不再开发，建议升级到最新版本。

.package(url: "https://github.com/WendellXY/CodableKit.git", from: "0.4.0"),

限制

当将此宏应用于基类时，在类定义头中，你不应该向类添加任何继承。否则，此类将被视为具有超类的类，因为宏无法在宏展开期间识别继承是类还是协议。

// Codable will consider the BaseUser as a base class since it does not have any inheritance
@Codable
class BaseUser { }

// Codable will consider the HashableUser as a subclass even if the inheritance just contains a protocol
@Codable
class HashableUser: Hashable { }

// So you have to write the HashableUser like:
@Codable
class HashableUser { }
extension HashableUser: Hashable { }

贡献

请随时为 CodableKit 做出贡献！任何意见和建议都将不胜感激。