xiaoyu/topfans
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d0ff68508f
topfans/backend/gateway/SOCIAL_GATEWAY_IMPLEMENTATION.md
zerosaturation 06f4038a75 提交后端代码
2026-04-07 22:29:48 +08:00

11 KiB
Raw Blame History

Gateway 社交服务集成总结

实现时间

2026年1月6日

概述

成功为 Top-Fans Gateway 添加了社交服务（SocialService）的 HTTP 接口支持，包括好友请求、好友管理等完整功能。

修改的文件

1. 控制器层

新增文件: controller/social_controller.go

实现了以下 HTTP 处理器：

方法 路由 功能描述
SendFriendRequest POST /api/v1/social/friend-requests 发送好友请求
GetFriendRequests GET /api/v1/social/friend-requests 获取好友请求列表
HandleFriendRequest POST /api/v1/social/friend-requests/handle 处理好友请求（接受/拒绝）
GetFriendList GET /api/v1/social/friends 获取好友列表
DeleteFriend DELETE /api/v1/social/friends 删除好友
SetFriendRemark PUT /api/v1/social/friends/remark 设置好友备注
CheckFriendship GET /api/v1/social/friendship/check 检查好友关系
GetFriendCount GET /api/v1/social/friends/count 获取好友数量

关键特性：

  • 统一的错误处理和日志记录
  • 从上下文中获取用户认证信息
  • 支持分页、搜索等查询参数
  • 5秒超时控制

2. DTO 转换层

新增文件: dto/social_converter.go

提供了以下数据转换函数：

  • ConvertFriendRequest(): 转换好友请求数据为 HTTP 响应格式
  • ConvertFriendship(): 转换好友关系数据为 HTTP 响应格式

转换特性：

  • 自动过滤空值字段
  • 智能处理可选字段（如备注、处理时间等）
  • 包含用户扩展信息（昵称、头像、等级等）

3. 配置层

修改文件: config/config.go

新增配置项：

type DubboConfig struct {
    UserServiceURL   string  // UserService 地址
    SocialServiceURL string  // SocialService 地址（新增）
}

默认值：

  • DUBBO_USER_SERVICE_URL: tri://127.0.0.1:20000
  • DUBBO_SOCIAL_SERVICE_URL: tri://127.0.0.1:20001

4. 路由层

修改文件: router/router.go

新增路由组：

// 社交功能路由（需要认证）
social := v1.Group("/social")
social.Use(middleware.AuthMiddleware())
{
    // 好友请求相关
    social.POST("/friend-requests", socialCtrl.SendFriendRequest)
    social.GET("/friend-requests", socialCtrl.GetFriendRequests)
    social.POST("/friend-requests/handle", socialCtrl.HandleFriendRequest)

    // 好友管理相关
    social.GET("/friends", socialCtrl.GetFriendList)
    social.DELETE("/friends", socialCtrl.DeleteFriend)
    social.PUT("/friends/remark", socialCtrl.SetFriendRemark)
    
    // 好友关系查询
    social.GET("/friendship/check", socialCtrl.CheckFriendship)
    social.GET("/friends/count", socialCtrl.GetFriendCount)
}

5. 主程序

修改文件: main.go

变更内容：

  • 初始化两个 Dubbo 客户端（UserService 和 SocialService）
  • 将两个客户端传递给路由设置函数
  • 添加 SocialService 连接日志

代码片段：

// UserService Client
userClient, err := client.NewClient(
    client.WithClientURL(cfg.Dubbo.UserServiceURL),
)

// SocialService Client
socialClient, err := client.NewClient(
    client.WithClientURL(cfg.Dubbo.SocialServiceURL),
)

// 设置路由
r, err := router.SetupRouter(userClient, socialClient)

6. 响应工具

修改文件: pkg/response/response.go

新增方法：

// ErrorWithCode 错误响应（自定义业务错误码）
func ErrorWithCode(c *gin.Context, code int, message string)

该方法根据业务错误码自动映射到合适的 HTTP 状态码。

7. 启动脚本

修改文件: start.sh

更新内容：

  • 添加 SocialService 端口检查（20001）
  • 添加 DUBBO_SOCIAL_SERVICE_URL 环境变量
  • 更新配置信息显示

API 路由一览

用户服务 API（已有）

方法 路径 认证 描述
POST /api/v1/auth/register ❌ 用户注册
POST /api/v1/auth/login ❌ 用户登录
POST /api/v1/auth/validate ❌ 验证 Token
GET /api/v1/auth/me ✅ 获取当前用户信息
POST /api/v1/auth/refresh ✅ 刷新 Token
POST /api/v1/auth/logout ✅ 登出
GET /api/v1/users/:user_id ❌ 获取指定用户信息
GET /api/v1/fan-profiles ❌ 获取粉丝档案
GET /api/v1/me/profile ✅ 获取当前用户档案
PUT /api/v1/me/nickname ✅ 更新昵称
POST /api/v1/account/password ✅ 更新密码
GET /api/v1/fan-identities ❌ 获取可选粉丝身份
POST /api/v1/my/fan-identities ✅ 添加粉丝身份
POST /api/v1/my/fan-identities/switch ✅ 切换粉丝身份

社交服务 API（新增）

方法 路径 认证 描述
POST /api/v1/social/friend-requests ✅ 发送好友请求
GET /api/v1/social/friend-requests ✅ 获取好友请求列表
POST /api/v1/social/friend-requests/handle ✅ 处理好友请求
GET /api/v1/social/friends ✅ 获取好友列表
DELETE /api/v1/social/friends ✅ 删除好友
PUT /api/v1/social/friends/remark ✅ 设置好友备注
GET /api/v1/social/friendship/check ✅ 检查好友关系
GET /api/v1/social/friends/count ✅ 获取好友数量

请求示例

1. 发送好友请求

POST /api/v1/social/friend-requests
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "friend_user_id": 2,
  "message": "你好，我们交个朋友吧！"
}

响应：

{
  "code": 200,
  "message": "ok",
  "data": {
    "request_id": 1,
    "status": "pending",
    "created_at": 1736234567890,
    "expires_at": 1738826567890
  }
}

2. 获取好友列表

GET /api/v1/social/friends?page=1&page_size=20&keyword=小李
Authorization: Bearer YOUR_TOKEN

响应：

{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": 1,
        "user_id": 1,
        "friend_id": 2,
        "star_id": 1,
        "created_at": 1736234600000,
        "remark": "小李",
        "friend_nickname": "李四",
        "friend_avatar": "http://...",
        "friend_fan_level": 5,
        "friend_social": 10
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "has_more": false
  }
}

3. 删除好友

DELETE /api/v1/social/friends
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "friend_user_id": 2
}

响应：

{
  "code": 200,
  "message": "ok",
  "data": {
    "success": true
  }
}

启动流程

1. 启动服务

# 1. 启动 UserService (端口 20000)
cd services/userService
./start.sh

# 2. 启动 SocialService (端口 20001)
cd services/socialService
./start.sh

# 3. 启动 Gateway (端口 8080)
cd gateway
./start.sh

2. 健康检查

curl http://localhost:8080/health

预期响应：

{
  "status": "ok",
  "service": "top-fans-gateway"
}

环境变量

变量名 默认值 说明
SERVER_PORT 8080 Gateway 服务端口
GIN_MODE debug Gin 运行模式（debug/release/test）
DUBBO_USER_SERVICE_URL tri://127.0.0.1:20000 UserService Dubbo 地址
DUBBO_SOCIAL_SERVICE_URL tri://127.0.0.1:20001 SocialService Dubbo 地址
JWT_SECRET topfans-secret-key... JWT 签名密钥

错误处理

错误码映射

Proto 错误码 HTTP 状态码 说明
0 200 成功
400 400 请求参数错误
401 401 未授权
403 403 权限不足
404 404 资源不存在
409 409 冲突（如重复请求）
500 500 服务器内部错误

错误响应示例

{
  "code": 400,
  "message": "已有待处理的好友请求"
}

测试指南

完整的测试流程请参考：

快速测试：

# 1. 注册用户
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"mobile":"13800000001","password":"password123","star_id":1,"nickname":"张三"}'

# 2. 使用返回的 token
export TOKEN="YOUR_ACCESS_TOKEN"

# 3. 发送好友请求
curl -X POST http://localhost:8080/api/v1/social/friend-requests \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"friend_user_id":2,"message":"你好！"}'

# 4. 查看好友列表
curl -X GET "http://localhost:8080/api/v1/social/friends?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"

技术栈

  • 框架: Gin Web Framework
  • RPC: Dubbo-go v3 (Triple 协议)
  • 序列化: Protobuf
  • 认证: JWT
  • 日志: Uber Zap
  • ORM: GORM（通过微服务）
  • 数据库: PostgreSQL（通过微服务）

架构特点

  1. 职责分离: Gateway 只负责 HTTP 请求处理和路由，业务逻辑在微服务中
  2. 统一认证: 使用中间件统一处理用户认证
  3. 错误处理: 统一的错误响应格式和错误码映射
  4. DTO 转换: 清晰的数据转换层，隔离 Proto 和 HTTP 响应
  5. 日志记录: 完整的请求和错误日志
  6. 超时控制: 每个 RPC 调用都有 5 秒超时保护
  7. 分页支持: 列表接口统一支持分页参数
  8. 搜索功能: 好友列表支持关键字搜索

编译验证

✅ Gateway 编译成功 ✅ 无 Linter 错误 ✅ 所有路由正确注册 ✅ 中间件正确应用

后续优化建议

  1. 性能优化

    • 添加 Redis 缓存层
    • 实现请求合并和批处理
    • 添加连接池管理

  2. 安全增强

    • 添加请求频率限制
    • 实现 CSRF 保护
    • 添加 IP 白名单

  3. 监控告警

    • 添加 Prometheus 指标
    • 实现链路追踪
    • 添加性能监控

  4. 文档完善

    • 生成 Swagger/OpenAPI 文档
    • 添加更多使用示例
    • 完善错误码说明

  5. 测试覆盖

    • 添加单元测试
    • 添加集成测试
    • 实现自动化测试脚本

相关文档

文档版本: v1.0
最后更新: 2026-01-06
维护者: AI Assistant