Pbandk 使用指南

1. 项目介绍

Pbandk 是一个专为 Kotlin 多平台设计的 Protocol Buffers 代码生成器及运行时库。此项目旨在从 .proto 定义文件自动生成符合 Kotlin 编程习惯的数据类，并支持在 JVM、Android、iOS、JavaScript、WebAssembly 等所有由 Kotlin Multiplatform 支持的平台上运行。Pbandk 强调遵循 Kotlin 的编程规范，提供易用且与平台兼容的API，同时也考虑到与其他语言如Java、Swift等的互操作性，尽管这受限于当前Kotlin多平台的限制。

2. 项目快速启动

添加依赖

首先，在你的 Kotlin 多平台项目中，确保你已经配置了 Protobuf 插件和添加了 Pbandk 作为依赖。以下是在 Gradle 中如何配置的示例：

 repositories {
    mavenCentral()
    // 如果使用的是SNAPSHOT版本，则还需要添加下面的仓库
    maven { url 'https://s01.oss.sonatype.org/content/repositories/snapshots/' }
}

dependencies {
    implementation("com.streem.pbandk:pbandk-runtime:0.16.1")
}

创建 .proto 文件

创建一个简单的 .proto 文件，比如 addressbook.proto:

syntax = "proto3";
package tutorial;

message Person {
    string name = 1;
    int32 id = 2;
    string email = 3;
    repeated PhoneNumber phones = 4;
}

message PhoneNumber {
    string number = 1;
    enum PhoneType {
        MOBILE = 0;
        HOME = 1;
        WORK = 2;
    }
    PhoneType type = 2;
}

message AddressBook {
    repeated Person people = 1;
}

生成 Kotlin 代码

你需要通过 Protobuf 编译器并结合 Pbandk 的插件来生成 Kotlin 代码。这通常通过Gradle插件自动完成，具体步骤依据项目的构建脚本而定。一旦配置正确，执行相应的编译任务后，会自动生成对应的 Kotlin 类在指定的包路径下。

3. 应用案例和最佳实践

使用 Pbandk 生成的 Person 示例数据类，你可以这样创建一个新的 Person 实例并序列化它：

import tutorial.Person

val johnDoe = Person(name = "John Doe", id = 1, email = "[e-mail]")
val bytes = pbandk.MessageWriter(johnDoe).toByteArray()

最佳实践中，你应该充分利用 Kotlin 的特性，如利用密封类处理 oneof 情况，以及通过 Ktor 或其他网络库将生成的消息高效地发送到服务器。

4. 典型生态项目

Pbandk 虽然主要聚焦于 Kotlin Multiplatform 环境中的 Protobuf 支持，但其在多平台服务端和客户端通信领域有着广泛的应用潜力。例如，结合 Ktor 开发RESTful服务，或是作为微服务架构中服务间通信的基础，利用其生成的代码进行高效的数据序列化和反序列化。

在实际开发中，你可能会遇到需要与gRPC服务交互的情况。虽然Pbandk本身不直接生成gRPC代码，但它提供了接口允许开发者实现自己的服务代码生成逻辑，从而与gRPC生态无缝对接。

通过以上介绍，你应该能够快速上手 Pbandk，将其融入你的多平台项目中，享受高效且一致的跨平台数据交换体验。