Files
main/.claude/skills/fangjia-openapi-dev/references/api-testing-guide.md
T
admin 106d0cdbad 新增小区第三方均价接口(ApiCode:3004)及测试脚本
- AverageStatistics 新增 xingfuliEsfPrice、maitianEsfPrice 字段
- AverageStatisticsService 新增 findRecentMonths 方法(查询最近N个月数据)
- PropertyController 新增 thirdPartyPriceAction(/property/thirdPartyPrice)
  - 返回幸福里、安居客、房天下、链家、城市房产、吉屋、淘房365、麦田均价
  - 仅取二手房价格,最多回溯3个月补全空值
- 新增 opentest 测试脚本:数据提取 + 多线程接口测试
- 更新 claude 技能文档:修正本地端口、seaweed集合字段说明、Groovy static 限制

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-02 16:27:26 +08:00

520 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API接口测试指南
接口开发完成后,需要进行系统化测试。本指南提供完整的测试流程和脚本组织方式。
## 测试脚本目录结构
在 `projects/fangjia-script/src/main/groovy/com/fangjia/script/` 下创建专门的测试包:
```
opentest/ # 接口测试脚本专用包
├── [InterfaceName]TestDataExtractor.groovy # 数据提取脚本
├── [InterfaceName]InterfaceTest.groovy # 接口测试脚本
└── data/ # 测试数据目录
├── [interface]_test_data.xlsx # 测试数据(自动生成,单Sheet)
└── [interface]_test_result.xlsx # 测试结果(自动生成,多Sheet)
# - Sheet1: 测试结果(详细数据)
# - Sheet2: 统计数据(汇总信息)
```
**示例**:E基金地址匹配接口测试
```
opentest/
├── EfundTestDataExtractor.groovy
├── EfundInterfaceTest.groovy
└── data/
├── efund_test_data.xlsx # 测试数据
└── efund_test_result.xlsx # 测试结果
├── Sheet1: 测试结果 # 1000行详细数据
└── Sheet2: 统计数据 # 汇总统计信息
```
## 第一步:编写数据提取脚本
**目的**:从生产环境提取真实测试数据
**关键技术**:
### 1. 使用 Mongo3Utils 连接MongoDB(推荐)
```groovy
import com.fangjia.core.Constants
import com.fangjia.core.util.Mongo3Utils
import com.mongodb.client.MongoCollection
import org.bson.Document
// 连接206服务器
MongoCollection<Document> coll = Mongo3Utils.getDbCollection(
Constants.SEAWATER_MONGO_URI, // 已配置好的连接URI
"business", // 数据库
"open_uri_log" // 集合
)
```
### 2. 使用 projection 优化查询
```groovy
// 只查询需要的字段,减少网络传输
Document query = new Document("user_id", "xxx")
.append("request_uri", "/api/xxx")
Document projection = new Document("parameter_map", 1).append("_id", 0)
MongoCursor<Document> cursor = coll.find(query)
.projection(projection) // 只返回 parameter_map
.limit(1000)
.iterator()
```
### 3. 提取测试参数
```groovy
List<List<Object>> excelData = []
excelData << ["序号", "参数1", "参数2", "参数3"] // 表头
int index = 0
while (cursor.hasNext()) {
Document doc = cursor.next()
Document paramMap = doc.get("parameter_map", Document.class)
String param1 = paramMap?.getString("param1") ?: ""
String param2 = paramMap?.getString("param2") ?: ""
excelData << [++index, param1, param2]
}
```
### 4. 保存到Excel
```groovy
import com.fangjia.script.util.ExcelUtils
// 自动确定脚本所在目录
String scriptDir = new File(getClass().protectionDomain.codeSource.location.path).parent
String dataDir = new File(scriptDir, "data").absolutePath
new File(dataDir).mkdirs()
String outputFile = "${dataDir}${File.separator}test_data.xlsx"
ExcelUtils.write(outputFile, excelData, "测试数据")
```
## 第二步:编写接口测试脚本
**目的**:多线程调用接口,记录结果和性能指标
**推荐方法**:使用 `ExcelUtils.multiThreadingModify` 工具类(自动管理线程池和进度监控)
### 方法一:使用 ExcelUtils.multiThreadingModify(推荐)
**优势**:
- ✅ 自动管理线程池(CPU核心数×4)
- ✅ 自动处理线程安全
- ✅ 自动进度监控(每1000条打印进度和百分比)
- ✅ 代码简洁,专注业务逻辑
- ✅ 超长等待时间(30天),适合大批量测试
**完整示例**:
```groovy
import com.fangjia.core.util.HttpRequest
import com.fangjia.script.util.ExcelUtils
import net.sf.json.JSONObject
// 1. 准备测试数据和结果Excel
String scriptDir = new File(getClass().protectionDomain.codeSource.location.path).parent
String dataDir = new File(scriptDir, "data").absolutePath
String inputFile = "${dataDir}${File.separator}test_data.xlsx"
String outputFile = "${dataDir}${File.separator}test_result.xlsx"
// 2. 读取所有数据(包括表头)
List<List<Object>> allData = ExcelUtils.read(inputFile, 0, 0)
// 3. 修改表头,添加结果列
allData[0] = ["序号", "参数1", "参数2", "返回字段1", "返回字段2",
"返回字段3", "耗时(ms)", "异常信息"]
// 4. 为每行数据添加空的结果列
for (int i = 1; i < allData.size(); i++) {
List row = allData[i]
(3..7).each { row << "" } // 添加5个结果列
}
// 5. 写入初始结果文件
ExcelUtils.write(outputFile, allData, "测试结果")
// 6. 使用 multiThreadingModify 多线程调用接口
ExcelUtils.multiThreadingModify(outputFile, { List row ->
HttpRequest request = new HttpRequest()
long startTime = System.currentTimeMillis()
try {
// 提取参数(row[0]=序号, row[1]=参数1, row[2]=参数2)
String param1 = row[1]?.toString() ?: ""
String param2 = row[2]?.toString() ?: ""
// 调用接口
Map<String, String> params = ["param1": param1, "param2": param2]
String response = request.get("http://localhost:9180/api/xxx", params, "UTF-8")
long duration = System.currentTimeMillis() - startTime
// 解析响应
JSONObject json = JSONObject.fromObject(response)
Integer code = json.optInt("code")
JSONObject result = json.optJSONObject("result")
if (code == 200 && result != null) {
// 成功:填充结果列(直接修改row,工具类自动处理线程安全)
row[3] = result.optString("field1", "")
row[4] = result.optString("field2", "")
row[5] = result.optString("field3", "")
row[6] = duration
row[7] = "" // 无异常
} else {
// 失败:记录错误信息
row[6] = duration
row[7] = "接口返回错误(code=${code}): ${json.optString('msg', '')}"
}
} catch (Exception e) {
// 异常:记录异常信息
long duration = System.currentTimeMillis() - startTime
row[6] = duration
row[7] = "异常: ${e.class.simpleName} - ${e.message}"
}
}, 0, "测试结果")
// 7. 读取结果并统计
List<List<Object>> finalData = ExcelUtils.read(outputFile, 0, 0)
int totalCount = finalData.size() - 1
int successCount = 0
int failCount = 0
long totalTime = 0
// 耗时分布统计
Map<String, Integer> timeDist = [
"<100ms": 0,
"100-200ms": 0,
"200-500ms": 0,
"500-1000ms": 0,
">1000ms": 0
]
for (int i = 1; i < finalData.size(); i++) {
List row = finalData[i]
String errorMsg = row[7]?.toString() ?: ""
if (errorMsg == "") {
successCount++
// 统计耗时
if (row[6] instanceof Number) {
int duration = ((Number)row[6]).intValue()
totalTime += duration
if (duration < 100) timeDist["<100ms"]++
else if (duration < 200) timeDist["100-200ms"]++
else if (duration < 500) timeDist["200-500ms"]++
else if (duration < 1000) timeDist["500-1000ms"]++
else timeDist[">1000ms"]++
}
} else {
failCount++
}
}
// 8. 保存统计数据到新Sheet
List<List<Object>> statsData = []
statsData << ["统计项", "数值"]
statsData << ["测试时间", new Date().format("yyyy-MM-dd HH:mm:ss")]
statsData << ["", ""]
statsData << ["总测试数", totalCount]
statsData << ["成功数", successCount]
statsData << ["失败数", failCount]
statsData << ["成功率", totalCount > 0 ? String.format('%.2f%%', successCount * 100.0 / totalCount) : '0.00%']
if (successCount > 0) {
int avgTime = (totalTime / successCount).intValue()
statsData << ["", ""]
statsData << ["平均耗时(ms)", avgTime]
// 耗时分布
statsData << ["", ""]
statsData << ["耗时分布", "数量"]
timeDist.each { range, count ->
statsData << [range, count]
}
}
// 添加统计Sheet
ExcelUtils.write(outputFile, statsData, "统计数据")
// 9. 控制台输出统计结果
println "\n========== 测试完成 =========="
println "总测试数:${totalCount}"
println "成功数:${successCount}"
println "失败数:${failCount}"
println "成功率:${totalCount > 0 ? String.format('%.2f%%', successCount * 100.0 / totalCount) : '0.00%'}"
if (successCount > 0) {
int avgTime = (totalTime / successCount).intValue()
println "平均耗时:${avgTime} ms"
println "\n耗时分布:"
timeDist.each { range, count ->
if (count > 0) {
println " ${range}: ${count} 条"
}
}
}
println "\n结果文件:${outputFile}"
println " - Sheet1: 测试结果(详细数据)"
println " - Sheet2: 统计数据(汇总信息)"
```
### 方法二:手动管理线程池(适合需要自定义控制的场景)
<details>
<summary>点击展开手动管理线程池的示例代码</summary>
```groovy
import java.util.concurrent.*
import java.util.concurrent.atomic.AtomicInteger
import com.fangjia.core.util.HttpRequest
import net.sf.json.JSONObject
// 1. 读取测试数据
List<List<Object>> testData = ExcelUtils.read(inputFile, 0, 1) // 跳过表头
// 2. 准备结果数据
List<List<Object>> resultData = []
resultData << ["序号", "参数1", "参数2", "返回字段1", "返回字段2", "耗时(ms)", "异常信息"]
testData.each { row ->
List newRow = [row[0], row[1], row[2]]
(3..6).each { newRow << "" }
resultData << newRow
}
// 3. 配置线程池
int nThread = Runtime.getRuntime().availableProcessors() * 4
ExecutorService executorService = Executors.newFixedThreadPool(nThread)
AtomicInteger counter = new AtomicInteger(0)
AtomicInteger successCounter = new AtomicInteger(0)
// 4. 提交任务
testData.eachWithIndex { List testRow, int i ->
final int rowIndex = i + 1
executorService.submit({
HttpRequest request = new HttpRequest()
long startTime = System.currentTimeMillis()
try {
String param1 = testRow[1]?.toString() ?: ""
String response = request.get("http://localhost:9180/api/xxx",
["param1": param1], "UTF-8")
long duration = System.currentTimeMillis() - startTime
JSONObject json = JSONObject.fromObject(response)
JSONObject result = json.optJSONObject("result")
synchronized(resultData) {
if (json.optInt("code") == 200 && result != null) {
resultData[rowIndex][3] = result.optString("field1", "")
resultData[rowIndex][4] = result.optString("field2", "")
resultData[rowIndex][5] = duration
successCounter.incrementAndGet()
} else {
resultData[rowIndex][5] = duration
resultData[rowIndex][6] = "错误: ${json.optString('msg')}"
}
}
} catch (Exception e) {
synchronized(resultData) {
resultData[rowIndex][6] = "异常: ${e.message}"
}
}
if (counter.incrementAndGet() % 100 == 0) {
println "进度: ${counter.get()}/${testData.size()}"
}
} as Runnable)
}
// 5. 等待完成并保存结果
executorService.shutdown()
executorService.awaitTermination(30, TimeUnit.MINUTES)
ExcelUtils.write(outputFile, resultData, "测试结果")
```
</details>
## 第三步:运行测试流程
### 1. 构建项目
```bash
cd deliverables/script
mvn clean package -Dmaven.test.skip=true
```
### 2. 提取测试数据
```bash
groovy -cp "target/classes;target/classes/lib/*" \
projects/fangjia-script/src/main/groovy/com/fangjia/script/opentest/XXXTestDataExtractor.groovy
```
### 3. 启动fangjia-open服务
```bash
cd deliverables/fangjiaopen
mvn tomcat7:run
```
### 4. 运行接口测试
```bash
groovy -cp "target/classes;target/classes/lib/*" \
projects/fangjia-script/src/main/groovy/com/fangjia/script/opentest/XXXInterfaceTest.groovy
```
## Excel结果文件结构
### 测试数据Excel(单Sheet)
| 列 | 字段 | 说明 |
|----|------|------|
| A | 序号 | 1-N |
| B | 参数1 | 接口输入参数 |
| C | 参数2 | 接口输入参数 |
| ... | ... | 更多参数 |
### 测试结果Excel(多Sheet)
#### 📄 Sheet1: 测试结果(详细数据)
| 列 | 字段 | 说明 |
|----|------|------|
| A | 序号 | 同测试数据 |
| B | 参数1 | 同测试数据 |
| C | 参数2 | 同测试数据 |
| D | 返回字段1 | 接口返回结果 |
| E | 返回字段2 | 接口返回结果 |
| ... | ... | 更多返回字段 |
| N | 耗时(ms) | 接口调用耗时 |
| N+1 | 异常信息 | 错误时记录 |
#### 📊 Sheet2: 统计数据(汇总信息)
| 列 | 字段 | 说明 |
|----|------|------|
| A | 统计项 | 统计项名称 |
| B | 数值 | 统计值 |
统计内容包括:
- 测试时间(测试执行的时间戳)
- 总测试数、成功数、失败数、成功率
- 平均耗时(仅统计成功的请求)
- 耗时分布(<100ms、100-200ms、200-500ms、500-1000ms、>1000ms)
示例:
```
| 统计项 | 数值 |
|----------------|----------------------|
| 测试时间 | 2026-02-26 14:30:15 |
| | |
| 总测试数 | 1000 |
| 成功数 | 980 |
| 失败数 | 20 |
| 成功率 | 98.00% |
| | |
| 平均耗时(ms) | 245 |
| | |
| 耗时分布 | 数量 |
| <100ms | 120 |
| 100-200ms | 350 |
| 200-500ms | 480 |
| 500-1000ms | 30 |
| >1000ms | 0 |
```
## 测试脚本最佳实践
### ✅ 推荐做法
1. **MongoDB查询优化**
- 使用 `Mongo3Utils` 而非旧版 `MongoUtils`
- 使用 `projection` 只查询需要的字段
- 使用 `Constants` 中的预定义URI
2. **路径处理**
- 使用相对路径而非硬编码
- 脚本自动识别所在目录:`new File(getClass().protectionDomain.codeSource.location.path).parent`
3. **多线程测试(强烈推荐)**
- **优先使用** `ExcelUtils.multiThreadingModify` 工具方法
- 自动管理线程池(CPU核心数×4)
- 自动处理线程安全(无需手动 synchronized)
- 自动进度监控(每1000条打印进度和百分比)
- 代码简洁,专注业务逻辑
4. **进度监控**
- 使用工具类自动监控(推荐)
- 或手动实现:每100条打印进度,包含时间戳
5. **异常处理**
- 捕获所有异常
- 记录到Excel而非终止程序
- 异常信息包含类型和消息
6. **统计数据保存**
- 使用 `ExcelUtils.write(outputFile, statsData, "统计数据")` 创建统计Sheet
- 统计内容包括:测试时间、成功率、平均耗时、耗时分布
- 方便后续分析和生成测试报告
### ❌ 避免做法
1. ❌ 硬编码文件路径(如 `D:\test\data.xlsx`)
2. ❌ 查询所有字段而不使用 projection
3. ❌ 使用旧版 MongoDB API(`DBObject`、`BasicDBObject`)
4. ❌ 单线程测试大量数据
5. ❌ 异常时终止整个测试
6. ❌ 手动管理线程池(除非有特殊需求,否则用工具类)
7. ❌ 忘记处理线程安全问题(使用工具类可避免)
8. ❌ 脚本顶层使用 `static` 修饰符 — **Groovy 脚本不支持顶层 `static`**,会报编译错误。应改为 `final`:
```groovy
// ❌ 错误
static final String TOKEN = "xxx"
static final String HOST = "http://..."
// ✅ 正确
final String TOKEN = "xxx"
final String HOST = "http://..."
```
## 测试完成后的分析
测试完成后,Excel文件包含两个Sheet,便于多维度分析:
### 📊 使用统计数据Sheet快速分析
1. **成功率分析**:查看成功率是否 >95%
- 低于95%需要排查失败原因
- 在"测试结果"Sheet中过滤"异常信息"列查看失败详情
2. **性能分析**:查看平均耗时和耗时分布
- 平均耗时应 <500ms(根据业务要求调整)
- 耗时分布帮助识别性能瓶颈
- 如果 >1000ms 的数量较多,需优化接口性能
3. **异常分析**:在"测试结果"Sheet中
- 使用Excel筛选功能查看所有失败记录
- 统计异常类型(如超时、参数错误、业务异常等)
- 针对高频异常进行优化
4. **数据质量分析**:在"测试结果"Sheet中
- 检查返回字段的完整性(是否有大量空值)
- 检查价格、匹配级别等核心字段的填充率
- 对比不同匹配级别的数据分布
### 💡 建议
- 将统计数据Sheet制作成Excel图表(饼图、柱状图)便于可视化分析
- 保存多次测试结果,对比性能变化趋势
- 将测试报告作为接口验收的依据