CodableWrappers完全指南：用属性包装器简化Swift序列化的终极方案

CodableWrappers完全指南：用属性包装器简化Swift序列化的终极方案

【免费下载链接】CodableWrappersA Collection of PropertyWrappers to make custom Serialization of Swift Codable Types easy项目地址: https://gitcode.com/gh_mirrors/co/CodableWrappers

CodableWrappers是一个强大的Swift库，它通过属性包装器（Property Wrappers）让自定义序列化变得前所未有的简单。无论你是处理复杂的日期格式、特殊的布尔值表示，还是需要灵活的编码键策略，这个库都能提供直观且高效的解决方案，帮助开发者轻松应对各种序列化挑战。

为什么选择CodableWrappers？

在Swift开发中，Codable协议为数据序列化提供了基础支持，但面对实际项目中多样化的序列化需求，原生实现往往显得力不从心。CodableWrappers通过属性包装器这一优雅的设计模式，将复杂的序列化逻辑封装起来，让代码更加清晰、可维护。

核心优势

• ** declarative语法**：用简洁的属性包装器注解代替繁琐的手动编码/解码逻辑
• 丰富的内置解决方案：涵盖日期、数据、布尔值、集合等多种类型的序列化需求
• 高度可定制：轻松扩展以支持项目特有的序列化规则
• 减少样板代码：大幅简化Codable类型的实现

快速开始：安装与基础使用

安装方式

Swift Package Manager（推荐）

在你的Package.swift文件中添加以下依赖：

dependencies: [ .package(url: "https://gitcode.com/gh_mirrors/co/CodableWrappers.git", .upToNextMajor(from: "3.0.0" )), ]

CocoaPods

pod 'CodableWrappers', '~> 3.0.0'

第一个示例

下面是一个简单示例，展示了如何使用CodableWrappers简化用户模型的序列化：

@CustomCodable @SnakeCase struct User: Codable { let firstName: String let lastName: String @SecondsSince1970DateCoding var joinDate: Date @CustomCodingKey("data") var imageData: Data }

在这个例子中：

• @CustomCodable启用自定义编码功能
• @SnakeCase自动将属性名转换为snake_case编码键
• @SecondsSince1970DateCoding将Date类型序列化为时间戳
• @CustomCodingKey("data")为imageData属性指定自定义编码键

强大的编码键策略

CodableWrappers提供了丰富的编码键转换宏，满足各种命名风格需求：

常用编码键宏

自定义编码键

除了预设的命名风格，你还可以使用@CustomCodingKey为单个属性指定任意编码键：

@CustomCodable struct UserProfile: Codable { @CustomCodingKey("user_name") let username: String @CustomCodingKey("registration_date") @ISO8601DateCoding let registerDate: Date }

前缀和后缀

使用@CodingKeyPrefix和@CodingKeySuffix可以为整个结构体或单个属性的编码键添加前缀或后缀：

@CustomCodable @CodingKeyPrefix("user_") struct User: Codable { let name: String // 编码键为 "user_name" let age: Int // 编码键为 "user_age" @CodingKeySuffix("_info") let email: String // 编码键为 "user_email_info" }

数据类型序列化定制

CodableWrappers为各种常见数据类型提供了专门的属性包装器，解决特定的序列化需求。

日期序列化

处理不同格式的日期是序列化中常见的挑战，CodableWrappers提供了多种日期编码方案：

struct Event: Codable { @SecondsSince1970DateCoding var timestamp: Date // 时间戳（秒） @MillisecondsSince1970DateCoding var preciseTime: Date // 时间戳（毫秒） @ISO8601DateCoding var isoDate: Date // ISO8601格式 @DateFormatterCoding<CustomDateCoder> var customDate: Date // 自定义格式 } // 自定义日期编码器示例 struct CustomDateCoder: DateFormatterStaticCoder { static let dateFormatter: DateFormatter = { let formatter = DateFormatter() formatter.dateFormat = "yyyy-MM-dd HH:mm:ss" return formatter }() }

数据（Data）序列化

对于Data类型，最常见的需求是Base64编码：

struct ImageData: Codable { @Base64Coding var image: Data // 自动进行Base64编码/解码 }

布尔值序列化

有时后端API会使用数字或字符串表示布尔值：

struct Settings: Codable { @BoolAsIntCoding var isEnabled: Bool // 1表示true，0表示false @BoolAsStringCoding var isVerified: Bool // "true"表示true，"false"表示false }

集合类型处理

处理包含nil值的集合时，可以使用Lossy系列包装器过滤nil值：

struct DataModel: Codable { @LossyArrayDecoding var tags: [String] // 解码时自动过滤nil值 @LossyDictionaryDecoding var properties: [String: String] // 解码时自动过滤nil值 @LossySetDecoding var categories: Set<String> // 解码时自动过滤nil值 }

高级功能

默认值与回退策略

当数据缺失或无效时，可以使用回退策略提供默认值：

struct Product: Codable { @FallbackDecoding<EmptyString> var name: String // 缺失时使用空字符串 @FallbackCoding<EmptyArray> var tags: [String]? // 缺失或nil时使用空数组 @FallbackEncoding<EmptyInt> var stock: Int? // 为nil时编码为0 // 自定义回退值 @FallbackDecoding<DefaultPriceProvider> var price: Double } struct DefaultPriceProvider: FallbackValueProvider { static var defaultValue: Double { 9.99 } }

忽略编码/解码

使用@OmitCoding可以排除不需要序列化的属性：

struct User: Codable { let id: String let name: String @OmitCoding var temporaryData: String? // 不会被编码或解码 }

只编码或只解码

某些场景下可能只需要编码或解码功能：

struct ReadOnlyData: Decodable { @SecondsSince1970DateDecoding var createdAt: Date // 只解码 } struct WriteOnlyData: Encodable { @SecondsSince1970DateEncoding var updatedAt: Date // 只编码 }

属性可变性控制

使用@Immutable可以创建解码后不可修改的属性：

struct User: Codable { @Immutable @SecondsSince1970DateCoding var createdAt: Date // 解码后不可修改 @SecondsSince1970DateCoding var updatedAt: Date // 可修改 }

自定义序列化逻辑

CodableWrappers的强大之处在于其可扩展性。你可以通过实现StaticCoder协议创建完全自定义的序列化逻辑。

创建自定义编码器

下面是一个将日期编码为纳秒时间戳的示例：

struct NanosecondsSince1970Coder: StaticCoder { static func decode(from decoder: Decoder) throws -> Date { let nanoSeconds = try Double(from: decoder) let seconds = nanoSeconds * 0.000000001 return Date(secondsSince1970: seconds) } static func encode(value: Date, to encoder: Encoder) throws { let nanoSeconds = value.secondsSince1970 / 0.000000001 try nanoSeconds.encode(to: encoder) } } // 使用自定义编码器 typealias NanosecondsSince1970Coding = CodingUses<NanosecondsSince1970Coder> struct Event: Codable { @NanosecondsSince1970Coding var preciseTime: Date }

总结

CodableWrappers通过属性包装器的方式，为Swift Codable提供了强大而灵活的扩展，极大简化了复杂序列化逻辑的实现。无论是处理各种日期格式、转换命名风格，还是实现自定义序列化规则，它都能让代码更加简洁、可读和可维护。

如果你正在寻找一种方式来简化Swift项目中的数据序列化工作，CodableWrappers绝对是一个值得尝试的终极方案！更多详细示例和高级用法，请参考项目中的CustomExamples.md和官方文档。

开始使用CodableWrappers，让Swift序列化工作变得前所未有的简单！ 🚀

【免费下载链接】CodableWrappersA Collection of PropertyWrappers to make custom Serialization of Swift Codable Types easy项目地址: https://gitcode.com/gh_mirrors/co/CodableWrappers