e2e执行引擎设计：Engine Contract与Session模型

e2e 引擎这东西第一次做的人十有八九会栽在同一个地方上来就写执行逻辑写了两千行之后发现驱动层换不掉、会话收不干净、并发一开就串数据。我在几个不同规模的团队里都参与过这类执行引擎的搭建和重构最后复盘下来真正决定成败的不是执行器写得多花哨而是最开始那份Engine Contract定得够不够准以及Session这一层有没有被当成正经的架构单元来对待。这篇就按我实际做过的顺序展开先讲契约怎么定、为什么这么定再讲会话模型怎么设计然后给出一套可以照着敲的骨架代码最后把能力协商、超时重试、可观测性和排查经验一次说透。适合正在做或准备做自动化执行引擎的开发者也适合已经有一版能用但总觉得哪里不对劲的人对照着看。1. 先把 Engine Contract 这件事想明白1.1 为什么必须先定契约而不是先写实现很多人对契约的理解停留在定义一个 interface这其实只对了一半。契约的本质是多方并行开发的边界协议写执行器的人、写驱动适配的人、写报告聚合的人、写调度平台的人四拨人如果不在同一个接口上达成一致后面每接一个模块都要改一次核心代码。我见过最典型的反例是引擎入口直接暴露了底层的页面句柄上层为了拿个截图直接穿透三层去调底层方法结果驱动一换二十几个调用点全部报废。先定契约还有一个很现实的好处它可以被 mock。契约稳定之后上层业务逻辑可以在引擎完全没实现的情况下先跑通用假实现返回固定的 StepResult联调时间能压缩一大半。这一点在多人协作里价值极高因为大家不必互相等。我个人的经验判断是契约设计投入的时间占整个项目 10% 左右是合理的低于 5% 基本都会返工。返工的成本不是改接口那几行代码而是所有已经写好的调用方。1.2 Engine Contract 的最小完备集合不要贪多。一个 e2e 执行引擎的对外契约真正必需的就那么几组能力。我通常按下面的表格来盘点多出来的都要问一句不加会死吗。能力分组方法/属性是否必需说明元信息name、version必需用于日志归属与兼容性判断能力声明capabilities()必需返回支持的步骤类型、平台、限制会话创建createSession(options)必需唯一的生产会话入口引擎销毁dispose()必需释放全局资源需幂等健康检查health()建议长驻进程场景必备事件订阅on(event, handler)建议可观测性的接入点会话枚举listSessions()可选仅调试与运维场景需要这里有个取舍值得单独说不要把 execute 放在 Engine 上。初学者常写成engine.execute(step)图省事但这就等于引擎内部藏了一个隐式全局会话所有调用共享同一份上下文并发一来直接串味。执行一定是 Session 的职责引擎只负责造会话和收会话。契约里还有一个隐式约定要写进文档哪些方法是幂等的。dispose()必须幂等重复调用不能抛错createSession()不幂等每次调用都必须产出独立会话close()必须幂等。这三条不写清楚上层就没法安全地做重试。1.3 契约的版本演进策略契约一旦对外就不能随便改。我的做法是给契约打语义化版本并且在能力声明里带上contractVersion字段。演进遵循三条线加方法小版本号递增老实现可以返回NOT_SUPPORTED上层通过能力探测决定是否调用。改签名大版本号递增同时在引擎侧提供一个适配层把老签名转成新签名给调用方一个过渡期。删方法只在超大版本做而且提前至少两个迭代周期在能力声明里标记deprecated。注意能力探测一定要走capabilities()的一次性快照不要在每次执行时临时判断。运行期反复探测会让代码里到处是 if最后没人敢动。2. Session 模型引擎里最容易被低估的一层2.1 Session 到底承载了什么在很多人脑子里Session 就是个 id 加一个底层句柄。实际做下来一个正经的会话至少要背负五件事上下文容器cookie、本地存储、缓存、认证态这些东西的生命周期必须严格绑定在会话上不能漏到进程级。隔离单元会话之间不能有任何共享可变状态哪怕是一个全局计数器都要谨慎。资源账本这个会话开了几个句柄、占了多少内存、跑了多久出问题时这些数字是第一手证据。状态机载体会话有明确的生命周期状态非法转换必须被拦住。追踪锚点所有日志、指标、快照都挂同一个 traceId事后能拼出一条完整时间线。我踩过最疼的一次坑就是把认证态存在了引擎实例上单会话测试全绿一开四并发四个会话互相顶掉登录态报错信息还特别有迷惑性说是元素找不到。查了两天才定位到是作用域写错了。2.2 会话状态机怎么设计状态机不要设计得太花。我的经验是六个状态足够覆盖 95% 的场景状态含义允许的下一步created对象已构造尚未初始化initializing、closedinitializing正在建立底层连接ready、failedready空闲可接受执行busy、closing、failedbusy正在执行步骤ready、failed、closingclosing正在回收资源closed、failedclosed终态无关键点在于终态不可回退以及busy 状态下拒绝新的 execute。后者很多人不做结果是两个调用同时进来步骤交错执行日志时间线完全错乱。最简单的做法是在 execute 入口做一次 CAS 式的状态切换切不成功就直接返回一个明确的SESSION_BUSY错误而不是排队等待——排队会把超时逻辑搞得极其复杂。type SessionState | created | initializing | ready | busy | closing | closed | failed; const LEGAL_TRANSITIONS: RecordSessionState, SessionState[] { created: [initializing, closed, failed], initializing: [ready, failed], ready: [busy, closing, failed], busy: [ready, closing, failed], closing: [closed, failed], closed: [], failed: [closing, closed], };2.3 隔离级别怎么选隔离级别直接决定了并发能力也直接决定了排查难度。我一般给团队三个档位按测试用例的性质来选。隔离级别实现方式单会话内存开销经验值启动耗时适用场景进程级独立进程300MB ~ 600MB1.5s ~ 4s强隔离、易崩的用例上下文级独立浏览器上下文80MB ~ 200MB200ms ~ 800ms大多数常规 e2e页面级共享上下文、独立标签30MB ~ 80MB50ms ~ 200ms无状态页面快速校验上面这些数字是常见实践下的量级参考具体值跟你跑的页面复杂度关系极大别当真理用自己测一轮更靠谱。选型的核心逻辑是上下文污染的风险 × 用例数量对比启动开销 × 用例数量。如果用例之间会写同一个账号的数据那就别省这个钱上上下文级隔离。提示无论选哪一档会话关闭时都要显式清理不能依赖进程退出。我见过依赖自动回收的引擎跑八小时之后内存从 2G 涨到 14G。3. 实操从零搭一个可跑的 Engine 骨架3.1 目录结构与依赖取舍结构上我倾向按契约 / 实现 / 适配三层切别按功能切。这样契约层的改动影响面一眼可见。engine/ contract/ engine.ts # EngineContract 与 Session 接口 types.ts # StepResult、SessionOptions、错误码 events.ts # 事件类型定义 core/ engine-impl.ts # 引擎实现 session-impl.ts # 会话实现 state.ts # 状态机与守卫 errors.ts # 错误分类 adapters/ registry.ts # 适配器注册表 base.ts # 适配器抽象 infra/ clock.ts # 可注入时钟方便测试超时 logger.ts metrics.ts依赖上我只坚持两条一是必须能注入时钟否则超时逻辑没法写单测二是必须能注入日志器引擎内部不要直接调 console。其他依赖能少则少引擎这种基础设施层每多一个第三方包就多一个版本冲突源。TypeScript 配置里我建议把strict全开尤其strictNullChecks和noImplicitAny。引擎里空值处理写错一个地方就是线上随机崩。3.2 契约层的类型定义先写类型再写实现这个顺序不要反。下面是我常用的版本去掉了一些业务相关的字段保留骨架。export type ErrorClass transient | fatal | assertion | timeout; export interface EngineError { code: string; message: string; class: ErrorClass; retryable: boolean; cause?: unknown; } export interface StepResult { stepId: string; ok: boolean; durationMs: number; error?: EngineError; artifacts?: string[]; } export interface SessionOptions { traceId: string; isolation?: process | context | page; deadlineMs?: number; tags?: Recordstring, string; } export interface CapabilitySet { contractVersion: string; isolationLevels: string[]; stepTypes: string[]; maxConcurrentSessions: number; supportsSnapshot: boolean; } export interface SessionSnapshot { sessionId: string; state: string; uptimeMs: number; stepsExecuted: number; lastError?: EngineError; resources: Recordstring, number; } export interface ActionStep { id: string; type: string; params: Recordstring, unknown; timeoutMs?: number; } export interface Session { readonly id: string; readonly traceId: string; readonly state: string; execute(step: ActionStep): PromiseStepResult; snapshot(): PromiseSessionSnapshot; close(reason?: string): Promisevoid; } export interface EngineContract { readonly name: string; readonly version: string; capabilities(): CapabilitySet; createSession(options: SessionOptions): PromiseSession; listSessions(): string[]; health(): { ok: boolean; detail?: string }; dispose(): Promisevoid; }注意StepResult里我用了ok而不是抛异常。这个选择有争议但执行引擎里我倾向于把失败当成正常返回值因为失败是高频事件用异常表达会导致调用方到处写 try/catch而且异常在并发场景下容易吞掉上下文。只有引擎自身不可用这类真异常才 throw。3.3 Session 实现的完整骨架这部分是重头戏。核心是三点状态守卫、截止时间传递、资源记账。export class SessionImpl implements Session { private _state: SessionState created; private stepsExecuted 0; private readonly startedAt: number; private readonly deadlineAt: number | null; private lastError?: EngineError; private adapter?: BaseAdapter; constructor( readonly id: string, readonly traceId: string, private readonly opts: SessionOptions, private readonly clock: Clock, private readonly log: Logger, ) { this.startedAt clock.now(); this.deadlineAt opts.deadlineMs ? this.startedAt opts.deadlineMs : null; } get state(): SessionState { return this._state; } private transition(to: SessionState): void { const legal LEGAL_TRANSITIONS[this._state]; if (!legal.includes(to)) { throw new Error(illegal transition ${this._state} - ${to}); } this._state to; } async init(): Promisevoid { this.transition(initializing); try { this.adapter await createAdapter(this.opts.isolation ?? context); this.adapter.onCrash((err) { this.lastError mapError(err); this._state failed; }); this.transition(ready); } catch (e) { this.lastError mapError(e); this.transition(failed); throw e; } } async execute(step: ActionStep): PromiseStepResult { if (this._state ! ready) { return { stepId: step.id, ok: false, durationMs: 0, error: { code: SESSION_NOT_READY, message: session state is ${this._state}, class: fatal, retryable: false, }, }; } const budget this.remainingBudget(step.timeoutMs); if (budget 0) { return { stepId: step.id, ok: false, durationMs: 0, error: { code: DEADLINE_EXCEEDED, message: session deadline already exceeded, class: timeout, retryable: false, }, }; } this.transition(busy); const t0 this.clock.now(); try { const result await withTimeout( this.adapter!.run(step), budget, step.id, ); this.stepsExecuted; return { stepId: step.id, ok: true, durationMs: this.clock.now() - t0, artifacts: result.artifacts }; } catch (e) { const err mapError(e); this.lastError err; return { stepId: step.id, ok: false, durationMs: this.clock.now() - t0, error: err }; } finally { if (this._state busy) this.transition(ready); } } private remainingBudget(stepTimeout?: number): number { const sessionLeft this.deadlineAt ? this.deadlineAt - this.clock.now() : Number.POSITIVE_INFINITY; const stepLeft stepTimeout ?? Number.POSITIVE_INFINITY; return Math.min(sessionLeft, stepLeft); } async close(reason normal): Promisevoid { if (this._state closed || this._state closing) return; this.transition(closing); try { await this.adapter?.dispose(reason); this.transition(closed); } catch (e) { this.lastError mapError(e); this._state closed; // 关闭失败也要进终态避免泄漏 this.log.warn(session close failed, { id: this.id, reason }); } finally { registry.release(this.id); } } }几个细节值得单独点出来。第一execute里busy的恢复放在finally但加了状态判断——如果执行过程中适配器崩了把状态推到failed这里不能硬拉回ready。第二close里关闭失败也强制进终态宁可标记成异常关闭也不能让会话挂在closing上占着资源。第三所有时间都走注入的 clock测试超时逻辑时可以直接推进虚拟时间不用真等。3.4 引擎入口与生命周期管理引擎实现本身很薄主要是会话注册表、并发闸门和销毁顺序。export class EngineImpl implements EngineContract { readonly name e2e-engine; readonly version 1.4.0; private sessions new Mapstring, SessionImpl(); private disposed false; constructor( private readonly cfg: EngineConfig, private readonly clock: Clock, private readonly log: Logger, ) {} capabilities(): CapabilitySet { return { contractVersion: 1.4, isolationLevels: [process, context, page], stepTypes: this.cfg.enabledStepTypes, maxConcurrentSessions: this.cfg.maxConcurrent, supportsSnapshot: true, }; } async createSession(opts: SessionOptions): PromiseSession { if (this.disposed) throw new Error(engine disposed); const active [...this.sessions.values()] .filter(s s.state ! closed s.state ! failed).length; if (active this.cfg.maxConcurrent) { throw new Error(session limit reached: ${active}); } const id s-${this.clock.now().toString(36)}-${rand(6)}; const s new SessionImpl(id, opts.traceId, opts, this.clock, this.log); this.sessions.set(id, s); await s.init(); return s; } async dispose(): Promisevoid { if (this.disposed) return; this.disposed true; const all [...this.sessions.values()]; await Promise.allSettled(all.map(s s.close(engine-dispose))); this.sessions.clear(); registry.reset(); } health() { const open [...this.sessions.values()] .filter(s s.state ! closed).length; return { ok: !this.disposed, detail: open sessions: ${open} }; } }dispose用allSettled而不是all这点很关键一个会话关闭失败不能阻断其他会话回收。销毁一个引擎最怕的就是卡在半路进程退不掉。4. 能力协商与驱动适配4.1 为什么要把能力声明做成一次性快照能力协商的意义在于把运行期的判断前移。上层调度系统在派发任务之前调一次capabilities()拿到引擎支持的步骤类型和隔离级别不支持的用例直接路由到别的引擎或者标记跳过。这比跑起来发现不支持再抛错优雅太多也省机器。实现上要注意两件事。一是这个返回值要做成不可变快照深拷贝或者冻结避免上层不小心改了它导致后续判断失真。二是它要包含限额信息比如maxConcurrentSessions调度器靠这个决定往这个引擎实例上派多少任务比硬编码一个数字靠谱得多。注意能力声明里不要写理论上支持的东西。写了supportsSnapshot: true就必须真能返回快照否则排查问题时上层会一直等到超时。4.2 适配器注册表怎么写适配器是引擎与具体执行环境之间的桥。注册表的设计目标只有一个引擎核心不认识任何具体驱动。interface AdapterFactory { name: string; supports(isolation: string): boolean; create(opts: SessionOptions): PromiseBaseAdapter; } class Registry { private factories new Mapstring, AdapterFactory(); register(f: AdapterFactory) { if (this.factories.has(f.name)) { throw new Error(adapter already registered: ${f.name}); } this.factories.set(f.name, f); } async createFor(isolation: string, opts: SessionOptions) { for (const f of this.factories.values()) { if (f.supports(isolation)) return f.create(opts); } throw new Error(no adapter for isolation${isolation}); } reset() { this.factories.clear(); } }register里做重名检查是必要的热加载场景下重复注册会导致工厂链越滚越长。createFor的遍历顺序就是优先级注册时先注册的更优先这个语义要写在文档里。4.3 并发度到底怎么算这是最容易被拍脑袋决定的参数。我一般用三条约束取最小值并发上限 min( 物理核数 × 单核超配系数, // CPU 约束 可用内存 × 0.75 ÷ 单会话峰值内存, // 内存约束 授权席位 / 外部服务限流阈值 // 外部约束 )举个具体例子一台 16 核、64GB 的机器单会话峰值内存实测 350MB外部服务限流 20 QPS每个会话平均 0.8 QPS。那么CPU 约束16 × 1.5 24内存约束64 × 0.75 ÷ 0.35 ≈ 137外部约束20 ÷ 0.8 25三者取最小是 24但还要再乘一个 0.7 的安全系数最终落在 16 左右。安全系数不是迷信是给突发留余量——真跑满 24 的时候任何一个用例内存翻倍就会触发 OOM。提示单会话峰值内存不要用平均值。取 95 分位数因为 OOM 是被最胖的那个会话触发的不是被平均的那个。5. 错误处理、超时与重试5.1 错误分类是所有容错逻辑的地基引擎里的错误不分级重试策略就无从谈起。我用的分类只有四档够用错误类别典型场景是否重试处理方式transient网络抖动、元素暂时未就绪是指数退避最多 2 次timeout步骤超时、会话超时视情况会话超时不重试步骤超时可 1 次assertion断言失败否直接判定用例失败并留证fatal适配器崩溃、会话非法状态否关闭会话重建后再跑分类的关键是每个类别要有明确的判据不能靠字符串匹配错误消息。我的做法是让适配器在抛错时带上结构化的code引擎按 code 的前缀映射到类别比如NET_*归 transientASSERT_*归 assertion。字符串匹配的错误分类在半年后一定会失效因为错误消息会被改。5.2 超时预算要分层不能只有一个数一套能用的超时体系至少三层全局任务超时 → 会话超时 → 单步超时。三者的关系必须是包含关系而且下层只能用上层的剩余预算。我见过最糟糕的实现是三层各配各的超时互相不知道对方。结果是单步配了 30 秒会话配了 20 秒跑到第 19 秒时单步还在等会话被杀日志里只留一个语焉不详的会话已关闭。用剩余预算的方式传递就不会出现这种自相矛盾。function remainingBudget( deadlineAt: number | null, now: number, stepTimeout?: number, ): number { const sessionLeft deadlineAt ? deadlineAt - now : Infinity; const stepLeft stepTimeout ?? Infinity; return Math.min(sessionLeft, stepLeft); }超时的实现要走AbortController或等价的取消机制不能只是超时了就返回。否则底层操作还在跑资源还在占下一轮并发直接爆。取消信号必须一路传到适配器最里层。5.3 重试的边界在哪重试不是免费午餐。三个约束必须同时成立才能重试幂等性成立这一步重复执行的副作用可接受。填表单重试一次可能就是两条数据。重试预算充足重试占用的时间要从会话预算里扣。预算不够时重试等于加速失败。错误类别允许只有 transient 和部分 timeout 应该重试。退避策略我用抖动指数退避第 n 次重试等min(base × 2^n, cap) × random(0.5, 1.0)。加抖动是为了避免一批会话同时失败后同时重试把下游打穿。这个场景在并发 16 以上时几乎必然发生别省这一行。6. 可观测性让问题自己冒出来6.1 事件总线怎么接引擎内部所有关键节点都发事件外部订阅与否是外部的事。事件列表我一般固定这几个session.created、session.ready、step.started、step.finished、session.failed、session.closed、engine.disposed。每个事件强制带traceId和sessionId。没有这两个字段的事件等于没有。日志器那边用 traceId 做上下文注入一次会话的所有日志能一键捞出来排查效率差十倍不止。一个容易忽略的点是事件监听器要及时解绑。会话关闭时如果不断开监听长驻进程跑一天之后 EventEmitter 上挂了几万个 handler内存泄漏加性能雪崩而且极难定位。6.2 快照要留什么snapshot()的返回内容要能回答三个问题这个会话现在在干什么、它跑了多久、它占了多少资源。我通常塞这些字段状态、已执行步数、运行时长、最后一次错误、以及资源计数打开的句柄数、缓存条目数等。快照的触发时机有两个主动查询排查时用和自动落盘会话异常关闭时。后者更有价值因为很多问题在会话关闭后就再也复现不了了。落盘也不用搞得很复杂一个 JSON 文件加时间戳就够重要的是在失败那一刻自动写而不是等运维来捞。提示快照落盘要注意脱敏。会话上下文里可能有登录凭证直接序列化到磁盘是隐患序列化前过一遍白名单。7. 常见问题与排查速查表7.1 高频问题速查现象大概率原因排查方向修复方式并发下用例互相串数据上下文没有按会话隔离检查是否有模块级可变状态移到会话实例内会话关闭后进程不退出有未释放的定时器或句柄关闭时打印活动句柄显式清理并置空内存随时间线性上涨事件监听器或缓存未清理对比快照的资源计数关闭时解绑并清空超时后仍有网络请求取消信号没传到最里层在适配器最底层打日志全链路传递取消信号状态机报非法转换并发重入或崩溃回调抢跑记录状态变更序列加状态守卫收敛回调重试引发流量尖峰无抖动或抖动范围太小看重试时间分布加大抖动窗口7.2 我踩过的几个坑第一个坑把 close 写成只做一半。早期的实现里close先释放适配器再更新状态。结果释放过程中抛了异常状态永远停在closing会话既不能被复用也不能被回收跑两小时注册表里堆了几百个僵尸。后来改成无论释放成功与否最终一定进终态同时打警告日志问题才断根。第二个坑以为并发就是多开几个实例。第一版直接按任务数开进程机器上 32 个实例同时启动启动瞬间 CPU 打满所有实例互相拖慢整体耗时比串行还长。后来加了并发闸门和启动排队前 8 个立刻起后面的按 200ms 间隔错峰稳定性和总耗时都好了很多。第三个坑用错误消息做分类。有次上游改了一句错误文案从连接超时改成连接已超时重试逻辑瞬间全部失效所有网络抖动都变成了致命错误成功率掉了 15 个点。改成结构化错误码之后再没出现过这类问题。第四个坑忽略了时钟。前几版直接用Date.now()超时逻辑完全没法写单测只能真等 30 秒。后来把 clock 抽成依赖测试里推进虚拟时间超时用例从跑一次半分钟变成跑一次几毫秒覆盖率也跟着上去了。8. 这套骨架后续怎么长骨架跑通之后一般会往两个方向长。往调度侧长加上任务队列、优先级、失败重投、按标签路由往能力侧长加上视频录制、网络拦截、性能指标采集。这两个方向都要守住一条新增能力必须通过契约暴露而不是在实现类里加个 public 方法让上层直接调。契约一旦被绕过前面所有的设计投入就白费了。还有个我个人的偏好把契约层单独发一个包版本号独立管理引擎实现依赖契约上层业务也依赖契约。这样契约的每次变更都有明确的版本记录谁在什么时候因为什么改了契约一查就知道。多包管理会带来一点工程复杂度但比起契约悄悄变形带来的维护成本这点复杂度非常划算。真要说这套东西里最值得花时间的部分还是最开始那两个小时——把 Engine Contract 的每个方法、每个返回值、每条幂等性约定写清楚把 Session 的状态机画在一张纸上。这两件事做扎实了后面的代码写起来其实很快而且改起来不慌。