📚 课程目录第4章录制模式配置

录制模式配置：全局录制与按需录制

录制模式的选择，说白了就是决定「录什么、什么时候录」。我刚接触 Mock 回放时，犯过一个低级错误——直接开了全局录制，结果跑了一整天 CI，硬盘满了，日志里全是无关 API 的请求。从此我学乖了：先搞清楚你的录制目标。

一句话总结：全局录制适合全链路回归，按需录制适合局部迭代。两种模式可以共存，但需要搭配过滤器才能优雅落地。

全局录制模式

全局录制就是拦截所有通过代理的 HTTP/HTTPS 流量，全部录下来。听起来简单粗暴，但实际坑不少。

优点：覆盖全面，不会漏掉任何请求；适合第一次搭建 Mock 录制的快速铺底。
缺点：会产生大量无意义数据（比如心跳、日志上报、静态资源），拖慢管道速度，占用存储。
适用场景：新项目 Mock 库初始化、全量回归测试。

我记得有个项目需要录制第三方支付接口的回放，直接开全局录制，结果录了 2000 多条请求，其中 1800 条是前端上报的异常日志。嗯，后来我加了个过滤器，才把数据量控制到 200 条以内。

配置示例（基于 HTTP Record Proxy 工具）：

# 全局录制配置
record:
  mode: global
  output: ./recordings/global/
  captureRequestHeaders:
    - Authorization
    - Cookie
  captureResponseHeaders:
    - Set-Cookie
    - Content-Type
  bodyLimit: 10MB

按需录制模式

按需录制，就是只录制你明确指定的接口或请求。我更喜欢用这种方式，因为精准。你想想看，迭代一个新功能，我只需要关注那两三个新增或修改的 API，其他老接口用已有的 Mock 数据就行。

实现方式通常有两种：

基于路径白名单：只录制匹配正则或精确路径的请求。
基于标签/注解：在请求头或查询参数中标记需要录制的请求。

路径白名单示例：

record:
  mode: on-demand
  include:
    - /api/v1/orders
    - /api/v2/users
  exclude:
    - /api/health-check
    - /api/error-log

我曾经踩过一个坑：只录了 POST /orders，忘了录后续的 GET /orders/{id} 查询接口。结果回放时，订单创建成功，但查询返回的是旧数据，导致测试断言失败。所以按需录制要把关联接口一起考虑进去。

录制过滤器设置

过滤器是录制模式的「安检仪」。没有它，全局录制会变成垃圾堆，按需录制也容易漏掉边界。我个人习惯把过滤器分为三个维度：

维度	常见配置	我的经验
请求路径	正则匹配、精确匹配	优先用正则，一次写对，多处复用
请求方法	GET/POST/PUT/DELETE	通常只录写操作（POST/PUT/DELETE），只读接口用 Mock 库已有数据
请求头/参数	包含特定 Header、Query 参数	过滤掉监控、热更新类请求，它们不是业务逻辑的一部分

为什么需要分维度？因为在复杂系统中，同一个路径可能既有业务请求又有内部调用。比如 /api/orders 既有客单查询又有后台同步，加一个自定义 Header 就能区分。

重点关注：过滤器不能太宽松，否则录不到关键请求；也不能太严格，否则遗漏边界情况。我建议先从「排除无用的」开始，再逐步收紧。

另一个容易忽略的点：敏感数据过滤。录制时如果录到密码或，回放时会被灌入测试环境，这是安全隐患。我的做法是在过滤器里加一个专门的敏感字段黑名单：

record:
  filters:
    excludeHeaders:
      - X-Auth-
      - Cookie
    excludeRequestBodyFields:
      - password
      - secret
    excludeResponseBodyFields:
      - creditCard

两种模式的切换与组合

实际项目中，我经常同时使用两种模式：用全局录制铺底一次，然后转为按需录制增量更新。切换时注意清理旧录制数据，避免混淆。

这里给一个通用的工作流：

首次搭建：开全局录制 + 基础过滤器，跑一遍核心 E2E 用例。
日常迭代：关掉全局，只打开按需录制，指定新增接口。
回归测试前：手动触发一次增量全局录制，补充被遗漏的场景。

我记得有一次，组里新人直接复用了全局录制的数据做回归，结果老接口 Mock 数据没更新，测试跑过了但实际生产出了问题。后来我们在管道脚本里加了一个校验：检查录制文件的最后修改时间，超过指定天数就报警。

埋点与验证：如何确保录制正确

配置只是第一步。我建议在管道里加两个自动化检查：

录制数量统计：对比本次录制请求数与期望值，偏差超过 20% 就报警。
内容一致性：随机抽几条录制的请求，回放一次，看看状态码和 body 结构是否完整。

为什么要有第二项？因为我遇到过过滤器写错了，把响应体给截断了——内容只有前 10 个字符。回放时接口返回正常，但期望字段全没了。这种 bug 在 CI 里隐藏得很深，不主动检查很难发现。

避坑指南：我曾经因为忘记排除 Health-Check 接口，导致录制文件里有一半是心跳请求。后期回放时，Mock 服务器每次要匹配几千个重复路径，性能严重下降。解决方案很简单：起手就把所有监控类的接口加到 exclude 列表里。

实用配置清单

我把日常项目里最常用的一组配置写在这里，你可以直接改成你的场景：

record:
  mode: hybrid # 全局+按需混合模式，默认全局，带白名单时按需
  global:
    outputDir: ./recordings/global
    maxFileSize: 100MB
    maxRequests: 5000
  on-demand:
    outputDir: ./recordings/delta
    includePolicies:
      - path: /api/v2/order.*
        method: POST|PUT
      - path: /api/v1/payment.*
        method: POST
  filters:
    exclude:
      - path: /health
      - path: /metrics
      - header: X-Debug-Group.*
    excludeBody:
      - creditCard
      - password
    compressResponses: true

注意最后的 compressResponses: true——这是个小技巧。响应体如果很大（比如大于 1MB），录制时自动 gzip 压缩，回放时再解压。我在项目中试过，存储空间能省 40% 左右。