topfans/backend/proto/README.md

Proto 文件说明

目录：Protocol Buffers 定义文件
用途：定义服务接口和数据结构

---

📁 文件结构

proto/
├── common.proto          # 通用消息定义（BaseResponse, PageRequest 等）
├── user.proto            # 用户服务定义（认证、身份、个人资料等）
├── social.proto          # 社交服务定义（好友、关注等功能）
└── README.md            # 本文档

---

🔧 编译 Proto 文件

1. 安装依赖

需要安装以下工具：

# 安装 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 文件

# 进入 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：

#!/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 文件编译完成！"

使用脚本：

chmod +x scripts/compile-proto.sh
./scripts/compile-proto.sh

---

📋 social.proto 说明

核心 Message

1. FriendRequest（好友请求）

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（好友关系）

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

service SocialService {
  // 好友请求相关
  rpc SendFriendRequest(...)      // 发送好友请求
  rpc GetFriendRequests(...)      // 获取请求列表
  rpc HandleFriendRequest(...)    // 处理请求（接受/拒绝）
  
  // 好友关系相关
  rpc GetFriendList(...)          // 获取好友列表
  rpc DeleteFriend(...)           // 删除好友
  rpc SetFriendRemark(...)        // 设置备注
  rpc CheckFriendship(...)        // 检查好友关系
  rpc GetFriendCount(...)         // 获取好友数量
}

---

🎯 使用示例

1. 在 Service 层实现接口

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 层调用服务

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. 测试验证

---

✅ 检查清单

• common.proto - 通用定义
• user.proto - 用户服务（认证、身份、个人资料）
• social.proto - 社交服务（好友、关注等功能）
• 编译所有 proto 文件
• 实现 SocialService
• 创建 Provider
• 注册 Dubbo 服务

---

📚 参考资料

• Protocol Buffers 官方文档
• Dubbo-go 官方文档
• gRPC HTTP 注解

---

最后更新：2026-01-06
版本：v2.0（已重命名为 Social 服务）