415 lines
11 KiB
Markdown
415 lines
11 KiB
Markdown
# 链接列表接口测试文档
|
||
|
||
## 接口概览
|
||
|
||
**接口地址**: `GET /api/link/list`
|
||
|
||
**功能描述**: 分页查询用户生成的链接列表，支持按状态、批次ID等条件过滤和排序
|
||
|
||
## 请求参数
|
||
|
||
### URL参数
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 示例 |
|
||
|-------|------|------|--------|------|------|
|
||
| page | Integer | 否 | 1 | 页码，从1开始 | 1 |
|
||
| pageSize | Integer | 否 | 20 | 每页大小（1-100） | 20 |
|
||
| status | String | 否 | - | 链接状态过滤 | NEW |
|
||
| batchId | Long | 否 | - | 批次ID过滤 | 123 |
|
||
| isExpired | Boolean | 否 | - | 是否过期过滤 | false |
|
||
| sortBy | String | 否 | createdAt | 排序字段 | createdAt |
|
||
| sortDir | String | 否 | DESC | 排序方向 | DESC |
|
||
|
||
### 状态值说明
|
||
|
||
- `NEW` - 新建
|
||
- `USING` - 使用中
|
||
- `LOGGED_IN` - 已登录
|
||
- `REFUNDED` - 已退款
|
||
- `EXPIRED` - 已过期
|
||
|
||
### 排序字段说明
|
||
|
||
- `createdAt` - 创建时间
|
||
- `updatedAt` - 更新时间
|
||
- `expireAt` - 过期时间
|
||
|
||
## 响应格式
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"codeNo": "ABC12345",
|
||
"batchId": 123,
|
||
"status": "NEW",
|
||
"statusDesc": "新建",
|
||
"expireAt": "2024-01-15 16:30:00",
|
||
"isExpired": false,
|
||
"remainingSeconds": 7200,
|
||
"quantity": 50,
|
||
"times": 5,
|
||
"totalPoints": 250,
|
||
"region": null,
|
||
"machineId": null,
|
||
"loginAt": null,
|
||
"createdAt": "2024-01-15 12:00:00",
|
||
"updatedAt": "2024-01-15 12:00:00"
|
||
}
|
||
],
|
||
"total": 150,
|
||
"page": 1,
|
||
"pageSize": 20,
|
||
"totalPages": 8,
|
||
"hasNext": true,
|
||
"hasPrev": false
|
||
}
|
||
```
|
||
|
||
## 测试用例
|
||
|
||
### 1. 基本分页查询
|
||
|
||
```bash
|
||
# 查询第一页，每页20条
|
||
curl -X GET "http://localhost:18080/api/link/list?page=1&pageSize=20" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**预期结果**:
|
||
- 返回最新的20条链接记录
|
||
- 按创建时间倒序排列
|
||
- 包含完整的分页信息
|
||
|
||
### 2. 按状态过滤
|
||
|
||
```bash
|
||
# 查询所有新建状态的链接
|
||
curl -X GET "http://localhost:18080/api/link/list?status=NEW" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**预期结果**:
|
||
- 只返回状态为NEW的链接
|
||
- 其他字段正常显示
|
||
|
||
### 3. 按批次ID过滤
|
||
|
||
```bash
|
||
# 查询指定批次的所有链接
|
||
curl -X GET "http://localhost:18080/api/link/list?batchId=123" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**预期结果**:
|
||
- 只返回指定批次的链接
|
||
- 显示该批次的所有链接状态
|
||
|
||
### 4. 按过期状态过滤
|
||
|
||
```bash
|
||
# 查询未过期的链接
|
||
curl -X GET "http://localhost:18080/api/link/list?isExpired=false" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
|
||
# 查询已过期的链接
|
||
curl -X GET "http://localhost:18080/api/link/list?isExpired=true" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**预期结果**:
|
||
- isExpired=false: 只返回未过期的链接
|
||
- isExpired=true: 只返回已过期的链接
|
||
|
||
### 5. 排序测试
|
||
|
||
```bash
|
||
# 按过期时间升序排列
|
||
curl -X GET "http://localhost:18080/api/link/list?sortBy=expireAt&sortDir=ASC" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
|
||
# 按更新时间降序排列
|
||
curl -X GET "http://localhost:18080/api/link/list?sortBy=updatedAt&sortDir=DESC" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**预期结果**:
|
||
- 按指定字段和方向正确排序
|
||
- 数据顺序符合预期
|
||
|
||
### 6. 组合条件查询
|
||
|
||
```bash
|
||
# 查询未过期的新建状态链接，按过期时间升序
|
||
curl -X GET "http://localhost:18080/api/link/list?status=NEW&isExpired=false&sortBy=expireAt&sortDir=ASC&page=1&pageSize=10" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**预期结果**:
|
||
- 同时满足多个条件的链接
|
||
- 正确的排序和分页
|
||
|
||
### 7. 大页码测试
|
||
|
||
```bash
|
||
# 查询第100页
|
||
curl -X GET "http://localhost:18080/api/link/list?page=100&pageSize=20" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**预期结果**:
|
||
- 如果数据不足，返回空数组
|
||
- 分页信息正确显示
|
||
|
||
### 8. 边界值测试
|
||
|
||
```bash
|
||
# 最小页码和页大小
|
||
curl -X GET "http://localhost:18080/api/link/list?page=1&pageSize=1" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
|
||
# 最大页大小
|
||
curl -X GET "http://localhost:18080/api/link/list?page=1&pageSize=100" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**预期结果**:
|
||
- pageSize=1: 只返回1条记录
|
||
- pageSize=100: 返回最多100条记录
|
||
|
||
## 错误测试
|
||
|
||
### 1. 无效参数测试
|
||
|
||
```bash
|
||
# 无效的页码
|
||
curl -X GET "http://localhost:18080/api/link/list?page=0" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
|
||
# 页大小超出限制
|
||
curl -X GET "http://localhost:18080/api/link/list?pageSize=101" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
|
||
# 无效的排序字段
|
||
curl -X GET "http://localhost:18080/api/link/list?sortBy=invalidField" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
|
||
# 无效的排序方向
|
||
curl -X GET "http://localhost:18080/api/link/list?sortDir=INVALID" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**预期结果**:
|
||
- 参数验证失败，返回400错误
|
||
- 或者使用默认值处理
|
||
|
||
### 2. 认证失败测试
|
||
|
||
```bash
|
||
# 无JWT令牌
|
||
curl -X GET "http://localhost:18080/api/link/list" \
|
||
-H "Accept: application/json"
|
||
|
||
# 无效JWT令牌
|
||
curl -X GET "http://localhost:18080/api/link/list" \
|
||
-H "Authorization: Bearer INVALID_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**预期结果**:
|
||
- 返回401未授权错误
|
||
- 不返回任何数据
|
||
|
||
## 性能测试
|
||
|
||
### 1. 响应时间测试
|
||
|
||
```bash
|
||
# 测试响应时间
|
||
time curl -X GET "http://localhost:18080/api/link/list?page=1&pageSize=20" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Accept: application/json"
|
||
```
|
||
|
||
**性能要求**:
|
||
- 响应时间 < 100ms（正常数据量）
|
||
- 响应时间 < 500ms（大数据量）
|
||
|
||
### 2. 并发测试
|
||
|
||
```bash
|
||
# 使用ab工具进行并发测试
|
||
ab -n 100 -c 10 -H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
"http://localhost:18080/api/link/list?page=1&pageSize=20"
|
||
```
|
||
|
||
**性能要求**:
|
||
- 支持至少10个并发用户
|
||
- 无明显性能衰减
|
||
|
||
## 数据验证
|
||
|
||
### 1. 分页计算验证
|
||
|
||
检查以下字段的计算是否正确：
|
||
- `totalPages` = Math.ceil(total / pageSize)
|
||
- `hasNext` = (page * pageSize < total)
|
||
- `hasPrev` = (page > 1)
|
||
|
||
### 2. 时间计算验证
|
||
|
||
检查以下时间字段：
|
||
- `isExpired` 与当前时间和 `expireAt` 的比较
|
||
- `remainingSeconds` 的计算精度
|
||
- 时间格式是否正确
|
||
|
||
### 3. 数据一致性验证
|
||
|
||
- 批次信息与链接任务的关联是否正确
|
||
- `totalPoints` = `quantity` × `times`
|
||
- 状态描述与状态码的对应关系
|
||
|
||
## 测试数据准备
|
||
|
||
### 1. 创建测试批次
|
||
|
||
```bash
|
||
# 生成多个批次的链接用于测试
|
||
curl -X POST http://localhost:18080/api/link/generate \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"times": 5,
|
||
"linkCount": 10
|
||
}'
|
||
```
|
||
|
||
### 2. 模拟不同状态
|
||
|
||
为了测试过滤功能，需要有不同状态的链接：
|
||
- 保持一些链接为NEW状态
|
||
- 将一些链接设置为USING状态
|
||
- 让一些链接过期（修改expire_at时间）
|
||
|
||
## 自动化测试脚本
|
||
|
||
### JavaScript (Node.js)
|
||
|
||
```javascript
|
||
const axios = require('axios');
|
||
|
||
async function testLinkList() {
|
||
const baseURL = 'http://localhost:18080';
|
||
const token = 'YOUR_JWT_TOKEN';
|
||
|
||
const config = {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Accept': 'application/json'
|
||
}
|
||
};
|
||
|
||
try {
|
||
// 测试基本分页
|
||
console.log('测试基本分页...');
|
||
const response = await axios.get(`${baseURL}/api/link/list?page=1&pageSize=5`, config);
|
||
console.log('响应:', response.data);
|
||
|
||
// 验证分页信息
|
||
const { total, page, pageSize, totalPages, hasNext, hasPrev } = response.data;
|
||
console.log(`总数: ${total}, 当前页: ${page}, 总页数: ${totalPages}`);
|
||
console.log(`有下一页: ${hasNext}, 有上一页: ${hasPrev}`);
|
||
|
||
// 测试状态过滤
|
||
console.log('测试状态过滤...');
|
||
const statusResponse = await axios.get(`${baseURL}/api/link/list?status=NEW`, config);
|
||
console.log('NEW状态链接数:', statusResponse.data.items.length);
|
||
|
||
} catch (error) {
|
||
console.error('测试失败:', error.response?.data || error.message);
|
||
}
|
||
}
|
||
|
||
testLinkList();
|
||
```
|
||
|
||
### Python
|
||
|
||
```python
|
||
import requests
|
||
import json
|
||
|
||
def test_link_list():
|
||
base_url = 'http://localhost:18080'
|
||
token = 'YOUR_JWT_TOKEN'
|
||
|
||
headers = {
|
||
'Authorization': f'Bearer {token}',
|
||
'Accept': 'application/json'
|
||
}
|
||
|
||
try:
|
||
# 测试基本分页
|
||
print('测试基本分页...')
|
||
response = requests.get(f'{base_url}/api/link/list?page=1&pageSize=5', headers=headers)
|
||
response.raise_for_status()
|
||
|
||
data = response.json()
|
||
print(f'总数: {data["total"]}, 当前页: {data["page"]}, 总页数: {data["totalPages"]}')
|
||
|
||
# 测试状态过滤
|
||
print('测试状态过滤...')
|
||
status_response = requests.get(f'{base_url}/api/link/list?status=NEW', headers=headers)
|
||
status_response.raise_for_status()
|
||
|
||
print(f'NEW状态链接数: {len(status_response.json()["items"])}')
|
||
|
||
except requests.exceptions.RequestException as e:
|
||
print(f'测试失败: {e}')
|
||
|
||
if __name__ == '__main__':
|
||
test_link_list()
|
||
```
|
||
|
||
## 测试报告模板
|
||
|
||
| 测试项目 | 测试结果 | 响应时间 | 备注 |
|
||
|---------|---------|---------|------|
|
||
| 基本分页查询 | ✅ 通过 | 45ms | 正常 |
|
||
| 状态过滤 | ✅ 通过 | 38ms | 正常 |
|
||
| 批次ID过滤 | ✅ 通过 | 42ms | 正常 |
|
||
| 过期状态过滤 | ✅ 通过 | 40ms | 正常 |
|
||
| 排序功能 | ✅ 通过 | 46ms | 正常 |
|
||
| 组合条件查询 | ✅ 通过 | 52ms | 正常 |
|
||
| 参数验证 | ✅ 通过 | 15ms | 正常 |
|
||
| 认证检查 | ✅ 通过 | 12ms | 正常 |
|
||
| 性能测试 | ✅ 通过 | 平均43ms | 满足要求 |
|
||
|
||
## 总结
|
||
|
||
链接列表接口提供了完整的分页查询功能，支持：
|
||
|
||
1. **灵活的分页** - 支持自定义页码和页大小
|
||
2. **多条件过滤** - 按状态、批次、过期状态等过滤
|
||
3. **多字段排序** - 支持按创建时间、更新时间、过期时间排序
|
||
4. **丰富的数据** - 包含链接状态、奖励信息、时间信息等
|
||
5. **良好的性能** - 使用数据库索引，支持高并发查询
|
||
6. **完善的错误处理** - 参数验证、认证检查等
|
||
|
||
该接口为前端提供了完整的链接管理功能，用户可以方便地查看和管理自己生成的所有链接。
|