解决的问题

• API 设计通常不一致
• 依赖管理通常是事后才想到的
• 不强制执行向前和向后兼容性
• proto文件分发是一个困难的、未解决的过程
• 工具生态系统是有限的

Buf Schema Registry

proto文件的托管平台，方便proto文件的分发

buf CLI

• 一种新开发的高性能 Protobuf 编译器。
• 强制执行良好的 API 设计选择和结构的linter。
• 在源代码或线路级别强制兼容性的重大更改检测器。
• 基于可配置模板调用插件的生成器。

buf build

• 验证一切设置是否正确，运行后没有输出意味着当前目录中定义的所有.proto文件都成功编译。

• buf mod init：创建buf.yaml

  version: v1
  deps:
  - buf.build/googleapis/googleapis
  lint:
  use:
    - DEFAULT
  breaking:
  use:
    - FILE

• 可引入网上公开的依赖

  deps:
  - buf.build/googleapis/googleapis

• 仅编译某一个type

  buf build \
  --type acme.weather.v1.Units \
  --type acme.weather.v1.CurrentWeather.Temperature

  • type可以为message、enum、server

• 还可以使用docker去build

  docker run \
  --volume "$(pwd):/workspace" \
  --workdir /workspace \
  bufbuild/buf build

buf generate

• buf.gen.yaml使用插件，编译go、grpc的proto

• 语法较多，用到了再看官方文档

  # 配置protoc生成规则
  version: v1
  managed:
  enabled: true
  go_package_prefix:
  # proto文件中不使用option定义包名称，因为proto生成代码可以放在不同项目中使用，因此在buf.gen.yaml中进行定义
  default: go/apigen
  except:
    - buf.build/googleapis/googleapis
  plugins:
  # 使用go插件生成go代码
  - name: go
  out: apigen/go
  opt: paths=source_relative
  # 使用go-grpc插件生成grpc代码
  - name: go-grpc
  out: apigen/go
  opt:
    - paths=source_relative
    - require_unimplemented_servers=false 
  # 使用grpc-gateway插件生成grpc-gateway代码
  - name: grpc-gateway
  out: apigen/go
  opt: paths=source_relative
  # 使用openapiv2插件生成swagger文件
  - name: openapiv2
  out: apigen
  opt:
    - allow_repeated_fields_in_body=true

• 使用远端的proto文件

  buf generate buf.build/acme/petapis

• 指定使用的template

  buf generate --template buf.gen.go.yaml
  buf generate --template buf.gen.java.yaml

• 指定需要生成的文件

  buf generate --path proto/foo --path proto/bar

• 指定输出目录

  buf generate https://github.com/foo/bar.git --template data/generate.yaml -o bar

buf ls-files

• 列出每个 构建配置管理的所有.proto文件

buf lint

• 运行所有配置的 lint 规则

• 查看具体的错误，对应的规则buf lint --error-format=json

• 在buf.yaml中配置检查规则

  version: v1
  lint:
   use:
     - DEFAULT
   except:
     - PACKAGE_VERSION_SUFFIX
     - FIELD_LOWER_SNAKE_CASE
     - SERVICE_SUFFIX
   ignore:
     - google/type/datetime.proto  
  breaking:
   use:
     - FILE

buf breaking

• 检查是否有重大改变（影响兼容性）

  buf breaking --against ../../.git#branch=main,subdir=start/petapis：和git main分支对比

• 跨项目时留意

buf mod update

更新依赖(会生成buf.lock文件)

工作空间

实现跨模块引用

.
├── buf.work.yaml
├── proto
│   ├── acme
│   │   └── weather
│   │       └── v1
│   │           └── weather.proto
│   └── buf.yaml
└── vendor
    └── protoc-gen-validate
        ├── buf.yaml
        └── validate
            └── validate.proto

buf.work.yaml

version: v1
directories:
  - proto
  - vendor/protoc-gen-validate

• 工作空间模块不能重叠，即一个工作空间模块不能是另一个工作空间模块的子目录。

• 所有.proto文件路径相对于每个工作区模块必须是唯一的。

  导入时用到了不包含工作空间名的路径，无法区分