神仙盒公共 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 的管理、构建和代码生成。请安装以下工具：

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

检查语法

# 在 proto 目录下运行
buf lint

检查兼容性

# 检查 API 兼容性
buf breaking --against .git#branch=main

版本控制

本项目使用语义化版本控制，服务接口的变更遵循以下原则：

1. 向后兼容：尽量保持接口的向后兼容性
2. 版本升级：不兼容的变更会导致版本号的升级
3. Breaking Change 检查：使用 buf breaking 工具检查不兼容的变更

开发规范

1. 遵循 Protocol Buffers Style Guide
2. 使用标准的 lint 规则（STANDARD）
3. 每个服务定义放在单独的目录下，并按版本号组织
4. 新增字段时使用新的字段编号，不要重用已删除字段的编号

贡献指南

1. Fork 本仓库
2. 创建特性分支
3. 提交变更
4. 运行 buf lint 和 buf breaking 检查
5. 创建 Pull Request

版权信息

© 2025 神仙盒团队. All rights reserved.