Swift Protobuf

欢迎使用 Swift Protobuf!

Apple 的 Swift 编程语言是Google 的 Protocol Buffer（"protobuf"）序列化技术的完美补充。它们都强调高性能和程序员安全。

本项目提供了将 Swift 代码生成添加到 Google 的 protoc 的命令行程序，以及使用生成代码所需的运行时库。使用 protoc 插件从 .proto 文件生成 Swift 代码后，您需要将此库添加到您的项目中。

SwiftProtobuf 的特性

SwiftProtobuf 相比其他序列化系统有许多优势：

安全性：protobuf 代码生成系统避免了手动构建序列化代码常见的错误。
正确性：SwiftProtobuf 通过了自身的广泛测试套件和 Google 的完整 protobuf 一致性测试。
模式驱动：在单独的 .proto 模式文件中定义数据结构清晰地记录了您的通信约定。
符合语言习惯：SwiftProtobuf 充分利用了 Swift 语言的特性。特别是，所有生成的类型都提供完整的 Swift 写时复制值语义。
高效的二进制序列化：.serializedBytes() 方法返回一个包含数据紧凑二进制形式的字节包。您可以使用 init(contiguousBytes:) 初始化器反序列化数据。
标准 JSON 序列化：.jsonUTF8Bytes() 方法返回数据的 JSON 形式，可以使用 init(jsonUTF8Bytes:) 初始化器进行解析。
可哈希、可比较：生成的结构体可以放入 Set<> 或 Dictionary<> 中。
高性能：二进制和 JSON 序列化器已经过广泛优化。
可扩展：您可以为任何生成的类型添加自己的 Swift 扩展。

最重要的是，您可以使用相同的 .proto 文件为其他平台生成 Java、C++、Python 或 Objective-C 代码。这些语言生成的代码将使用与 SwiftProtobuf 完全相同的序列化和反序列化约定，使得在二进制或 JSON 形式下轻松交换序列化数据，无需您额外付出努力。

文档

更多信息可在相关文档中找到：

Google 的 protobuf 文档提供了有关 protocol buffers、protoc 编译器以及如何在 C++、Java 和其他语言中使用 protocol buffers 的一般信息。
PLUGIN.md 文档介绍了为 protoc 程序添加 Swift 支持的 protoc-gen-swift 插件。
API.md 文档介绍了如何使用生成的代码。建议在项目中使用 SwiftProtobuf 的任何人阅读此文档。
INTERNALS.md 文档介绍了生成代码和库的内部结构。这仅对有兴趣研究 SwiftProtobuf 本身的人有用。
STYLE_GUIDELINES.md 文档介绍了我们在代码库中采用的样式指南，如果您有兴趣贡献，可以参考。

入门

如果您之前使用过 Protocol Buffers，添加 Swift 支持非常简单：您只需构建 protoc-gen-swift 程序并将其复制到 PATH 中。 protoc 程序将自动找到并使用它，允许您为 proto 文件构建 Swift 源代码。当然，您还需要将 SwiftProtobuf 运行时库添加到项目中，如下所述。

系统要求

要在 Protocol buffers 中使用 Swift，您需要：

Swift 5.8 或更高版本的编译器（如果使用 Xcode 构建，则需要 Xcode 14.3 或更高版本，App Store 要求）。Swift protobuf 项目正在针对 Swift.org 上提供的最新发布版本的 Swift 进行开发和测试。
Google 的 protoc 编译器。Swift protoc 插件正在针对最新的 protobuf 源代码进行积极开发和测试。SwiftProtobuf 测试需要支持 swift_prefix 选项的 protoc 版本（在 protoc 3.2.0 中引入）。它可能适用于较早版本的 protoc。您可以从 Google 的 github 仓库获取最新版本。

构建和安装代码生成器插件

要将 .proto 文件转换为 Swift，您需要 Google 的 protoc 编译器和 SwiftProtobuf 代码生成器插件。

在任何支持的 Swift 平台上构建插件应该很简单：

git clone https://github.com/apple/swift-protobuf.git
cd swift-protobuf

选择您要使用的 SwiftProtobuf 发布版本。您可以使用以下命令获取标签列表：

git tag -l

选择要使用的版本后，将本地状态设置为匹配，并构建 protoc 插件：

git checkout tags/[tag_name]
swift build -c release

这将在 .build/release 目录中创建一个名为 protoc-gen-swift 的二进制文件。

要安装，只需将这个可执行文件复制到 PATH 环境变量中的某个目录即可。

注意：Swift 运行时支持现在已包含在 macOS 中。如果您使用的是旧版 Xcode 或旧系统版本，可能还需要在 swift build 中使用 --static-swift-stdlib。

或者通过 Homebrew 安装

如果您更喜欢使用 Homebrew：

brew install swift-protobuf

这将安装 protoc 编译器和 Swift 代码生成器插件。

将 .proto 文件转换为 Swift

要为 .proto 文件生成 Swift 输出，请像往常一样运行 protoc 命令，使用 --swift_out=<directory> 选项：

protoc --swift_out=. my.proto

protoc 程序将自动在您的 PATH 中查找 protoc-gen-swift 并使用它。

每个 .proto 输入文件将在输出目录中生成对应的 .pb.swift 文件。

有关构建和使用 protoc-gen-swift 的更多信息，可以在详细的插件文档中找到。

将 SwiftProtobuf 库添加到您的项目...

要使用生成的代码，您需要在项目中包含 SwiftProtobuf 库模块。具体操作方法会因项目的构建方式而异。请注意，在所有情况下，我们强烈建议您使用与用于生成代码的 protoc-gen-swift 版本相对应的 SwiftProtobuf 库版本。

...使用 `swift build`

将 .pb.swift 文件复制到项目后，您需要将 SwiftProtobuf 库添加到项目中以支持生成的代码。如果您使用的是 Swift Package Manager，请在 Package.swift 文件中添加依赖项，并将 SwiftProtobuf 库导入所需的目标中。将这里的 "1.27.0" 调整为与上面用于构建插件的 [tag_name] 匹配：

dependencies: [
    .package(url: "https://github.com/apple/swift-protobuf.git", from: "1.27.0"),
],
targets: [
    .target(
      name: "MyTarget",
      dependencies: [.product(name: "SwiftProtobuf", package: "swift-protobuf")]
    ),
]

...使用 Xcode

如果您使用的是 Xcode，那么您应该：

将从 proto 生成的 .pb.swift 源文件直接添加到您的项目中
将此 SwiftPM 包作为 Xcode 项目的依赖项添加： Apple 文档

...使用 CocoaPods

如果您使用的是 CocoaPods，请将以下内容添加到您的 Podfile 中，调整 :tag 以匹配您用于构建插件的 [tag_name]：

pod 'SwiftProtobuf', '~> 1.0'

然后运行 pod install。

注意：需要 CocoaPods 1.7 或更新版本。

快速入门

一旦您安装了代码生成器，使用它从 .proto 文件生成 Swift 代码，并将 SwiftProtobuf 库添加到您的项目中，您就可以像使用任何其他 Swift 结构体一样使用生成的类型。

例如，您可以从以下非常简单的 proto 文件开始：

syntax = "proto3";

message BookInfo {
   int64 id = 1;
   string title = 2;
   string author = 3;
}

然后使用以下命令生成 Swift 代码：

protoc --swift_out=. DataModel.proto

生成的代码将为每个 proto 字段公开一个 Swift 属性，并提供一系列序列化和反序列化功能：

// 创建一个 BookInfo 对象并填充它：
var info = BookInfo()
info.id = 1734
info.title = "Really Interesting Book"
info.author = "Jane Smith"

// 与上面相同，但生成一个只读值：
let info2 = BookInfo.with {
    $0.id = 1735
    $0.title = "Even More Interesting"
    $0.author = "Jane Q. Smith"
  }

// 序列化为二进制 protobuf 格式：您可以选择序列化为任何符合 SwiftProtobufContiguousBytes 的类型。例如：
let binaryData: Data = try info.serializedBytes()
let binaryDataAsBytes: [UInt8] = try info.serializedBytes()

// 从 `binaryData` 反序列化接收到的 Data 对象
let decodedInfo = try BookInfo(serializedData: binaryData)

// 从 `binaryDataAsBytes` 反序列化接收到的 [UInt8] 对象
let decodedInfo = try BookInfo(serializedBytes: binaryDataAsBytes)

// 序列化为 JSON 格式作为 Data 对象，或任何其他符合 SwiftProtobufContiguousBytes 的类型。例如：
let jsonData: Data = try info.jsonUTF8Data()
let jsonBytes: [UInt8] = try info.jsonUTF8Bytes()

// 从 `jsonBytes` 的 JSON 格式反序列化
let receivedFromJSON = try BookInfo(jsonUTF8Bytes: jsonBytes)