Files
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

17 KiB
Raw Permalink Blame History

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(推荐)

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 优化查询

// 只查询需要的字段,减少网络传输
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. 提取测试参数

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

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天),适合大批量测试

完整示例:

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: 统计数据(汇总信息)"

方法二:手动管理线程池(适合需要自定义控制的场景)

点击展开手动管理线程池的示例代码
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, "测试结果")

第三步:运行测试流程

1. 构建项目

cd deliverables/script
mvn clean package -Dmaven.test.skip=true

2. 提取测试数据

groovy -cp "target/classes;target/classes/lib/*" \
  projects/fangjia-script/src/main/groovy/com/fangjia/script/opentest/XXXTestDataExtractor.groovy

3. 启动fangjia-open服务

cd deliverables/fangjiaopen
mvn tomcat7:run

4. 运行接口测试

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:
    // ❌ 错误
    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图表(饼图、柱状图)便于可视化分析
  • 保存多次测试结果,对比性能变化趋势
  • 将测试报告作为接口验收的依据