Netflix/pollyjs 配置详解：打造智能HTTP请求录制与回放系统

Netflix/pollyjs 配置详解：打造智能HTTP请求录制与回放系统

一、Pollyjs 配置基础

Netflix/pollyjs 是一个强大的 JavaScript 库，用于记录、重放和模拟 HTTP 交互。通过灵活的配置选项，开发者可以精确控制请求录制与回放的各个环节。

1.1 配置方式

Pollyjs 提供两种主要配置方式：

// 方式一：构造函数配置
const polly = new Polly('测试记录', {
  recordIfMissing: false,
  logLevel: 'info'
});

// 方式二：实例方法配置
polly.configure({
  mode: 'record',
  adapters: ['xhr']
});

二、核心配置参数解析

2.1 日志级别控制

logLevel 参数控制日志输出级别，对于调试非常有用：

• silent: 完全静默
• error: 仅错误
• warn: 警告及以上（默认）
• info: 常规信息
• debug: 调试信息
• trace: 最详细日志

polly.configure({
  logLevel: 'debug'  // 适合开发环境调试
});

2.2 录制行为控制

recordIfMissing 和 recordFailedRequests 共同控制录制行为：

polly.configure({
  recordIfMissing: true,    // 当没有录制时自动录制
  recordFailedRequests: true // 录制失败请求(HTTP 400+)
});

2.3 过期策略管理

expiresIn 和 expiryStrategy 管理录制内容的生命周期：

polly.configure({
  expiresIn: '30d', // 30天后过期
  expiryStrategy: 'warn' // 过期时警告而非报错
});

时间格式支持多种写法：

• 30d5h10m → 30天5小时10分钟
• 5 min 10 seconds → 5分10秒

三、工作模式详解

mode 参数决定 Pollyjs 的核心行为：

polly.configure({
  mode: 'replay' // 默认值，优先回放录制
});

polly.configure({
  mode: 'record' // 强制重新录制
});

polly.configure({
  mode: 'passthrough' // 直接透传请求
});

四、适配器与持久化配置

4.1 适配器配置

适配器负责拦截实际HTTP请求：

import XHRAdapter from '@pollyjs/adapter-xhr';

polly.configure({
  adapters: [XHRAdapter], // 使用XHR适配器
  adapterOptions: {
    xhr: { context: window } // 适配器特定配置
  }
});

4.2 持久化配置

持久化配置决定录制内容如何存储：

import LocalStoragePersister from '@pollyjs/persister-local-storage';

polly.configure({
  persister: LocalStoragePersister,
  persisterOptions: {
    keepUnusedRequests: true, // 保留未使用的请求
    disableSortingHarEntries: false // 保持HAR规范排序
  }
});

五、高级请求匹配配置

matchRequestsBy 是Pollyjs最强大的功能之一，它定义了如何识别"相同"的请求：

5.1 基础匹配配置

polly.configure({
  matchRequestsBy: {
    method: true,  // 匹配HTTP方法
    headers: {     // 精细控制头匹配
      exclude: ['Authorization']
    },
    body: false   // 忽略请求体差异
  }
});

5.2 URL匹配策略

URL匹配可以精确到各个组成部分：

polly.configure({
  matchRequestsBy: {
    url: {
      protocol: false,  // 忽略http/https差异
      hostname(host) {  // 自定义域名处理
        return host.replace('staging.', '');
      },
      query: {          // 处理查询参数
        exclude: ['timestamp']
      }
    }
  }
});

六、性能与调试技巧

6.1 请求延迟模拟

import { Timing } from '@pollyjs/core';

polly.configure({
  timing: Timing.relative(2.0) // 2倍速回放
});

polly.configure({
  timing: Timing.fixed(500) // 固定500ms延迟
});

6.2 请求生命周期管理

polly.configure({
  flushRequestsOnStop: true // 停止时等待未完成请求
});

七、最佳实践建议

1. 开发环境：使用 mode: 'record' 建立初始录制
2. CI环境：使用 mode: 'replay' 确保一致性
3. 敏感数据处理：通过 matchRequestsBy 过滤认证信息
4. 长期维护：设置合理的 expiresIn 提醒更新录制

通过合理配置这些参数，Pollyjs可以成为前端开发、测试和调试过程中不可或缺的工具，特别是在微服务架构和前后端分离的项目中，它能显著提高开发效率和测试可靠性。