# 神仙盒公共 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.