game_server/docs/链接状态接口兼容性说明.md

链接状态接口兼容性说明

概述

为了解决链接复制粘贴时参数丢失的问题，同时保证向后兼容，系统现在支持两种访问格式：

1. 路径参数格式（推荐）：/api/link/{code}/status
2. 查询参数格式（兼容旧版）：/api/link/status?code={code}

支持的访问方式

方式一：路径参数（推荐 ⭐）

接口： GET /api/link/{code}/status

示例：

curl http://localhost:8080/api/link/ABC12345/status

// JavaScript
fetch('/api/link/ABC12345/status')

优势：

• ✅ 复制粘贴时不会丢失参数
• ✅ 符合 RESTful 设计规范
• ✅ URL 结构更清晰
• ✅ 浏览器地址栏直接可见完整路径

---

方式二：查询参数（兼容旧版）

接口： GET /api/link/status

支持的参数：

• code - 链接编号（推荐）
• codeNo - 链接编号（别名）
• linkId - 链接数据库ID

示例：

# 使用 code 参数
curl "http://localhost:8080/api/link/status?code=ABC12345"

# 使用 codeNo 参数
curl "http://localhost:8080/api/link/status?codeNo=ABC12345"

# 使用 linkId 参数
curl "http://localhost:8080/api/link/status?linkId=123"

// JavaScript
fetch('/api/link/status?code=ABC12345')
fetch('/api/link/status?codeNo=ABC12345')
fetch('/api/link/status?linkId=123')

说明：

• linkId 和 code/codeNo 至少提供一个即可
• 如果同时提供，优先使用 codeNo，其次是 code

---

响应格式

两种方式返回完全相同的数据结构：

{
  "status": "NEW",
  "machineId": null
}

status 可能的值：

• NEW - 新建
• USING - 使用中（前端会显示为 NEW）
• LOGGED_IN - 已登录
• COMPLETED - 已完成
• REFUNDED - 已退款
• EXPIRED - 已过期

---

测试用例

测试 1：路径参数方式

# 假设有一个 codeNo 为 ABC12345 的链接
curl http://localhost:8080/api/link/ABC12345/status

期望结果： 返回链接状态信息

---

测试 2：查询参数方式（code）

curl "http://localhost:8080/api/link/status?code=ABC12345"

期望结果： 返回与测试1相同的结果

---

测试 3：查询参数方式（codeNo）

curl "http://localhost:8080/api/link/status?codeNo=ABC12345"

期望结果： 返回与测试1相同的结果

---

测试 4：查询参数方式（linkId）

# 假设链接的数据库 ID 为 123
curl "http://localhost:8080/api/link/status?linkId=123"

期望结果： 返回链接状态信息

---

测试 5：错误处理

# 不存在的链接
curl http://localhost:8080/api/link/INVALID/status

# 空参数
curl "http://localhost:8080/api/link/status?code="

# 缺少参数
curl "http://localhost:8080/api/link/status"

期望结果： 返回错误信息

---

迁移建议

对于新开发的前端

推荐使用路径参数格式：

const codeNo = 'ABC12345';
const response = await fetch(`/api/link/${codeNo}/status`);

对于现有系统

无需修改，查询参数格式继续有效：

// 继续使用旧格式
const response = await fetch(`/api/link/status?code=${codeNo}`);

渐进式迁移

可以逐步将旧代码迁移到新格式：

// 旧代码
async function getLinkStatus_Old(codeNo) {
    return fetch(`/api/link/status?code=${codeNo}`);
}

// 新代码（推荐）
async function getLinkStatus_New(codeNo) {
    return fetch(`/api/link/${codeNo}/status`);
}

---

后端实现说明

Controller 方法

系统提供了两个独立的 Controller 方法：

1. getUserLinkStatusByPath - 处理路径参数请求

   • 路由：GET /api/link/{code}/status
   • 参数：@PathVariable String code

2. getUserLinkStatusByQuery - 处理查询参数请求

   • 路由：GET /api/link/status
   • 参数：@RequestParam Long linkId, @RequestParam String codeNo, @RequestParam String code

日志区分

两个方法使用不同的日志标识，便于问题排查：

• 路径参数：=== 用户端获取链接状态（路径参数） ===
• 查询参数：=== 用户端获取链接状态（查询参数，兼容模式） ===

---

兼容性保证

• ✅ 两种格式返回完全相同的数据结构
• ✅ 旧链接继续有效，无需修改
• ✅ 新生成的链接推荐使用路径参数格式
• ✅ 系统会长期维护两种格式的支持
• ✅ 不会影响现有功能和性能

---

常见问题

Q1: 为什么推荐使用路径参数格式？

A: 路径参数格式的优势：

1. 复制粘贴 URL 时不会丢失参数（查询参数容易在 ? 后被截断）
2. 符合 RESTful API 设计规范
3. URL 更清晰，更容易阅读和理解
4. 浏览器地址栏显示更完整

Q2: 旧链接会失效吗？

A: 不会。查询参数格式会长期保持支持，确保兼容性。

Q3: 能否混合使用两种格式？

A: 可以。同一个应用中可以同时使用两种格式，系统都会正确处理。

Q4: 性能上有区别吗？

A: 没有。两种格式调用相同的底层服务方法，性能完全一致。

Q5: 如何在 Swagger/OpenAPI 中查看？

A: Swagger UI 会显示两个独立的接口：

• GET /api/link/{code}/status - 推荐格式
• GET /api/link/status - 兼容格式

---

更新日志

• 2025-10-21：添加路径参数格式支持，同时保留查询参数格式兼容性
• 旧的查询参数格式标记为"兼容模式"，推荐新项目使用路径参数格式