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