策略概览

Softprobe 测试用声明式 YAML 策略（apiVersion: softprobe.ai/v1）控制行为，而非临时请求参数。策略按应用匹配、按 metadata.priority 合并，由 sp-backend 在运行时生效。

策略是可选的调优，不是前提

内置的全局默认策略（priority 0）让录制与回放开箱即用。只有当你要改变默认行为——控制采样、缩小操作范围、忽略噪声字段——才需要写自己的策略（priority > 0 覆盖）。先能跑通核心流程，再回来收紧。

操作流程与策略配置分开阅读：

阶段	操作文档	策略配置
1 · 录制	录制流量	本节 RecordingPolicy
2 · 回放	回放与对比	本节 MockPolicy、CompareRulePolicy

逐字段说明与完整 YAML 示例：策略 YAML 指南 · sp policy 命令

CLI 速查

sp policy recording validate -f recording.yaml --json
sp policy recording apply -f recording.yaml --json
sp policy mock apply -f mock.yaml --json
sp policy compare apply -f compare.yaml --json

冲突时 metadata.priority 更高者生效。内置 priority 0 全局默认；应用策略请设 priority > 0。

按生命周期分阶段

阶段	Kind	何时配置	CLI
1 · 录制	RecordingPolicy	产生流量之前	sp policy recording
2 · 回放	MockPolicy	执行 sp replay run 之前	sp policy mock
2 · 回放	CompareRulePolicy	执行 sp replay run 之前	sp policy compare

完整生命周期：快速开始

---

RecordingPolicy

用于录制阶段 · 产生流量之前应用

控制 Agent 录什么：采样、时间窗口、操作包含/排除、序列化跳过、录制时时间 Mock。

• 采样 — ratePerHundredSeconds（每 100 秒上限；0 = 不录）、machineCountLimit（并发录制实例上限，省略 = 不限）
• 时间窗口 — daysOfWeek、from / to（Agent JVM 本地时区）
• 操作过滤 — exclude（黑名单 Glob）；非空 include 时变为白名单模式
• 序列化跳过 — serializeSkip 按类名与字段名
• timeMock — 录制时固定 java.time.*

操作步骤： 录制流量

YAML 字段与示例： 策略 YAML 指南 · RecordingPolicy

说明

• spec.sensitiveData 在 Agent 录制路径尚未生效；Mock 键噪声用 matchTolerance，查看脱敏用 SensitivePolicy（见 YAML 指南相关配置）。
• 修改 operations 包含/排除会影响回放调度的操作范围，无需单独改调度文档。

sp policy recording validate -f my-recording.yaml --json

---

MockPolicy

用于回放阶段 · 执行 sp replay run 之前应用

控制回放时依赖是否 Mock、Mock 键容差、跨应用依赖与无匹配 Mock 时的回退。

• mockByDefault — 默认 Mock 全部依赖（skipMock 为例外），或反之以 forceMock 为例外
• Category:operationGlob — 如 HttpClient:/payment/**（不是 Servlet 等入口类型）
• matchTolerance — 忽略易变头、查询参数、body 路径
• multiServiceDependencies — 同会话内下游应用 Mock
• fallback — FAIL（默认）、PASS_THROUGH、RETURN_DEFAULT

内置全局策略 强制 Mock DynamicClass:SystemTime.** / RandomSource.**；用户 skipMock 无效。

YAML 字段与示例： 策略 YAML 指南 · MockPolicy

完整依赖分类列表

---

CompareRulePolicy

用于回放阶段 · 执行 sp replay run 之前应用

控制回放差异对比中的噪声（非 Mock 行为）。

• excludePaths / includePaths — JSON Pointer（支持 Glob）
• defaults.timeToleranceMs 与 CEL validations — 按规则丢弃差异（含按 category 忽略，如 DATABASE body）
• operationSpecs — 按入口操作覆盖（不要在 selector 上写操作名）

YAML 字段与示例： 策略 YAML 指南 · CompareRulePolicy

回放后用 sp replay diff 排查，再收紧策略而非改业务代码。

---

动态类（非 RecordingPolicy）

本地缓存等方法在动态类配置（控制台/API）登记，不在 RecordingPolicy 中。回放 Mock 通过 MockPolicy 的 UserDynamic / DynamicClass 规则控制。见 策略 YAML 指南 · 相关配置。

策略类型与服务端模块

Kind	CLI	服务端模块
RecordingPolicy	sp policy recording	RecordingPolicyService
MockPolicy	sp policy mock	MockPolicyService
CompareRulePolicy	sp policy compare	CompareRulesService

示例文件位于 sp-policy-rules/src/main/resources/examples/。

Agent 工作流

# apply 前务必先 validate
sp policy recording validate -f recording.yaml --json
sp policy recording apply -f recording.yaml --json

CI 应在 valid: false 或非零退出码时失败。

GitOps

sp policy recording export prod-policy-id -o policies/recording-prod.yaml
git commit -m "chore: sync recording policy"

见 GitOps 策略。

与旧版配置的关系

policy-rules 迁移后，sp config legacy schedule 与 Mongo 的 ServiceCollectConfiguration 不再是配置的唯一来源。用 sp policy recording 管理同时影响 agent 与回放范围的 operation include/exclude。

相关文档

• 录制流量
• 回放与对比
• 策略 YAML 指南
• CLI：policy 命令