zhibo/接口对接分析报告.md

直播间管理模块接口对接分析报告

📋 分析概述

本报告对比了 模块文档/02-直播间管理模块.md 中定义的接口规范与后端实际实现，以及前端Android应用的调用情况。

---

✅ 已正确实现的接口

1. 获取直播间列表

• 文档路径: GET /api/front/live/public/rooms
• 后端实现: ✅ LiveRoomController.publicRooms()
• 前端调用: ✅ ApiService.getRooms()
• 状态: 完全匹配

后端返回字段:

- id (String)
- title (String)
- streamerName (String)
- streamKey (String)
- isLive (Boolean)
- viewerCount (Integer)
- streamUrls (StreamUrlsResponse)
  - rtmp
  - flv
  - hls

⚠️ 缺失字段对比文档:

• ❌ streamerId (主播ID)
• ❌ streamerAvatar (主播头像)
• ❌ coverImage (封面图)
• ❌ likeCount (点赞数)
• ❌ categoryId (分类ID)
• ❌ categoryName (分类名称)
• ❌ tags (标签数组)
• ❌ createTime (创建时间)
• ❌ startTime (开始时间)

---

2. 获取直播间详情

• 文档路径: GET /api/front/live/public/rooms/{id}
• 后端实现: ✅ LiveRoomController.publicRoom()
• 前端调用: ✅ ApiService.getRoom()
• 状态: 部分匹配

⚠️ 缺失字段对比文档:

• ❌ description (直播间描述)
• ❌ streamerId (主播ID)
• ❌ streamerAvatar (主播头像)
• ❌ streamerLevel (主播等级)
• ❌ coverImage (封面图)
• ❌ likeCount (点赞数)
• ❌ shareCount (分享数)
• ❌ categoryId (分类ID)
• ❌ categoryName (分类名称)
• ❌ tags (标签数组)
• ❌ isFollowing (是否已关注)
• ❌ createTime (创建时间)
• ❌ startTime (开始时间)
• ❌ notice (直播间公告)

---

3. 创建直播间

• 文档路径: POST /api/front/live/rooms
• 后端实现: ✅ LiveRoomController.create()
• 前端调用: ✅ ApiService.createRoom()
• 状态: 部分匹配

后端接收参数:

- title (String) ✅
- streamerName (String) ✅

⚠️ 文档要求但后端未接收的参数:

• ❌ type (直播类型)
• ❌ categoryId (分类ID)
• ❌ description (描述)
• ❌ coverImage (封面URL)

---

4. 开始直播

• 文档路径: POST /api/front/live/room/{id}/start
• 后端实现: ❌ 未实现
• 前端调用: ✅ ApiService.startLiveRoom()
• 状态: 缺失接口

问题:

• 后端没有提供 /room/{id}/start 端点
• 后端只有 setLiveStatus(streamKey, boolean) 方法，通过SRS回调自动触发
• 前端期望手动控制开始直播，但后端未提供此接口

---

5. 结束直播

• 文档路径: POST /api/front/live/room/{id}/stop
• 后端实现: ❌ 未实现
• 前端调用: ✅ ApiService.stopLiveRoom()
• 状态: 缺失接口

问题:

• 后端没有提供 /room/{id}/stop 端点
• 后端只有 setLiveStatus(streamKey, boolean) 方法，通过SRS回调自动触发
• 前端期望手动控制结束直播，但后端未提供此接口

---

6. 关注主播

• 文档路径: POST /api/front/live/follow
• 后端实现: ✅ LiveRoomController.followStreamer()
• 前端调用: ✅ ApiService.followStreamer()
• 状态: 完全匹配

后端接收参数:

- streamerId (Integer) ✅
- action (String: "follow" | "unfollow") ✅

后端返回:

- success (Boolean)
- message (String)
- isFollowing (Boolean)

---

7. 获取在线人数

• 文档路径: GET /api/live/online/count/{roomId}
• 后端实现: ✅ LiveRoomOnlineController.getRoomOnlineCount()
• 前端调用: ❌ 前端未直接调用此接口
• 状态: 后端已实现，前端未使用

后端返回:

CommonResult<Integer> // 直接返回人数

⚠️ 文档期望返回格式:

{
  "code": 200,
  "msg": "success",
  "data": {
    "count": 1234,
    "roomId": "房间ID"
  }
}

问题: 返回格式不匹配，后端直接返回Integer，文档期望返回包含count和roomId的对象

---

8. 获取观众列表

• 文档路径: GET /api/front/live/rooms/{roomId}/viewers
• 后端实现: ✅ LiveRoomController.getViewers()
• 前端调用: ✅ ApiService.getRoomViewers()
• 状态: 部分匹配

后端返回字段:

- userId (String)
- nickname (String)
- avatar (String)
- level (Integer)
- isVip (Boolean)
- enterTime (Date)
- isOnline (Boolean)
- clientId (String)

⚠️ 文档期望但后端未返回的字段:

• ❌ vipLevel (VIP等级，后端返回的是isVip布尔值)
• ❌ isFollowing (是否关注)
• ❌ joinTime (文档使用joinTime，后端使用enterTime)

⚠️ 分页参数不匹配:

• 文档期望: page, pageSize
• 后端接收: limit (只有limit参数，没有page)
• 前端调用: page, pageSize

---

9. 赠送礼物

• 文档路径: POST /api/front/live/rooms/{roomId}/gift
• 后端实现: ✅ LiveRoomController.sendGift()
• 前端调用: ✅ ApiService.sendRoomGift()
• 状态: 完全匹配

后端接收参数:

- roomId (路径参数) ✅
- giftId (请求体) ✅
- count (请求体) ✅
- receiverId (请求体) - 额外参数

后端返回:

- success (Boolean)
- newBalance (Integer)
- giftName (String)
- totalPrice (Integer)
- message (String)

---

10. 手动广播在线人数

• 文档路径: POST /api/live/online/broadcast/{roomId}
• 后端实现: ✅ LiveRoomOnlineController.broadcastRoomCount()
• 前端调用: ✅ ApiService.broadcastOnlineCount()
• 状态: 完全匹配

---

❌ 主要问题汇总

🔴 严重问题

1. 缺失关键接口

• 开始直播接口: POST /api/front/live/room/{id}/start - 未实现
• 结束直播接口: POST /api/front/live/room/{id}/stop - 未实现

影响: 前端无法手动控制直播的开始和结束，只能依赖SRS推流回调自动触发

建议: 在 LiveRoomController 中添加以下方法:

@ApiOperation(value = "开始直播")
@PostMapping("/room/{id}/start")
public CommonResult<Map<String, Object>> startLive(@PathVariable Integer id) {
    Integer uid = frontTokenComponent.getUserId();
    if (uid == null) return CommonResult.failed("未登录");
    
    LiveRoom room = liveRoomService.getById(id);
    if (room == null) return CommonResult.failed("房间不存在");
    if (!uid.equals(room.getUid())) return CommonResult.failed("无权限");
    
    boolean success = liveRoomService.setLiveStatus(room.getStreamKey(), true);
    
    Map<String, Object> result = new HashMap<>();
    result.put("success", success);
    result.put("message", success ? "直播已开始" : "开始直播失败");
    return CommonResult.success(result);
}

@ApiOperation(value = "结束直播")
@PostMapping("/room/{id}/stop")
public CommonResult<Map<String, Object>> stopLive(@PathVariable Integer id) {
    Integer uid = frontTokenComponent.getUserId();
    if (uid == null) return CommonResult.failed("未登录");
    
    LiveRoom room = liveRoomService.getById(id);
    if (room == null) return CommonResult.failed("房间不存在");
    if (!uid.equals(room.getUid())) return CommonResult.failed("无权限");
    
    boolean success = liveRoomService.setLiveStatus(room.getStreamKey(), false);
    
    Map<String, Object> result = new HashMap<>();
    result.put("success", success);
    result.put("message", success ? "直播已结束" : "结束直播失败");
    return CommonResult.success(result);
}

---

🟡 中等问题

2. 响应字段缺失

LiveRoomResponse 缺失的重要字段:

// 需要在 LiveRoomResponse 类中添加:
private Integer streamerId;        // 主播ID
private String streamerAvatar;     // 主播头像
private String coverImage;         // 封面图
private String description;        // 描述
private Integer likeCount;         // 点赞数
private Integer shareCount;        // 分享数
private Integer categoryId;        // 分类ID
private String categoryName;       // 分类名称
private List<String> tags;         // 标签
private Boolean isFollowing;       // 是否已关注
private Date createTime;           // 创建时间
private Date startTime;            // 开始时间
private String notice;             // 公告
private Integer streamerLevel;     // 主播等级

影响: 前端无法显示完整的直播间信息，用户体验受影响

---

3. 创建直播间参数不完整

CreateLiveRoomRequest 缺失的参数:

// 需要在 CreateLiveRoomRequest 类中添加:
private String type;              // 直播类型
private Integer categoryId;       // 分类ID
private String description;       // 描述
private String coverImage;        // 封面图URL

影响: 无法创建带分类、描述、封面的直播间

---

4. 在线人数接口返回格式不匹配

当前返回: CommonResult<Integer> 文档期望:

{
  "code": 200,
  "msg": "success",
  "data": {
    "count": 1234,
    "roomId": "房间ID"
  }
}

建议修改:

@GetMapping("/count/{roomId}")
public CommonResult<Map<String, Object>> getRoomOnlineCount(@PathVariable String roomId) {
    try {
        int count = liveRoomOnlineService.getRoomOnlineCount(roomId);
        Map<String, Object> result = new HashMap<>();
        result.put("count", count);
        result.put("roomId", roomId);
        return CommonResult.success(result);
    } catch (Exception e) {
        log.error("Error getting room online count for roomId: {}", roomId, e);
        return CommonResult.failed("获取在线人数失败");
    }
}

---

5. 观众列表分页参数不一致

文档期望: page, pageSize 后端实现: 只有 limit 参数 前端调用: page, pageSize

建议修改:

@GetMapping("/rooms/{roomId}/viewers")
public CommonResult<Map<String, Object>> getViewers(
        @PathVariable Integer roomId,
        @RequestParam(defaultValue = "1") Integer page,
        @RequestParam(defaultValue = "20") Integer pageSize) {
    // 实现分页逻辑
    // 返回包含 data, total, page, pageSize 的结果
}

---

🟢 轻微问题

6. 字段命名不一致

• 文档使用 joinTime，后端使用 enterTime
• 文档使用 vipLevel，后端使用 isVip

建议: 统一字段命名，或在响应对象中做映射

---

📊 接口实现完整度统计

接口	文档定义	后端实现	前端调用	状态
1. 获取直播间列表	✅	✅	✅	🟡 字段不完整
2. 获取直播间详情	✅	✅	✅	🟡 字段不完整
3. 创建直播间	✅	✅	✅	🟡 参数不完整
4. 开始直播	✅	❌	✅	🔴 接口缺失
5. 结束直播	✅	❌	✅	🔴 接口缺失
6. 关注主播	✅	✅	✅	✅ 完全匹配
7. 获取在线人数	✅	✅	❌	🟡 格式不匹配
8. 获取观众列表	✅	✅	✅	🟡 参数不一致
9. 赠送礼物	✅	✅	✅	✅ 完全匹配
10. 手动广播在线人数	✅	✅	✅	✅ 完全匹配

完整度: 6/10 完全匹配，2/10 缺失，2/10 部分匹配

---

🔧 修复建议优先级

P0 - 紧急 (必须修复)

1. ✅ 添加开始直播接口 POST /api/front/live/room/{id}/start
2. ✅ 添加结束直播接口 POST /api/front/live/room/{id}/stop

P1 - 重要 (建议修复)

3. ✅ 扩展 LiveRoomResponse 添加缺失字段
4. ✅ 扩展 CreateLiveRoomRequest 添加缺失参数
5. ✅ 修复在线人数接口返回格式
6. ✅ 修复观众列表分页参数

P2 - 一般 (可选修复)

7. ✅ 统一字段命名规范
8. ✅ 完善API文档注释

---

📝 总结

后端基本实现了核心功能，但存在以下主要问题：

1. 缺少手动控制直播的接口 - 这是最严重的问题，影响前端功能
2. 响应数据不完整 - 缺少主播信息、分类、标签等重要字段
3. 参数格式不统一 - 分页参数、返回格式与文档不一致

建议按照优先级逐步修复这些问题，确保前后端接口完全对齐。