89 lines
2.6 KiB
Markdown
89 lines
2.6 KiB
Markdown
# 神仙盒公共 gRPC 服务定义
|
||
|
||
## 项目简介
|
||
|
||
这是神仙盒（Shenxianhe）项目的公共 gRPC 服务 Protocol Buffers 定义文件。本仓库包含了项目中所有微服务的接口定义，用于服务间通信和客户端 SDK 生成。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
proto/
|
||
├── .gitignore # Git忽略配置文件
|
||
├── Makefile # 构建和发布脚本
|
||
├── README.md # 项目说明文档
|
||
├── src/ # 服务定义目录
|
||
├── buf.gen.yaml # buf生成配置
|
||
├── buf.yaml # buf项目配置
|
||
├── script/ # 辅助脚本目录
|
||
├── templates/ # 模板文件目录
|
||
└── version.txt # 版本号文件
|
||
```
|
||
|
||
## 使用指南
|
||
|
||
### 安装依赖
|
||
|
||
本项目使用多个工具进行 Protocol Buffers 的管理、构建和代码生成。请安装以下工具：
|
||
|
||
1. go 相关工具
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
如果安装后依然提示找不到命令，需要将 go 的 bin 目录添加到 PATH 中。
|
||
如果是使用 brew 安装的 go，可以执行 `brew unlink go && brew link go` 来解决。
|
||
|
||
2. node 相关工具
|
||
|
||
```bash
|
||
npm install -g @bufbuild/protoc-gen-es
|
||
```
|
||
|
||
如果安装后依然提示找不到命令，需要将 npm 的 bin 目录添加到 PATH 中。
|
||
如果是使用 brew 安装的 node，可以执行 `brew unlink node && brew link node` 来解决。
|
||
|
||
### 检查语法
|
||
|
||
```bash
|
||
# 在 proto 目录下运行
|
||
buf lint
|
||
```
|
||
|
||
### 检查兼容性
|
||
|
||
```bash
|
||
# 检查 API 兼容性
|
||
buf breaking --against .git#branch=main
|
||
```
|
||
|
||
## 版本控制
|
||
|
||
本项目使用语义化版本控制，服务接口的变更遵循以下原则：
|
||
|
||
1. **向后兼容**：尽量保持接口的向后兼容性
|
||
2. **版本升级**：不兼容的变更会导致版本号的升级
|
||
3. **Breaking Change 检查**：使用 buf breaking 工具检查不兼容的变更
|
||
|
||
## 开发规范
|
||
|
||
1. 遵循 [Protocol Buffers Style Guide](https://developers.google.com/protocol-buffers/docs/style)
|
||
2. 使用标准的 lint 规则（STANDARD）
|
||
3. 每个服务定义放在单独的目录下，并按版本号组织
|
||
4. 新增字段时使用新的字段编号，不要重用已删除字段的编号
|
||
|
||
## 贡献指南
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支
|
||
3. 提交变更
|
||
4. 运行 `buf lint` 和 `buf breaking` 检查
|
||
5. 创建 Pull Request
|
||
|
||
## 版权信息
|
||
|
||
© 2025 神仙盒团队. All rights reserved.
|