埋点分析系统 API 测试报告

📅 2026-07-30 📂 obsidian ⏱ 约 20 分钟
📑 目录
  1. 一、测试概览
  2. 二、逐个API测试结果
  3. 三、错误情况测试
  4. 四、数据质量评估
  5. 五、问题汇总
  6. 六、结论

埋点分析系统 API 测试报告

测试日期: 2026-07-30 测试环境: http://127.0.0.1:5000 登录凭据: admin / clklog 测试日期范围: 2026-07-24 ~ 2026-07-30

一、测试概览

统计项数值
测试API总数20
成功 (HTTP 200)18
失败 (HTTP 401)2
包含data字段17
存在数据问题4

二、逐个API测试结果

1. POST /api/auth/login （登录）

项目结果
HTTP状态码200
是否成功是
返回数据data对象包含token字段
数据摘要成功获取Bearer Token

结论: 正常。

2. GET /api/overview/kpi （概览KPI）

项目结果
HTTP状态码200
是否成功是
返回字段activeusers, avgsessionduration, pv, totalevents
数据结构每个字段为 {trend, value} 对象
异常无

数据示例:

{
  "active_users": {"trend": -0.3, "value": 16339},
  "avg_session_duration": {"trend": ..., "value": ...},
  "pv": {"trend": ..., "value": ...},
  "total_events": {"trend": ..., "value": ...}
}

结论: 正常，无null值，无负数异常。

3. GET /api/events/distribution （事件分布）

项目结果
HTTP状态码200
是否成功是
返回字段data (嵌套对象), labels
数据量labels: 10条, data: 10条
异常无

结论: 正常。注意data返回的是嵌套对象而非数组，分页参数在distribution中的含义需确认。

4. GET /api/events/list （事件列表）

项目结果
HTTP状态码200
是否成功是
返回字段list, page, page_size, total
分页信息page=1, page_size=10, total=166
列表记录数10条
单条字段avgperuser, event, eventtype, screenname, trend, triggercount, usercount

结论: 分页正确，total=166，返回10条记录，无null字段。

5. GET /api/users/kpi （用户KPI）重点关注

项目结果
HTTP状态码200
是否成功是
返回字段activeusers, newusers, retentionrate, totalusers
数据格式每个字段为 {trend, value}

完整数据:

{
  "active_users":    {"trend": -0.3,  "value": 16339},
  "new_users":       {"trend": 214.7, "value": 107},
  "retention_rate":  {"trend": null,  "value": 50.0},
  "total_users":     {"trend": 3.4,   "value": 29026}
}

留存率分析:

  • retention_rate.value = 50.0 (类型: Decimal，数值合理，表示50%)
  • retention_rate.trend = null --- 问题确认

结论: 留存率数值本身（50.0%）看起来合理，但 trend 字段为 null，这是之前提到的bug。其他字段正常。

6. GET /api/users/trend （用户趋势）

项目结果
HTTP状态码200
是否成功是
返回字段labels, newusers, totalusers
数据量labels: 7, newusers: 7, totalusers: 7

结论: 7天数据完整，数组长度一致，无异常。

7. GET /api/screens/flow （页面流转）

项目结果
HTTP状态码200
是否成功是
返回字段data, labels
数据量labels: 10, data: 10

结论: 正常。

8. GET /api/elements/kpi （元素KPI）

项目结果
HTTP状态码200
是否成功是
返回字段totalclicks, uniqueelements, uniquescreens, uniqueusers

结论: 正常，无null字段。

9. GET /api/detail/events （事件明细）

项目结果
HTTP状态码200
是否成功是
返回字段list, page, page_size, total
分页信息page=1, page_size=20, total=255891
列表记录数20条
单条字段city, clientip, devicemodel, distinctid, elementcontent, elementname, elementtype, event, eventtype, logtime, networktype, osfull, province, screen_name

结论: 分页正确，total=255891，返回20条记录，字段完整。

10. GET /api/detail/filters （过滤器列表）

项目结果
HTTP状态码200
是否成功是
返回字段devices, events, os_list, provinces

结论: 正常，返回了所有可用的筛选选项。

11. GET /api/flow/overview （流程概览）

项目结果
HTTP状态码200
是否成功是
返回字段current, previous, samePeriod

完整数据:

{
  "current":    {"avgPv": 0.0, "avgVisitTime": 0, "bounceRate": 0.0, "ipCount": 0, "pv": 0, "uv": 0, "visitCount": 0},
  "previous":   {"avgPv": 0.0, "avgVisitTime": 0, "bounceRate": 0.0, "ipCount": 0, "pv": 0, "uv": 0, "visitCount": 0},
  "samePeriod": {"avgPv": 0.0, "avgVisitTime": 0, "bounceRate": 0.0, "ipCount": 0, "pv": 0, "uv": 0, "visitCount": 0}
}

问题: 三个时间段的数据全部为0。这可能表示流程数据未采集、数据表结构不匹配、或该功能模块依赖的数据源未启用。需要进一步排查。

结论: 返回结构正确，但数据全为0属于异常，建议排查数据源。

12. GET /api/health （健康检查）

项目结果
HTTP状态码200
是否成功是
返回内容{"code":0,"data":null,"message":"ok"}
data字段null

结论: 服务运行正常（HTTP 200），但data字段为null。这可能是有意设计（health检查不需要返回数据），但与其他API的返回格式不一致。

13. GET /api/projects （项目列表）

项目结果
HTTP状态码200
是否成功是
返回格式数组
数据量1个项目

数据:

{
  "event_count": 2918345,
  "project_name": "qianlongapp",
  "project_token": "5388ed7459ba4c4cad0c8693fb85630a",
  "user_count": 29026
}

结论: 正常，返回1个项目，数据完整。

14. GET /api/env/list （环境列表）

项目结果
HTTP状态码200
是否成功是
返回格式数组
数据量2个环境

数据:

  • "生产环境" (production) - host: 114.80.38.24:9000
  • "测试环境" (test) - host: 192.168.20.147:9000

结论: 正常。

15. GET /api/env/current （当前环境）

项目结果
HTTP状态码200
是否成功是
当前环境production (114.80.38.24)

结论: 正常，当前连接生产环境。

三、错误情况测试

3.1 不带Token访问受保护API

测试端点预期实际结果
GET /api/overview/kpi401401通过
  • 返回401状态码，但响应Body为空，没有返回JSON格式的错误信息（如 {"code":401,"message":"未授权"}）

3.2 无效Token访问

测试端点预期实际结果
GET /api/overview/kpi (Bearer invalidtoken12345)401401通过
  • 返回401状态码，同样响应Body为空。

3.3 缺少必要参数

测试端点缺失参数预期实际结果
/api/overview/kpi?end_date=2026-07-30start_date400200不通过
/api/overview/kpi?start_date=2026-07-24end_date400200不通过
/api/overview/kpi?startdate=abc&enddate=xyz无效日期400200不通过

问题: 缺少必要参数和无效日期格式时，API返回200而非400，只是返回了空数据。建议后端增加参数校验，返回明确的错误信息。

四、数据质量评估

4.1 数值合理性

API字段值评估
users/kpiactive_users.value16339合理
users/kpinew_users.value107合理
users/kpitotal_users.value29026合理
users/kpiretention_rate.value50.0合理（50%留存率）
projectsevent_count2918345合理（约292万事件）
projectsuser_count29026与users/kpi一致
detail/eventstotal255891合理
events/listtotal166合理（事件类型数）

4.2 Null值检测

API字段值是否问题
users/kpiretention_rate.trendnull是 - Bug
healthdatanull可能是有意设计

4.3 全零数据

API字段值是否问题
flow/overviewcurrent.*全部为0是 - 需排查
flow/overviewprevious.*全部为0是 - 需排查
flow/overviewsamePeriod.*全部为0是 - 需排查

4.4 分页正确性

APItotalpagepage_size实际返回一致性
events/list16611010条正确
detail/events25589112020条正确

五、问题汇总

严重问题（2个）

#问题影响API描述
1留存率趋势为null/api/users/kpiretention_rate.trend = null，前端可能因此显示异常
2流程概览数据全为0/api/flow/overviewcurrent/previous/samePeriod 三个时段所有指标均为0

中等问题（1个）

#问题影响API描述
3缺少参数校验/api/overview/kpi 等缺少startdate/enddate/无效日期格式时返回200而非400

轻微问题（2个）

#问题影响API描述
4401响应Body为空所有需认证API未认证时返回空Body，建议返回JSON格式错误信息
5health接口data为null/api/health与其他API返回格式不一致

六、结论

  1. 核心功能正常: 15个API端点中，14个认证API均返回200，认证拦截机制正常工作（401）。
  2. 留存率Bug确认存在: retention_rate.trend 为 null，前端可能因此无法正确显示趋势箭头或百分比变化。
  3. 流程概览数据缺失: flow/overview 三个时段数据全为0，建议检查数据采集管道或ClickHouse查询逻辑。
  4. 参数校验缺失: 缺少日期参数时不返回400错误，前端无法有效提示用户。
  5. 数据一致性良好: projects中的usercount与users/kpi中的totalusers一致（均为29026），说明数据源一致。
obsidian

📎 相关文章

📊 股票代码总索引

title股票代码总索引 created20260805 updated20260805 tags[股票代码, 索引, MOC] 📊 股票代码总索引 [!inf...

科技股下半年机会

date20260720 updated20260720 conversation_idf21364a807fd487da6923432916c6b30 tit...

社交数据 - 社交数据

社交数据 社交数据 共 36 张数据表 标签#数据字典 #13_社交数据 表列表 表名 中文名 字段数 说明 [[T_SOC]] 新三板代码表 7 [[T_SO...