# 链接列表接口测试文档 ## 接口概览 **接口地址**: `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. **完善的错误处理** - 参数验证、认证检查等 该接口为前端提供了完整的链接管理功能，用户可以方便地查看和管理自己生成的所有链接。