feat: HTTP 探针增强 — ignoreSSL、精确重定向控制、状态码范围匹配、编码自动检测

2026-05-13 00:02:04 +08:00
parent 87d946a441
commit 2fd0f206be
16 changed files with 642 additions and 22 deletions
--- a/openspec/specs/checker-runner-abstraction/spec.md
+++ b/openspec/specs/checker-runner-abstraction/spec.md
@@ -60,6 +60,14 @@
 - **WHEN** YAML 配置中 HTTP target 缺少 `http.url`
 - **THEN** HttpChecker 的 `resolve()` SHALL 抛出校验错误，提示缺少必填字段

+#### Scenario: HTTP method 非法校验
+- **WHEN** YAML 配置中 HTTP target 的 `http.method` 不在合法方法列表中
+- **THEN** HttpChecker 的 `resolve()` SHALL 抛出校验错误，提示 method 不合法
+
+#### Scenario: URL 格式校验
+- **WHEN** YAML 配置中 HTTP target 的 `http.url` 不以 `http://` 或 `https://` 开头
+- **THEN** HttpChecker 的 `resolve()` SHALL 抛出校验错误，提示 URL 格式不合法
+
 ### Requirement: 存储序列化通过 registry 获取展示格式
 系统 SHALL 在 `ProbeStore.syncTargets()` 中通过 `checkerRegistry.get(t.type).serialize(t)` 获取每个 target 的展示摘要（`target` 列）和配置 JSON（`config` 列），替代 `buildTargetDisplay()` / `buildTargetConfig()` 中的类型分支。

--- a/openspec/specs/expect-body-checkers/spec.md
+++ b/openspec/specs/expect-body-checkers/spec.md
@@ -126,3 +126,30 @@
 #### Scenario: actual 值截断
 - **WHEN** 失败规则的实际值超过系统允许记录的摘要长度
 - **THEN** 系统 MUST 截断 actual 摘要，而不是持久化完整响应体或命令输出
+
+### Requirement: 状态码范围匹配
+系统 SHALL 支持在 `expect.status` 数组中使用范围模式字符串（如 `"2xx"`、`"3xx"`、`"4xx"`、`"5xx"`），与精确数字混合使用。范围模式 SHALL 匹配对应百位段内的所有状态码。
+
+#### Scenario: 2xx 范围匹配
+- **WHEN** HTTP target 配置 `expect.status: ["2xx"]`，且响应状态码为 200
+- **THEN** 系统 SHALL 判定状态码匹配
+
+#### Scenario: 2xx 范围匹配 204
+- **WHEN** HTTP target 配置 `expect.status: ["2xx"]`，且响应状态码为 204
+- **THEN** 系统 SHALL 判定状态码匹配
+
+#### Scenario: 2xx 范围不匹配 301
+- **WHEN** HTTP target 配置 `expect.status: ["2xx"]`，且响应状态码为 301
+- **THEN** 系统 SHALL 判定状态码不匹配
+
+#### Scenario: 混合精确值与范围模式
+- **WHEN** HTTP target 配置 `expect.status: ["2xx", 301]`，且响应状态码为 301
+- **THEN** 系统 SHALL 判定状态码匹配（精确值 301 匹配）
+
+#### Scenario: 混合精确值与范围模式范围命中
+- **WHEN** HTTP target 配置 `expect.status: ["2xx", 301]`，且响应状态码为 204
+- **THEN** 系统 SHALL 判定状态码匹配（2xx 范围命中）
+
+#### Scenario: 5xx 范围匹配
+- **WHEN** HTTP target 配置 `expect.status: ["5xx"]`，且响应状态码为 503
+- **THEN** 系统 SHALL 判定状态码匹配
--- a/openspec/specs/probe-config/spec.md
+++ b/openspec/specs/probe-config/spec.md
@@ -5,7 +5,7 @@
 ## Requirements

 ### Requirement: YAML 配置文件格式
-系统 SHALL 支持通过 YAML 配置文件定义全部运行参数，包括 server 配置、runtime 配置、checker 默认值和 typed target 列表（含可选 group 字段）。target MUST 使用 `type` 字段声明 checker 类型，HTTP 领域字段 MUST 放在 `http` 分组，command 领域字段 MUST 放在 `command` 分组。
+系统 SHALL 支持通过 YAML 配置文件定义全部运行参数，包括 server 配置、runtime 配置、checker 默认值和 typed target 列表（含可选 group 字段）。target MUST 使用 `type` 字段声明 checker 类型，HTTP 领域字段 MUST 放在 `http` 分组，command 领域字段 MUST 放在 `command` 分组。HTTP target 的 `http` 分组 SHALL 支持可选的 `ignoreSSL`（布尔值）和 `maxRedirects`（非负整数）字段。

 #### Scenario: 完整配置文件解析
 - **WHEN** 系统启动并读取包含 server、runtime、defaults、targets（含 group 字段）的 YAML 配置文件
@@ -13,7 +13,7 @@

 #### Scenario: 最简 HTTP 配置文件解析
 - **WHEN** 系统读取只包含一个 `type: http` target 和 `http.url` 的 YAML 配置文件（省略 server、runtime、defaults 和 expect）
- **THEN** 系统 SHALL 使用内置默认值填充未指定的字段（host=127.0.0.1, port=3000, dir=./data, interval=30s, timeout=10s, runtime.maxConcurrentChecks=20, http.method=GET, http.maxBodyBytes=100MB, group="default"）
+- **THEN** 系统 SHALL 使用内置默认值填充未指定的字段（host=127.0.0.1, port=3000, dir=./data, interval=30s, timeout=10s, runtime.maxConcurrentChecks=20, http.method=GET, http.maxBodyBytes=100MB, http.ignoreSSL=false, http.maxRedirects=0, group="default"）

 #### Scenario: 最简 command 配置文件解析
 - **WHEN** 系统读取只包含一个 `type: command` target 和 `command.exec` 的 YAML 配置文件
@@ -23,6 +23,14 @@
 - **WHEN** 某个 target 指定 interval、timeout 或对应领域分组中的默认字段
 - **THEN** 该 target SHALL 使用其自身的值，不受 defaults 中对应字段影响

+#### Scenario: HTTP target 配置 ignoreSSL
+- **WHEN** YAML 配置中 HTTP target 设置 `http.ignoreSSL: true`
+- **THEN** 系统 SHALL 解析该字段并在执行时跳过 SSL 证书校验
+
+#### Scenario: HTTP target 配置 maxRedirects
+- **WHEN** YAML 配置中 HTTP target 设置 `http.maxRedirects: 5`
+- **THEN** 系统 SHALL 解析该字段并在执行时允许最多跟随 5 次重定向
+
 ### Requirement: CLI 参数
 系统 SHALL 通过单一命令行参数接受 YAML 配置文件路径。

@@ -77,6 +85,30 @@
 - **WHEN** maxBodyBytes 或 maxOutputBytes 值不是有效的 size 格式
 - **THEN** 系统 SHALL 以错误退出并提示支持 B、KB、MB、GB 格式

+#### Scenario: HTTP method 非法
+- **WHEN** YAML 中某个 HTTP target 的 `http.method` 不是 GET、HEAD、POST、PUT、PATCH、DELETE、OPTIONS 之一
+- **THEN** 系统 SHALL 以错误退出，提示该 target 的 method 不合法
+
+#### Scenario: URL 格式非法
+- **WHEN** YAML 中某个 HTTP target 的 `http.url` 不以 `http://` 或 `https://` 开头
+- **THEN** 系统 SHALL 以错误退出，提示该 target 的 URL 格式不合法
+
+#### Scenario: maxRedirects 非法
+- **WHEN** YAML 中某个 HTTP target 的 `http.maxRedirects` 为负数
+- **THEN** 系统 SHALL 以错误退出，提示该 target 的 maxRedirects 必须为非负整数
+
+#### Scenario: maxRedirects 非整数非法
+- **WHEN** YAML 中某个 HTTP target 的 `http.maxRedirects` 不是非负整数（如 `1.5` 或 `"5"`）
+- **THEN** 系统 SHALL 以错误退出，提示该 target 的 maxRedirects 必须为非负整数
+
+#### Scenario: ignoreSSL 类型非法
+- **WHEN** YAML 中某个 HTTP target 的 `http.ignoreSSL` 不是布尔值
+- **THEN** 系统 SHALL 以错误退出，提示该 target 的 ignoreSSL 必须为布尔值
+
+#### Scenario: status 模式非法
+- **WHEN** YAML 中某个 HTTP target 的 `expect.status` 包含不符合 `数字xx` 格式的字符串（如 `"abc"`、`"2x"`）
+- **THEN** 系统 SHALL 以错误退出，提示该 target 的 status 模式不合法
+
 ### Requirement: size 配置解析
 系统 SHALL 支持使用单位字符串配置读取上限，单位包括 `B`、`KB`、`MB` 和 `GB`。

@@ -107,7 +139,7 @@
 - **THEN** 系统 SHALL 调用 `Bun.YAML.parse()` 将内容解析为配置对象

 ### Requirement: expect 配置增强
-系统 SHALL 支持 typed target 的领域专用 expect 配置，包括 HTTP 的 `status`、`headers`、`body` 和 command 的 `exitCode`、`stdout`、`stderr`。内容类 expect MUST 使用数组表达配置顺序。
+系统 SHALL 支持 typed target 的领域专用 expect 配置，包括 HTTP 的 `status`（支持精确数字和范围模式）、`headers`、`body` 和 command 的 `exitCode`、`stdout`、`stderr`。内容类 expect MUST 使用数组表达配置顺序。

 #### Scenario: 解析 HTTP expect 配置
 - **WHEN** YAML 配置文件中 HTTP target 的 expect 包含 status、headers、body 规则数组及内部方法
@@ -125,6 +157,14 @@
 - **WHEN** HTTP target 未配置 `expect.status`
 - **THEN** 系统 SHALL 在执行 expect 时使用默认 `status: [200]` 语义

+#### Scenario: 配置 HTTP status 范围模式
+- **WHEN** HTTP target 配置 `expect.status: ["2xx"]`
+- **THEN** 系统 SHALL 在执行 expect 时匹配所有 200-299 状态码
+
+#### Scenario: 配置 HTTP status 混合模式
+- **WHEN** HTTP target 配置 `expect.status: ["2xx", 301]`
+- **THEN** 系统 SHALL 在执行 expect 时匹配所有 200-299 状态码或精确匹配 301
+
 #### Scenario: 不配置 command exitCode
 - **WHEN** command target 未配置 `expect.exitCode`
 - **THEN** 系统 SHALL 在执行 expect 时使用默认 `exitCode: [0]` 语义
--- a/openspec/specs/probe-data-store/spec.md
+++ b/openspec/specs/probe-data-store/spec.md
@@ -121,7 +121,7 @@

 #### Scenario: HTTP target config 序列化
 - **WHEN** 同步 HTTP target
- **THEN** targets.config SHALL 存储 JSON，包含 url、method、headers、body、maxBodyBytes
+- **THEN** targets.config SHALL 存储 JSON，包含 url、method、headers、body、maxBodyBytes、ignoreSSL、maxRedirects

 #### Scenario: command target config 序列化
 - **WHEN** 同步 command target
--- a/openspec/specs/probe-engine/spec.md
+++ b/openspec/specs/probe-engine/spec.md
@@ -31,7 +31,7 @@
 - **THEN** 系统 MUST 同时最多运行 3 个检查，其余检查等待并发槽位释放

 ### Requirement: HTTP 拨测执行
-系统 SHALL 对 `type: http` 的目标执行 HTTP 请求，支持 GET、POST、PUT、DELETE、PATCH、HEAD 方法，并携带 `http.headers` 和 `http.body`。
+系统 SHALL 对 `type: http` 的目标执行 HTTP 请求，支持 GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS 方法，并携带 `http.headers` 和 `http.body`。系统 SHALL 支持 `http.ignoreSSL` 配置跳过 SSL 证书校验，支持 `http.maxRedirects` 配置控制重定向行为。

 #### Scenario: 执行 GET 请求
 - **WHEN** 目标配置 method 为 GET
@@ -49,6 +49,34 @@
 - **WHEN** HTTP response body 超过该 target 的 maxBodyBytes
 - **THEN** 系统 MUST 停止读取并记录 `matched=false` 和结构化输出超限错误

+#### Scenario: 忽略 SSL 证书校验
+- **WHEN** 目标配置 `http.ignoreSSL: true` 且目标 URL 为 HTTPS
+- **THEN** 系统 SHALL 跳过 SSL 证书校验，即使证书无效也正常完成请求
+
+#### Scenario: 不忽略 SSL 证书校验
+- **WHEN** 目标未配置 `http.ignoreSSL` 或配置为 `false`，且目标 URL 使用自签名证书
+- **THEN** 系统 SHALL 因 SSL 证书校验失败而记录请求错误
+
+#### Scenario: 默认不跟随重定向
+- **WHEN** 目标未配置 `http.maxRedirects` 或配置为 0，且服务端返回 301/302
+- **THEN** 系统 SHALL 不跟随重定向，直接返回 301/302 的响应状态码和响应头
+
+#### Scenario: 配置跟随重定向
+- **WHEN** 目标配置 `http.maxRedirects: 5` 且服务端返回重定向
+- **THEN** 系统 SHALL 跟随重定向，最多跟随 5 次
+
+#### Scenario: 超过最大重定向次数
+- **WHEN** 目标配置 `http.maxRedirects: 1` 且服务端连续返回两次重定向
+- **THEN** 系统 SHALL 只跟随第一次重定向，并返回第二次重定向响应的状态码和响应头
+
+#### Scenario: 响应体编码自动检测
+- **WHEN** HTTP 响应的 `Content-Type` header 包含 `charset=gbk`
+- **THEN** 系统 SHALL 使用 GBK 编码解码响应体，而非硬编码 UTF-8
+
+#### Scenario: 响应体编码回退 UTF-8
+- **WHEN** HTTP 响应的 `Content-Type` header 未指定 charset
+- **THEN** 系统 SHALL 使用 UTF-8 编码解码响应体
+
 ### Requirement: 请求超时控制
 系统 SHALL 对每次 checker 执行实施超时控制，超时时间使用目标配置的 timeout 值。

@@ -71,10 +99,18 @@
 - **WHEN** HTTP target 未配置 `expect.status`
 - **THEN** 系统 SHALL 按默认 `status: [200]` 校验响应状态码

-#### Scenario: 校验 HTTP 状态码
+#### Scenario: 校验 HTTP 状态码精确值
 - **WHEN** HTTP target 配置了 `expect.status: [200, 201]`
 - **THEN** 系统 SHALL 检查响应状态码是否在列表中，将匹配结果记录到 matched 字段

+#### Scenario: 校验 HTTP 状态码范围模式
+- **WHEN** HTTP target 配置了 `expect.status: ["2xx"]`
+- **THEN** 系统 SHALL 检查响应状态码是否在 200-299 范围内
+
+#### Scenario: 校验 HTTP 状态码混合模式
+- **WHEN** HTTP target 配置了 `expect.status: ["2xx", 301]`，且响应状态码为 204
+- **THEN** 系统 SHALL 判定状态码匹配（204 属于 2xx 范围）
+
 #### Scenario: 校验 HTTP 响应头
 - **WHEN** HTTP target 配置了 `expect.headers: {"Content-Type": {contains: "application/json"}}`
 - **THEN** 系统 SHALL 检查响应头是否符合指定规则，全部匹配时继续后续阶段