322 lines
7.6 KiB
Markdown
322 lines
7.6 KiB
Markdown
# Proto 文件说明
|
||
|
||
> **目录**：Protocol Buffers 定义文件
|
||
> **用途**：定义服务接口和数据结构
|
||
|
||
---
|
||
|
||
## 📁 文件结构
|
||
|
||
```
|
||
proto/
|
||
├── common.proto # 通用消息定义（BaseResponse, PageRequest 等）
|
||
├── user.proto # 用户服务定义（认证、身份、个人资料等）
|
||
├── social.proto # 社交服务定义（好友、关注等功能）
|
||
└── README.md # 本文档
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 编译 Proto 文件
|
||
|
||
### 1. 安装依赖
|
||
|
||
需要安装以下工具：
|
||
|
||
```bash
|
||
# 安装 protoc 编译器
|
||
# macOS
|
||
brew install protobuf
|
||
|
||
# Ubuntu/Debian
|
||
apt-get install protobuf-compiler
|
||
|
||
# 安装 Go 插件
|
||
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
|
||
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
|
||
go install github.com/dubbogo/triple/cmd/protoc-gen-triple@latest
|
||
|
||
# 安装 HTTP 注解插件（可选）
|
||
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
|
||
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest
|
||
```
|
||
|
||
### 2. 编译 Proto 文件
|
||
|
||
```bash
|
||
# 进入 backend 目录
|
||
cd /path/to/backend
|
||
|
||
# 编译 user.proto
|
||
protoc --proto_path=. \
|
||
--go_out=. \
|
||
--go_opt=module=github.com/topfans/backend \
|
||
--go-triple_out=. \
|
||
--go-triple_opt=module=github.com/topfans/backend \
|
||
proto/user.proto
|
||
|
||
# 编译 social.proto
|
||
protoc --proto_path=. \
|
||
--go_out=. \
|
||
--go_opt=module=github.com/topfans/backend \
|
||
--go-triple_out=. \
|
||
--go-triple_opt=module=github.com/topfans/backend \
|
||
proto/social.proto
|
||
|
||
# 生成的文件：
|
||
# - pkg/proto/user/user.pb.go # 用户服务消息定义
|
||
# - pkg/proto/user/user.triple.go # 用户服务 Dubbo Triple 接口
|
||
# - pkg/proto/social/social.pb.go # 社交服务消息定义
|
||
# - pkg/proto/social/social.triple.go # 社交服务 Dubbo Triple 接口
|
||
```
|
||
|
||
### 3. 批量编译所有 proto 文件
|
||
|
||
创建编译脚本 `scripts/compile-proto.sh`：
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
|
||
set -e
|
||
|
||
# 进入项目根目录
|
||
cd "$(dirname "$0")/.."
|
||
|
||
echo "编译 Proto 文件..."
|
||
|
||
# 模块路径
|
||
MODULE_PATH="github.com/topfans/backend"
|
||
|
||
# 编译 user.proto
|
||
protoc --proto_path=. \
|
||
--go_out=. \
|
||
--go_opt=module=$MODULE_PATH \
|
||
--go-triple_out=. \
|
||
--go-triple_opt=module=$MODULE_PATH \
|
||
proto/user.proto
|
||
|
||
echo "✅ user.proto 编译完成"
|
||
|
||
# 编译 social.proto
|
||
protoc --proto_path=. \
|
||
--go_out=. \
|
||
--go_opt=module=$MODULE_PATH \
|
||
--go-triple_out=. \
|
||
--go-triple_opt=module=$MODULE_PATH \
|
||
proto/social.proto
|
||
|
||
echo "✅ social.proto 编译完成"
|
||
|
||
echo "所有 Proto 文件编译完成！"
|
||
```
|
||
|
||
使用脚本：
|
||
|
||
```bash
|
||
chmod +x scripts/compile-proto.sh
|
||
./scripts/compile-proto.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 social.proto 说明
|
||
|
||
### 核心 Message
|
||
|
||
#### 1. FriendRequest（好友请求）
|
||
|
||
```protobuf
|
||
message FriendRequest {
|
||
int64 id = 1; // 请求ID
|
||
int64 from_user_id = 2; // 发送者用户ID
|
||
int64 to_user_id = 3; // 接收者用户ID
|
||
int64 star_id = 4; // 明星ID
|
||
string message = 5; // 请求附带消息
|
||
string status = 6; // 状态
|
||
// ... 更多字段
|
||
}
|
||
```
|
||
|
||
**状态枚举**：
|
||
- `pending` - 待处理
|
||
- `accepted` - 已接受
|
||
- `rejected` - 已拒绝
|
||
- `expired` - 已过期
|
||
|
||
---
|
||
|
||
#### 2. Friendship（好友关系）
|
||
|
||
```protobuf
|
||
message Friendship {
|
||
int64 id = 1; // 关系ID
|
||
int64 user_id = 2; // 用户ID
|
||
int64 friend_id = 3; // 好友用户ID
|
||
int64 star_id = 4; // 明星ID
|
||
string status = 5; // 状态
|
||
string remark = 6; // 备注名
|
||
// ... 更多字段
|
||
}
|
||
```
|
||
|
||
**状态枚举**：
|
||
- `accepted` - 正常好友关系
|
||
- `blocked` - 已屏蔽（预留）
|
||
|
||
---
|
||
|
||
### 服务接口
|
||
|
||
#### SocialService
|
||
|
||
```protobuf
|
||
service SocialService {
|
||
// 好友请求相关
|
||
rpc SendFriendRequest(...) // 发送好友请求
|
||
rpc GetFriendRequests(...) // 获取请求列表
|
||
rpc HandleFriendRequest(...) // 处理请求（接受/拒绝）
|
||
|
||
// 好友关系相关
|
||
rpc GetFriendList(...) // 获取好友列表
|
||
rpc DeleteFriend(...) // 删除好友
|
||
rpc SetFriendRemark(...) // 设置备注
|
||
rpc CheckFriendship(...) // 检查好友关系
|
||
rpc GetFriendCount(...) // 获取好友数量
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 使用示例
|
||
|
||
### 1. 在 Service 层实现接口
|
||
|
||
```go
|
||
package service
|
||
|
||
import (
|
||
pb "github.com/topfans/backend/pkg/proto/social"
|
||
)
|
||
|
||
type SocialService struct {
|
||
// 依赖注入
|
||
socialRepo repository.SocialRepository
|
||
config *config.SocialConfig
|
||
}
|
||
|
||
// 实现 SendFriendRequest
|
||
func (s *SocialService) SendFriendRequest(
|
||
ctx context.Context,
|
||
req *pb.SendFriendRequestRequest,
|
||
) (*pb.SendFriendRequestResponse, error) {
|
||
// 从 Dubbo Attachments 获取用户信息
|
||
userID := dubbo.GetAttachment(ctx, "user_id")
|
||
starID := dubbo.GetAttachment(ctx, "star_id")
|
||
|
||
// 业务逻辑...
|
||
|
||
return &pb.SendFriendRequestResponse{
|
||
Base: &common.BaseResponse{
|
||
Code: common.StatusCode_STATUS_OK,
|
||
Message: "ok",
|
||
Timestamp: time.Now().UnixMilli(),
|
||
},
|
||
RequestId: requestID,
|
||
Status: "pending",
|
||
}, nil
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 在 Gateway 层调用服务
|
||
|
||
```go
|
||
package controller
|
||
|
||
import (
|
||
pb "github.com/topfans/backend/pkg/proto/social"
|
||
)
|
||
|
||
type SocialController struct {
|
||
socialServiceClient pb.SocialServiceClient
|
||
}
|
||
|
||
func (c *SocialController) SendFriendRequest(ctx *gin.Context) {
|
||
var req pb.SendFriendRequestRequest
|
||
if err := ctx.ShouldBindJSON(&req); err != nil {
|
||
response.BadRequest(ctx, err.Error())
|
||
return
|
||
}
|
||
|
||
// 创建 Dubbo Context，设置 Attachments
|
||
dubboCtx := context.Background()
|
||
dubboCtx = context.WithValue(dubboCtx, constant.AttachmentKey,
|
||
map[string]interface{}{
|
||
"user_id": ctx.GetInt64("user_id"),
|
||
"star_id": ctx.GetInt64("star_id"),
|
||
})
|
||
|
||
// 调用 Dubbo 服务
|
||
resp, err := c.socialServiceClient.SendFriendRequest(dubboCtx, &req)
|
||
if err != nil {
|
||
response.HandleError(ctx, err)
|
||
return
|
||
}
|
||
|
||
response.Success(ctx, resp)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 HTTP 路由映射
|
||
|
||
基于 proto 文件中的 `google.api.http` 注解，自动生成以下路由：
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/v1/friends/requests` | 发送好友请求 |
|
||
| GET | `/api/v1/friends/requests` | 获取请求列表 |
|
||
| POST | `/api/v1/friends/requests/{request_id}/handle` | 处理请求 |
|
||
| GET | `/api/v1/friends` | 获取好友列表 |
|
||
| DELETE | `/api/v1/friends/{friend_user_id}` | 删除好友 |
|
||
| PUT | `/api/v1/friends/{friend_user_id}/remark` | 设置备注 |
|
||
| GET | `/api/v1/friends/check/{user_id}/{friend_user_id}` | 检查好友关系 |
|
||
| GET | `/api/v1/friends/count` | 获取好友数量 |
|
||
|
||
---
|
||
|
||
## 🔄 Proto 文件修改流程
|
||
|
||
1. **修改 proto 文件**
|
||
2. **重新编译**：`./scripts/compile-proto.sh`
|
||
3. **更新 Service 实现**
|
||
4. **更新 Gateway Controller**
|
||
5. **测试验证**
|
||
|
||
---
|
||
|
||
## ✅ 检查清单
|
||
|
||
- [x] common.proto - 通用定义
|
||
- [x] user.proto - 用户服务（认证、身份、个人资料）
|
||
- [x] social.proto - 社交服务（好友、关注等功能）
|
||
- [x] 编译所有 proto 文件
|
||
- [ ] 实现 SocialService
|
||
- [ ] 创建 Provider
|
||
- [ ] 注册 Dubbo 服务
|
||
|
||
---
|
||
|
||
## 📚 参考资料
|
||
|
||
- [Protocol Buffers 官方文档](https://developers.google.com/protocol-buffers)
|
||
- [Dubbo-go 官方文档](https://dubbogo.github.io/)
|
||
- [gRPC HTTP 注解](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto)
|
||
|
||
---
|
||
|
||
**最后更新**：2026-01-06
|
||
**版本**：v2.0（已重命名为 Social 服务）
|