88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
# 神仙盒公共 gRPC 服务定义
|
||
|
||
## 项目简介
|
||
|
||
这是神仙盒（Shenxianhe）项目的公共 gRPC 服务 Protocol Buffers 定义仓库。本仓库专注于定义项目中所有微服务的接口规范，多语言客户端 SDK 完全由本仓库中的 proto 文件自动生成。
|
||
|
||
## SDK 地址
|
||
|
||
| SDK 类型 | 地址 |
|
||
| -------------- | -------------------------------------------------------------------- |
|
||
| Go SDK | `https://git.shenxianhe.cn/shenxianhe/sdk` |
|
||
| TypeScript SDK | `https://git.shenxianhe.cn/shenxianhe/-/packages/npm/@connect%2Fsdk` |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
proto/
|
||
├── .gitignore # Git忽略配置文件
|
||
├── Makefile # 构建和发布脚本
|
||
├── README.md # 项目说明文档
|
||
├── src/ # 服务定义目录
|
||
├── buf.gen.yaml # buf生成配置
|
||
├── buf.yaml # buf项目配置
|
||
├── script/ # 辅助脚本目录
|
||
├── templates/ # 模板文件目录
|
||
└── version.txt # 版本号文件
|
||
```
|
||
|
||
## 编写指南
|
||
|
||
### 安装必要工具
|
||
|
||
本项目使用以下工具进行 Protocol Buffers 的管理、构建和代码生成：
|
||
|
||
```bash
|
||
# 安装 Go 相关工具
|
||
go install github.com/bufbuild/buf/cmd/buf@latest
|
||
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
|
||
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
|
||
go install connectrpc.com/connect/cmd/protoc-gen-connect-go@latest
|
||
|
||
# 安装 Node.js 相关工具
|
||
npm install -g @bufbuild/protoc-gen-es
|
||
```
|
||
|
||
> 提示：如果安装后找不到命令，需要确保工具的 bin 目录已添加到系统 PATH 环境变量中。如果是使用 brew 安装的软件，可以执行 `brew unlink name && brew link name` 来解决。 如：`brew unlink node && brew link node`
|
||
|
||
### 修改 proto 文件后的工作流程
|
||
|
||
当你需要修改或添加 proto 文件时，请遵循以下工作流程：
|
||
|
||
1. **修改/创建 proto 文件**：在 `src/` 目录下按照服务和版本组织的结构进行修改或创建新文件
|
||
|
||
2. **验证语法**：运行 `buf lint` 确保语法符合规范
|
||
|
||
3. **检查兼容性**：运行 `buf breaking --against .git#branch=main` 检查是否有不兼容变更
|
||
|
||
4. **生成 SDK 代码**：运行 `make generate` 命令生成最新的 SDK 代码
|
||
|
||
5. **发布 SDK**：运行 `make publish` 命令自动生成新版本号并发布 SDK（版本号会通过脚本自动管理）
|
||
|
||
## 版本控制
|
||
|
||
本项目使用语义化版本控制，服务接口的变更遵循以下原则：
|
||
|
||
1. **向后兼容**：尽量保持接口的向后兼容性
|
||
2. **版本升级**：不兼容的变更请在 src 中为服务创建单独的版本目录
|
||
3. **自动版本生成**：通过 `script/get_next_version.sh` 脚本自动管理版本号
|
||
4. **Breaking Change 检查**：使用 buf breaking 工具检查不兼容的变更
|
||
|
||
## 开发规范
|
||
|
||
1. 遵循 [Protocol Buffers Style Guide](https://developers.google.com/protocol-buffers/docs/style) 并使用 buf 标准 lint 规则
|
||
2. 具体 lint 规则配置可在项目根目录的 buf.yaml 文件中查看
|
||
3. 每个服务定义放在单独的目录下，并按版本号组织
|
||
4. 新增字段时使用新的字段编号，不要重用已删除字段的编号
|
||
|
||
## Makefile 命令提示
|
||
|
||
执行 `make help` 可查看所有可用命令和详细说明。主要命令包括：
|
||
|
||
- `make generate`: 生成 SDK 代码
|
||
- `make publish`: 发布 SDK 到各个仓库
|
||
|
||
## 版权信息
|
||
|
||
© 2025 神仙盒团队. All rights reserved.
|