HelloWorld Locust 测试教程

要快速上手 Locust 的 HelloWorld 压力测试：先在有 Python 的机器上 pip 安装 locust，写一个最小的 locustfile.py，定义 HttpUser 子类和用 @task 标记的请求方法，命令行启动 locust（或用 –headless 在 CI 中运行），在 Web UI 或终端里观察吞吐、延迟、失败率等指标，必要时用分布式模式扩展节点并记录自定义指标，从而把真实的负载回放到目标系统并据此优化。

为什么选择 Locust？先把核心概念捋清楚

如果你只是想快速造负载或把用户行为脚本化，Locust 把复杂的负载测试简化成“写 Python 的任务”。它的核心思想是把每个并发用户当成一个类（User），在类里写任务（task），运行时会按你设定的并发用户数和权重来调度。相比传统工具，Locust 更灵活、可扩展且易于与 CI/CD、容器化结合。

几个关键词（理解这些就够开始）

• HttpUser：内置用户类型，附带 requests 风格的 client 用来发 HTTP 请求。
• task：装饰器或方法，用来定义用户会执行的动作（比如访问首页、登录、下单）。
• spawn：生成并发用户的过程，可以在 Web UI 或命令行设置总用户数和速率。
• headless：无界面模式，适合在 CI 或自动化脚本中运行。
• master/worker：分布式模式，用于大规模并发。

准备工作：安装与环境

下面是最实用的安装步骤，按顺序来就行。

• 确保安装了 Python 3.8+（推荐 3.9/3.10），并有 pip。
• 创建虚拟环境（可选，但建议）：python -m venv venv; source venv/bin/activate。
• 安装 locust：pip install locust。
• 如果要运行分布式或 docker，准备好对应机器/镜像与端口开放（默认 8089 Web UI 端口）。

开发工具建议

• 编辑器：VSCode、PyCharm，启用 Python lint/formatter。
• 版本控制：把 locustfile.py 放到项目里，方便 CI 调用。
• 日志与观察：结合 Prometheus/Grafana、或至少把 locust 的 CSV 输出收集起来。

第一个 HelloWorld locustfile 实战

这里我们写一个最简单的示例，模拟用户访问首页并查看接口响应。

# 文件名：locustfile.py
from locust import HttpUser, task, between

class HelloWorldUser(HttpUser):
    wait_time = between(1, 3)

    @task
    def index(self):
        self.client.get("/")

    @task(2)
    def about(self):
        self.client.get("/about")

说明：

• wait_time 控制用户在两次请求间等待的秒数，between(1,3) 表示 1 到 3 秒随机等待。
• @task(2) 表示 about 的权重是 2，index 权重默认是 1，所以 about 被执行频率更高。

运行方式

• 交互式（带 Web UI）：locust -f locustfile.py –host=http://example.com，打开 http://localhost:8089 填入并发用户数和 spawn 速率开始测试。
• 无界面（headless，便于 CI）：locust -f locustfile.py –headless -u 100 -r 10 –run-time 1m –host=http://example.com

如何设计更接近真实用户的场景

真实用户不会每次都只访问一个页面，通常要模拟会话、登录、带 token 的请求、表单/JSON 提交等。

示例：带登录流程的用户

from locust import HttpUser, task, between

class AuthUser(HttpUser):
    wait_time = between(1, 2)

    def on_start(self):
        # 在用户开始时先登录，保存 cookies 或 token
        resp = self.client.post("/api/login", json={"user":"u","pass":"p"})
        self.token = resp.json().get("token")

    @task
    def get_profile(self):
        self.client.get("/api/profile", headers={"Authorization": f"Bearer {self.token}"})

注意点：

• 把登录放在 on_start 可以让每个模拟用户拥有各自的会话。
• 如果需要模拟共享资源（比如同一个账户多用户登录），要根据测试目的调整。

指标怎么看：把数字变成判断

Locust 在 UI/终端会展示一堆指标，关键是把它们和业务目标对应起来。

• Requests/s（吞吐）：单位时间内成功请求数。用于衡量系统处理能力。
• 平均/中位/95/99 延迟：响应时间分布，95/99 分位很关键，反映尾部延迟。
• 失败数/率：任何非 2xx/3xx 的响应、超时都会计为失败，需关注错误类型与堆栈。
• 用户数：并发用户数不是线程数，是逻辑上的并发访客。

如何判断是否达到了瓶颈

• 如果吞吐不再上升且延迟急剧增长，说明后端或某层出现饱和。
• CPU、内存、数据库慢查询、连接数耗尽、网络带宽都可能是原因。
• 借助 APM（如 Pinpoint、SkyWalking）或系统监控同时查看资源使用。

进阶：分布式测试与规模扩展

当单机不能达到目标并发时，使用 master/worker 模式。

• 在 master 节点运行：locust -f locustfile.py –master
• 在 worker 节点运行并连接 master：locust -f locustfile.py –worker –master-host=MASTER_IP
• 注意网络延迟和带宽，若 worker 与目标服务处于同一网络，可能会高估性能。

常见分布式问题

• 时钟不同步会影响日志与统计对齐，确保 NTP 同步。
• 网络带宽成为瓶颈，尤其是大量大响应体时，考虑使用更小的响应或 mock 静态资源。
• 日志与结果收集分散，建议把 CSV/JSON 输出汇总到中心存储。

与 CI、容器化集成

把 Locust 加到 CI 的好处是可以在每次提交或发布前自动回归测试。常见做法是用 Docker 镜像或直接在 CI 里用 headless 模式运行。

# Dockerfile 简单示例
FROM python:3.10
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY locustfile.py .
CMD ["locust", "-f", "locustfile.py", "--headless", "-u", "200", "-r", "10", "--run-time", "2m", "--host", "http://example.com"]

在 CI 中运行时，要把测试结果（CSV、HTML）上传为构建产物，便于失败回放与趋势对比。

自定义指标与复杂场景

Locust 支持自定义事件和 metrics，适用于业务 KPI 监控（例如订单成功率、支付延迟）。

from locust import events, stats

# 在代码里记录自定义度量
events.request.fire(request_type="custom", name="order_created", response_time=123, response_length=0, response=None, context=None, exception=None)

也可以把 Locust 与 Prometheus 集成，把指标暴露出来，方便做长期趋势分析。

常见陷阱与调优建议

• 不要把复杂计算放在用户任务里：Locust 的目标是测目标系统，不是测你的负载脚本 CPU。
• 避免在用户间共享可变全局状态：会导致竞态与难以复现的行为。
• 小心请求的缓存与 CDN：静态资源被 CDN 缓存会让测试偏高估后端性能，按需禁用缓存或只测 API。
• 请求并行与连接复用：如果你需要并发请求，考虑在同一用户内异步或使用 gevent（Locust 默认使用 gevent）。

调试技巧：当测试表现不符合预期怎么办

• 先用少量用户运行，打开日志，确认请求路径、headers、认证都正确。
• 在目标系统开启详细日志（短时间）来定位报错原因。
• 在本地模拟网络条件（如 tc/netem）来观察耐受性。
• 把失败的请求信息（URL、状态码、响应体摘出来）做统计，找出高频问题。

结果保存与分析建议

把每次测试的配置（脚本版本、用户数、run-time、目标 URL）和输出保存，形成对比。一个简单的表格可以帮助记录回归趋势：

实战小结（边想边写的那种提示）

写到这里我会提醒自己：先用最简单的 locustfile 把流程跑通，再逐步加复杂度。别一开始就追求极高并发，先确认脚本行为与统计口径没问题，然后再逐渐放大规模。遇到异常时，先把请求与响应抓下来确认真实情况，再去猜测是代码层、数据库还是网络导致的瓶颈。

参考与扩展阅读

• Locust 官方文档（阅读最新版本的 API 说明非常重要）。
• 关于性能工程的书籍与 APM 文档，帮助把单次测试结果放到系统视角下分析。

好了，写到这儿，接下来你可以把上面的示例复制到项目里，按步骤跑一遍，遇到具体问题再微调脚本或扩展监控；测试本身是个循环迭代的过程，边测边改，能最早发现真实瓶颈。