1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
use crate::{error::ScenarioError, invariant::InvariantViolation, runner::TaskIndex};
/// `setup()` 阶段的执行粒度。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SetupMode {
/// 每个并发任务执行一次(默认);产出在任务内所有轮次间复用。
/// 适合登录拿 token、预热客户端等会话级准备。
Task,
/// 每轮 `run` 之前执行一次;产出仅本轮有效。
/// 适合验证码、唯一账号等一次性消耗数据。
Round,
}
/// `teardown()` 阶段的执行粒度,与 [`SetupMode`] 同义:
/// `Task` = 每个任务在轮次循环结束后一次,`Round` = 每轮一次。
pub type TeardownMode = SetupMode;
/// 框架按 `block_on` + `join_all` 调度(默认单线程协作;
/// 可用 `ManagerConfig::with_workers` 分片到多个自建线程),不 `tokio::spawn`,
/// 因此不要求方法返回的 Future `Send`;若未来需要 spawn,
/// 应改为返回 `impl Future + Send` 的手写形态。
#[allow(async_fn_in_trait)]
pub trait Scenario: Default + Send + Sync + 'static {
type Ctx: Send + Sync;
type Error: ScenarioError;
/// `run` 的成功产出(如 `reqwest::Response`),每轮 run 的局部值,
/// 仅供本轮 `validate` 借用来做业务校验。
/// 不需要产出数据时填 `()` 即可(此时 `run` 签名与旧版 `Result<(), Error>` 等价)。
type Output;
/// `setup` 产出的数据(如登录会话/预热客户端/本轮业务参数),
/// 供 `run`/`validate` 借用。不需要时填 `()` 并在 `setup` 中返回 `Ok(())`。
type Setup: Send + Sync;
/// `setup` 执行粒度,默认每个任务一次(`SetupMode::Task`)。
const SETUP_MODE: SetupMode = SetupMode::Task;
/// `teardown` 执行粒度,默认每个任务一次(`TeardownMode::Task`)。
///
/// - `Task`:每个任务在轮次循环结束后执行一次(含被优雅关闭提前结束的路径);
/// - `Round`:每轮 `run`/`validate` 之后执行一次,能拿到本轮 `setup` 与 `run` 产出。
///
/// 需要清理**每轮创建的资源**(如每轮下单后删除订单)时应设为 `Round`:
/// 任务级收尾拿不到任何一轮的 `Output`。
const TEARDOWN_MODE: TeardownMode = TeardownMode::Task;
/// 场景展示名。
///
/// 默认返回完整类型路径(如 `my_mod::HelloScenario`)。
/// 注意:注册进 registry 的**匹配名**由 `register_scenario!` 生成,
/// 默认是类型简单名(可用 `name = "..."` 覆盖),两者相互独立。
fn name() -> &'static str {
std::any::type_name::<Self>()
}
/// 预置阶段,按 [`Self::SETUP_MODE`] 决定执行频率:
///
/// - `SetupMode::Task`:每个并发任务在 run 循环开始前执行**一次**,
/// 产出注入该任务所有轮次的 `run`/`validate`;
/// - `SetupMode::Round`:每轮 `run` 之前执行**一次**,
/// 产出仅本轮有效。
///
/// `task` 与 `run` 收到的为同一任务身份,可用 `task.index`
/// 做账号等参数化预置(如 `login(format!("loadtest_{}", index))`)。
/// 返回 `Err` 时该任务直接中止:记一次失败,不再继续。
/// 本方法为**必填**:`Setup` 不再要求 `Default`,框架不再提供默认实现;
/// 无预置数据时填 `type Setup = ()` 并返回 `Ok(())` 即可。
async fn setup(ctx: &Self::Ctx, task: &TaskIndex) -> Result<Self::Setup, Self::Error>;
/// 执行一次场景业务,返回本轮产出供 `validate` 校验。
/// `setup` 为该任务/该轮预置阶段的产出,可借用。
/// `task` 是框架分配的并发任务身份(编号/总数),可用 `task.index`
/// 做账号等参数化(如 `format!("loadtest_{}", task.index + 1)`)。
/// 返回 `Err` 时该轮直接记为失败,runner 不会调用 `validate`。
async fn run(
ctx: &Self::Ctx,
task: &TaskIndex,
setup: &Self::Setup,
) -> Result<Self::Output, Self::Error>;
/// 对 run 的成功产出做业务校验,默认直接通过。
/// `setup` 与 `task` 与 `run` 收到的为同一任务身份/预置产出。
/// 返回 `Err` 同样记为一次 validate 失败。
async fn validate(
_ctx: &Self::Ctx,
_task: &TaskIndex,
_setup: &Self::Setup,
_output: &Self::Output,
) -> Result<bool, Self::Error> {
Ok(true)
}
/// 收尾阶段(finally 语义),默认什么都不做。
///
/// 按 [`Self::TEARDOWN_MODE`] 决定执行频率;`run`/`validate` **无论成败**都会
/// 执行(不同于只在 `run` 成功时执行的 `validate`),且不可被停止信号打断。
///
/// `result` 为对应轮次 `run` 的结果:`Round` 粒度恒为 `Some(Ok/Err)`;
/// `Task` 粒度没有单轮产出,恒为 `None`。
///
/// 失败处理:返回 `Err` 记一次 teardown 失败(以 `teardown:{kind}` 进错误明细),
/// **不**加剧 `failures`/`timeouts`、不触发退避、不影响通过率,也不中止任务
/// (收尾失败不应中断压测)。
///
/// 边界:`setup` 未成功(普通失败 / 首轮前被取消)时不执行任务级收尾;
/// `SetupMode::Round` 且本轮 setup 失败时不执行本轮收尾。
/// 另注:`SetupMode::Round` 搭配 `TeardownMode::Task` 时,任务级收尾拿到的是
/// **最后一次成功 setup** 的产出(若从未成功 setup 过则不执行收尾)。
async fn teardown(
_ctx: &Self::Ctx,
_task: &TaskIndex,
_setup: &Self::Setup,
_result: Option<Result<&Self::Output, &Self::Error>>,
) -> Result<(), Self::Error> {
Ok(())
}
/// 全局对账阶段,默认不检查。
///
/// 在所有并发任务结束(含中断后的收尾)之后执行**一次**,用于校验
/// 单轮 `validate` 覆盖不到的聚合不变量,例如:
/// - `visual.like_count == count(visual_like)`;
/// - 同一 `(user_id, visual_id)` 无重复行;
/// - 静默后计数归零、缓存与数据库一致。
///
/// 语义:
/// - 返回空 `Vec` 表示通过;
/// - 每个 [`InvariantViolation`] 进入 [`crate::ScenarioReport::invariant_failures`],
/// 不影响 `times` / `failures` / `timeouts` / `validate_failures`,由调用方单独判定;
/// - 返回 `Err` 会折叠为一条 `reconcile:{kind}` violation,不会静默跳过检查;
/// - 不计入 RPS 的 `elapsed`,耗时单列在 `reconcile_total`;
/// - 因优雅关闭而**未启动**的场景不会执行;已启动的场景即使被中断也会执行。
async fn reconcile(_ctx: &Self::Ctx) -> Result<Vec<InvariantViolation>, Self::Error> {
Ok(Vec::new())
}
}