# 链接状态接口兼容性说明

## 概述

为了解决链接复制粘贴时参数丢失的问题，同时保证向后兼容，系统现在支持两种访问格式：
1. **路径参数格式**（推荐）：`/api/link/{code}/status`
2. **查询参数格式**（兼容旧版）：`/api/link/status?code={code}`

## 支持的访问方式

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

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

**示例：**
```bash
curl http://localhost:8080/api/link/ABC12345/status
```

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

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

---

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

**接口：** `GET /api/link/status`

**支持的参数：**
- `code` - 链接编号（推荐）
- `codeNo` - 链接编号（别名）
- `linkId` - 链接数据库ID

**示例：**

```bash
# 使用 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
// JavaScript
fetch('/api/link/status?code=ABC12345')
fetch('/api/link/status?codeNo=ABC12345')
fetch('/api/link/status?linkId=123')
```

**说明：**
- `linkId` 和 `code/codeNo` 至少提供一个即可
- 如果同时提供，优先使用 `codeNo`，其次是 `code`

---

## 响应格式

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

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

**status 可能的值：**
- `NEW` - 新建
- `USING` - 使用中（前端会显示为 NEW）
- `LOGGED_IN` - 已登录
- `COMPLETED` - 已完成
- `REFUNDED` - 已退款
- `EXPIRED` - 已过期

---

## 测试用例

### 测试 1：路径参数方式

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

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

---

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

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

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

---

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

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

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

---

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

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

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

---

### 测试 5：错误处理

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

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

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

**期望结果：** 返回错误信息

---

## 迁移建议

### 对于新开发的前端

**推荐使用路径参数格式：**
```javascript
const codeNo = 'ABC12345';
const response = await fetch(`/api/link/${codeNo}/status`);
```

### 对于现有系统

**无需修改，查询参数格式继续有效：**
```javascript
// 继续使用旧格式
const response = await fetch(`/api/link/status?code=${codeNo}`);
```

### 渐进式迁移

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

```javascript
// 旧代码
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**：添加路径参数格式支持，同时保留查询参数格式兼容性
- 旧的查询参数格式标记为"兼容模式"，推荐新项目使用路径参数格式