企业官网建设流程全解析

系列12-接口压测怎么做成平台能力？自研 httpx 引擎、分布式 Worker 与 Locust 选型对照

团队做性能测试，常见两条路：

1. Locust / 自写脚本：灵活，但 URL/Body/Token 与接口回归两套维护，报告散落本地 HTML
2. JMeter GUI：功能全，但 XML 难维护，CI 集成重

BrickCore 选第三条：复用接口自动化用例（ApiTestCase）+ asyncio/httpx 自研压测引擎，可选Perf Worker水平加并发。

需要先说清一点：平台没有嵌入 Locust，Docker 镜像也不带 Locust 依赖；执行层借鉴 Locust 的并发用户 / Ramp-up / 分布式 Worker产品思路，HTTP 请求与变量替换与run_single_case同源（build_perf_request→ httpx）。

演示与源码

线上路径：性能测试 → 场景管理 / 执行机 / 执行记录。Worker 推荐BrickCoreRunner v1.3.14+选「压测执行机」角色上线。

一、平台化压测要解决什么

二、架构一图读懂

PerfScene（场景：scene_items + config + csv） ↓ POST /perf/exec/{scene_id}?use_workers= PerfRecord（config_snapshot 不可变快照） ↓ run_perf_scene（BackgroundTasks） ┌─────────────────┬──────────────────────────┐ │ 本机 asyncio │ 分布式 use_workers=true │ │ Backend httpx │ distribute_concurrent │ │ 虚拟用户协程池 │ → Perf Worker（perf_worker）│ └─────────────────┴──────────────────────────┘ ↓ 秒级聚合 time_series_data 报告：QPS / P95 / error_rate / case_aggregations / phase_metrics

与 UI Runner 分工：Perf Worker 只跑HTTP 压测；UI Runner 跑 Playwright，队列协议不同（系列09）。

三、数据模型

PerfScene ├─ scene_items: [{case_id, weight, delay_ms}, ...] ├─ config: {mode, concurrent_users, ramp_up_seconds, ...} └─ csv_data + csv_config PerfRecord（一次执行） ├─ config_snapshot / scene_items_snapshot ├─ total_requests, qps, p95, error_rate, time_series_data ├─ case_aggregations（接口维度） ├─ phase_metrics / request_details（SSE 场景） └─ distribution_info（分布式 Worker 分配） PerfWorker ├─ register / heartbeat / unregister ├─ max_concurrent └─ project_id（须与场景项目一致）

快照设计：场景事后被改，历史报告仍对应当时的配置与用例列表——发版对比靠record_id，不靠「还记得上次参数」。

四、五种压测模式

固定/循环/梯度模式还可勾选流式问答：在持续压测中对指定用例走 SSE 引擎（use_stream_execution）。

场景项示例（权重 + 思考时间，概念对齐 Locust@task(weight)+between）：

[{"case_id":101,"weight":3,"delay_ms":500},{"case_id":102,"weight":1,"delay_ms":0}]

配置示例：

{"mode":"fixed","concurrent_users":50,"ramp_up_seconds":10,"duration_seconds":120,"error_rate_threshold":5,"request_detail_level":"brief"}

error_rate_threshold：错误率连续 3 秒超阈值自动停压（workers.py中ERROR_RATE_AUTO_STOP_MSG）。

五、执行链路（源码）

5.1 启动

# routers/perf/exec.py — start_perfrecord=awaitPerfRecord.create(scene_id=scene_id,status="pending",trigger_type="manual",config_snapshot=config,scene_items_snapshot=scene.scene_items,)background_tasks.add_task(run_perf_scene,record.id,use_workers)

5.2 run_perf_scene 核心步骤

1. 读快照，解析env_id、Host（可target_host覆盖环境）
2. Host 连通性探测（HEAD），失败则record.status=failed
3. 预加载ApiTestCase+ApiDefinition，merge_execution_variables合并项目/环境变量
4. 构建scene_items_for_worker（含 merged headers/body，减少 Worker 侧查库）
5. 分支：本机 asyncio或分布式 Worker

5.3 本机：虚拟用户 + 信号量

# _perf_worker_fixed：random.choices(case_pool, weights=...) 按 weight 选接口asyncwithsem:# sem = concurrent_usersresult=await_execute_perf_case_request(case,env,target_host,client,csv_row,...)ifdelay_ms>0:awaitasyncio.sleep(delay_ms/1000)

_execute_perf_case_request走 httpx，成功判定：status < 500 且断言通过（与功能回归同源断言逻辑）。

5.4 分布式：并发拆分

# routers/perf/workers.py — distribute_concurrent# 按各 Worker max_concurrent 比例分配，且不超过单节点上限assignments=distribute_concurrent(total_concurrent,workers)

Worker 侧引擎与 Backend同一套runner/perf_worker.py（BrickCoreRunner 内置或命令行启动），秒级指标 POST/workers/{record_id}/report，结束后finalize汇总。

硬约束：journey_*模式若含阶段sync_before屏障，不支持分布式——引擎会直接 failed 并提示改单机执行（journey_has_sync_barrier校验）。

六、复用接口用例：变量与断言

压测不另写 locustfile，请求构建走build_perf_request：

all_variables=ensure_dt_cache(awaitmerge_execution_variables(case.project_id,env.id))# + csv_row 列 → ${{username}}# + journey 步骤间 session_variables（extractors）method,url,headers,params,body,timeout,body_type=...

实操：压测前用接口用例单跑确认 Host、Token、Body；再挂到场景里加权。

七、CSV 参数化

csv_data存 JSON 数组，csv_config.strategy：

分布式下get_next_csv_row(..., worker_id, total_workers)避免多 Worker 抢同一行。

八、Perf Worker 部署（推荐 BrickCoreRunner）

8.1 客户端方式（推荐）

1. 安装BrickCoreRunner v1.3.14+
2. 登录 → 执行角色仅压测或UI + 压测
3. 选择压测项目（与平台顶部项目 ID 一致）→上线
4. 性能测试 → 执行机确认在线
5. 场景执行勾选使用分布式 Worker

客户端会话区 +runner/logs/perf_worker.log可看秒级 QPS/RT；下线自动unregister，不必等心跳超时。

8.2 命令行（CI / 高级）

cdrunner python perf_worker.py--masterhttp://你的平台地址\--tokenmy-local-token\--name"压测机-01"\--max-concurrent200\--project-id 当前项目ID

生产环境浏览器访问一般为80 端口（Nginx），--master不要写 :8000。

8.3 何时勾选 Worker

九、流式 / SSE 与大模型压测

stream_burst模式 +stream_profile.parser_id（默认qa_sse_v1）：

• 每用户一次完整 SSE 会话
• 采集：首字时间、思考耗时、各阶段 RT→phase_metrics
• 报告支持SSE 阶段汇总、流式明细懒加载、导出 Excel
• request_detail_level=detailed可保留成功 trace，不影响 QPS/RT 聚合

固定/循环/梯度模式也可对指定用例勾选流式执行，适合「混合流量里夹 SSE 接口」。

十、业务链路（Journey）

journey_fixed/journey_loop：多phase顺序/并行，步骤间extractors → session_variables，等价压测版「登录→下单」：

{"mode":"journey_fixed","concurrent_users":20,"duration_seconds":300,"journey":{"phases":[{"name":"登录","execution":"serial","steps":[{"case_id":101,"delay_ms":0}]},{"name":"下单","execution":"serial","sync_before":false,"steps":[{"case_id":102,"delay_ms":200}]}]}}

sync_before: true为阶段屏障（全链路用户齐步走）——仅单机；分布式请关闭或改journey_fixed单机压测。

十一、报告读什么

分位采样说明：接口维度 P90/P95/P99 基于最多 5000 条RT 样本（蓄水池采样，MAX_CASE_RT_SAMPLES）；总请求数、QPS、错误率、Min/Max 仍统计全量。超大规模压测时分位为近似值，报告页有说明。

支持多 record 对比、HTML 导出、完成后邮件/钉钉/企微推送（maybe_auto_push_perf_report）。

十二、与 Locust 选型对照

外部仍有 Locust 脚本时，结果需自行对接；平台侧重与接口资产、定时任务、看板一体。

十三、发版前压测 SOP

1. 场景：核心 3～5 个接口，weight按生产流量比例
2. 环境：独立压测环境，勿误打生产
3. 冒烟：10 并发 × 60s 本机验证用例与 CSV
4. 加压：stepping或提高concurrent_users，勾选 Worker
5. 阈值：设error_rate_threshold（如 5%）
6. 对比：与同场景上一版record_id比 P95、error_rate
7. 归档：评审贴 record 链接；可选定时压测（PerfCronJob+use_workers）

十四、常见排错

十五、小结

1. 平台压测 =ApiTestCase 资产 + asyncio/httpx 自研引擎，不是嵌入 Locust。
2. 五种模式覆盖稳态、梯度、SSE、业务链路；快照保证报告可追溯。
3. Perf Worker与 Backend同引擎，distribute_concurrent按容量比例拆并发。
4. CSV + 变量合并与接口回归同源；报告支持对比、SSE 阶段、自动停压与通知。

附录 A：源码文件索引

选型背景（docs/ROADMAP.md）：零 Locust 依赖、直接复用接口用例变量/断言，Docker 部署更轻。

支持与交流

• 演示：http://43.142.83.156/showcase/ · 源码：https://gitee.com/BanZhuanKeOrz/BrickCore
• 觉得有用欢迎Star⭐，问题评论区留言或 Gitee Issues