buf-gradle-plugin

本项目提供了将 Buf 与 Gradle 集成的支持。它还支持与 Protobuf Gradle 插件的集成（注意：buf-gradle-plugin 兼容 protobuf-gradle-plugin 版本 >= 0.9.2）。

该插件支持 buf lint、buf format 和 buf generate 的简单用法，以及 buf build 和 buf breaking 之间的自包含集成。

用法

该插件假设已在项目根目录配置了 Buf，并配置了 buf.yaml，有关设置 Buf 工作区的说明请参阅 Buf 文档。

该插件也可以在不指定 buf.yaml 的情况下使用，在这种情况下，插件将扫描所有顶级目录以查找 Protobuf 源文件。

如果项目包含 protobuf-gradle-plugin，该插件将使用一个隐式的 Buf 工作区，其中包含以下内容：

所有指定的 Protobuf 源目录
protobuf-gradle-plugin 提取到 $buildDir/extracted-include-protos 的 include 依赖项
protobuf-gradle-plugin 被指示生成并提取到 $buildDir/extracted-protos 的依赖项

该插件不支持同时使用 Buf 工作区和 protobuf-gradle-plugin，因为依赖项解析会变得复杂且容易出错。

应用该插件：

plugins {
    id("build.buf") version "<version>"
}

或

buildscript {
    dependencies {
        classpath("build.buf:buf-gradle-plugin:<version>")
    }
}

apply(plugin = "build.buf")

应用后，该插件会创建以下任务：

bufFormatApply 应用 buf format
bufFormatCheck 验证 buf format
bufLint 验证 buf lint
bufBuild 使用 buf build 构建镜像
bufBreaking 通过 buf breaking 检查 Protobuf 模式与之前版本之间的向后不兼容变更
bufGenerate 使用 buf generate 生成 Protobuf 代码

Gradle 兼容性

此插件需要 Gradle 8 或更高版本。

示例

本项目中的每个集成测试都是一个使用示例。

配置

对于基本的 Buf 项目或使用 protobuf-gradle-plugin 的项目，您可以在项目目录中创建一个 Buf 配置文件：

# buf.yaml

version: v2
lint:
  ignore:
    - path/to/dir/to/ignore
  use:
    - DEFAULT

作为项目目录中 buf.yaml 文件的替代方案，您可以通过配置扩展来指定 buf.yaml 的位置：

buf {
    configFileLocation = rootProject.file("buf.yaml")
}

或者，您可以跨项目共享 Buf 配置，并通过专用的 buf 配置进行指定：

dependencies {
    buf("build.buf:shared-buf-configuration:0.1.0")
}

例如，这是一个 shared-buf-configuration 项目的设置：

shared-buf-configuration % tree
.
├── build.gradle.kts
└── buf.yaml

// build.gradle.kts

plugins {
    `maven-publish`
}

publishing {
    publications {
        create<MavenPublication>("bufconfig") {
            groupId = "build.buf"
            artifactId = "shared-buf-configuration"
            version = "0.1.0"
            artifact(file("buf.yaml"))
        }
    }
}

使用 Buf 工作区的项目必须按照 Buf 文档中的说明配置其工作区；linting 的配置不可覆盖。项目根目录或扩展中指定的 buf.yaml 仅用于破坏性检查。

依赖项

如果您的 buf.yaml 使用 deps 键声明了任何依赖项，您必须运行 buf mod update 以手动创建 buf.lock 文件。buf-gradle-plugin 目前（尚）不支持创建依赖锁定文件。

`bufGenerate`

bufGenerate 按照 Buf 文档中的描述进行配置。在项目根目录中创建一个 buf.gen.yaml，bufGenerate 将在项目的构建目录 "$buildDir/bufbuild/generated/<out path from buf.gen.yaml>" 中生成代码。

一个使用远程插件进行 Java 代码生成的示例：

version: v2
plugins:
  - plugin: buf.build/protocolbuffers/java:<version>
    out: java

如果要在构建中使用生成的代码，必须将生成的代码添加为源目录，并配置任务依赖，以确保在编译之前生成代码：

// build.gradle.kts

import build.buf.gradle.GENERATED_DIR

plugins {
    `java`
    id("build.buf") version "<version>"
}

// Add a task dependency for compilation
tasks.named("compileJava").configure { dependsOn("bufGenerate") }

// Add the generated code to the main source set
sourceSets["main"].java { srcDir("$buildDir/bufbuild/$GENERATED_DIR/java") }

// Configure dependencies for protobuf-java:
repositories { mavenCentral() }

dependencies {
    implementation("com.google.protobuf:protobuf-java:<protobuf version>")
}

生成依赖项

如果您希望为依赖项生成代码，请配置 bufGenerate 任务：

// build.gradle.kts

buf {
    generate {
        includeImports = true
    }
}

确保你拥有一个由 buf mod update 生成的最新 buf.lock 文件，否则本次生成将会失败。

进一步的生成配置

默认情况下，bufGenerate 会从项目根目录读取 buf.gen.yaml 模板文件。你可以覆盖模板文件的位置：

// build.gradle.kts

buf {
    generate {
        templateFileLocation = rootProject.file("subdir/buf.gen.yaml")
    }
}

`bufFormatApply` 和 `bufFormatCheck`

bufFormatApply 是手动运行的，没有配置。

bufFormatCheck 在 check 任务期间自动运行，前提是 enforceFormat 已启用。它没有其他配置。

buf {
    enforceFormat = true // True by default
}

`bufLint`

bufLint 通过在基础项目或使用 protobuf-gradle-plugin 的项目中创建 buf.yaml 进行配置。它在 check 任务期间自动运行。对于使用工作区的项目，不支持指定 buf.yaml。

`bufBuild`

bufBuild 配置了 build 闭包：

buf {
    build {
        imageFormat = ImageFormat.JSON // JSON by default
        compressionFormat = CompressionFormat.GZ // null by default (no compression)
    }
}

可用的图像格式为：

binpb
bin
json
txtpb

可用的压缩格式为：

gz
zst

该文件在项目的构建目录中的 bufbuild 目录中构建，其名称为 image，后跟图像格式以及可选的压缩格式，例如 build/bufbuild/image.bin.zst。

`bufBreaking`

bufBreaking 更为复杂，因为它需要一个先前版本的 Protobuf schema 来验证当前版本。Buf 内置的 git 集成并不完全足够，因为它需要一个可构建的 Protobuf 源集，而 protobuf-gradle-plugin 的提取步骤通常针对项目构建目录，该目录是临时的且未被提交。

此插件使用 buf build 从当前 Protobuf schema 创建镜像，并将其作为 Maven 发布物发布。在项目的后续构建中，该插件将解析先前发布的 schema 镜像，并针对当前 schema 运行 buf breaking，以该镜像作为参考。

与最新已发布版本进行比对

启用 checkSchemaAgainstLatestRelease 后，该插件将解析先前发布的 Maven 构件作为其验证输入。

例如，首先启用 publishSchema 发布项目：

buf {
    publishSchema = true
}

然后配置插件以检查模式：

buf {
    // Continue to publish the schema
    publishSchema = true

    checkSchemaAgainstLatestRelease = true
}

该插件将运行 Buf 以验证项目当前的 schema：

> Task :bufBreaking FAILED
src/main/proto/buf/service/test/test.proto:9:1:Previously present field "1" with name "test_content" on message "TestMessage" was deleted.

与静态版本进行比对

如果由于某种原因，您不希望动态地针对最新发布的 schema 版本进行比对，您可以使用 previousVersion 指定一个常量版本：

buf {
    // Continue to publish the schema
    publishSchema = true

    // Will always check against version 0.1.0
    previousVersion = "0.1.0"
}

构件详情

默认情况下，已发布的镜像构件会从现有的 Maven 发布中推断其详情（如果存在）。如果不存在、存在多个，或者您希望自行指定详情，则可以对其进行配置：

buf {
    publishSchema = true

    imageArtifact {
        groupId = rootProject.group.toString()
        artifactId = "custom-artifact-id"
        version = rootProject.version.toString()
    }
}

其他配置

可以通过扩展上的 toolVersion 属性来配置所使用的 Buf 版本：

buf {
    toolVersion = <version>
}

贡献

我们非常乐意接受您的帮助，让此插件变得更好！

有关在本地构建插件、运行测试以及向仓库贡献代码的详细说明，请参阅我们的 CONTRIBUTING.md 指南。

生态系统

connect-kotlin：用于惯用 gRPC 和 Connect RPC 的 Kotlin 客户端
connect-es：使用 Protobuf 和 TypeScript 的类型安全 API。
connect-go：GoLang 的服务处理程序和客户端
Buf Studio：用于临时 RPC 的 Web UI

状态

本项目处于 beta 阶段，随着我们从早期采用者那里收集反馈，我们可能会进行一些更改。欢迎加入我们的 Slack！

法律

根据 Apache 2 许可证提供。