refactor: 清理 checker 遗留边界

2026-05-13 12:53:03 +08:00
parent 7b20b59b79
commit aade0bbff7
6 changed files with 85 additions and 196 deletions
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -167,7 +167,9 @@ export function handleXxx(params, store: ProbeStore, method: string, mode: Runti

 ### 1.7 开发新 Checker

-Checker 是本项目的核心扩展单元。得益于插件式注册架构，完成一个新 checker 后，**配置校验、引擎调度、数据存储、API 层会自动适配**，无需修改这些中间层代码。
+Checker 是本项目的核心扩展单元。得益于插件式注册架构，完成一个新 checker 并注册后，**配置契约组装、引擎调度、数据存储、API 层会自动走 registry 委托链路**，无需在这些中间层添加新的 type 分支。
+
+当前 checker 执行链路已经注册化，但新增 checker 仍需更新中央类型定义、默认注册入口、前端展示常量、配置示例、用户/开发文档和测试。下文清单以这些必要更新为准。

 以下以新增 `tcp` 类型 checker 为例，说明完整的开发步骤。

@@ -499,7 +501,7 @@ export function registerCheckers(registry = checkerRegistry): void {
 }
 ```

-注册后，以下管线会自动适配，**无需修改**：
+注册后，以下管线会通过 registry 自动委托，**无需新增 type 分支**：

 | 模块                          | 自动行为                                                                 |
 | ----------------------------- | ------------------------------------------------------------------------ |
@@ -509,6 +511,8 @@ export function registerCheckers(registry = checkerRegistry): void {
 | `engine.ts`                   | 按 `target.type` 从 registry 取对应 checker 执行 `execute()`             |
 | `store.ts`                    | 按 `target.type` 从 registry 取对应 checker 执行 `serialize()`           |

+注意：自动适配指上述中间层不需要新增 `switch/case` 或类型分支；开发者仍需按后续步骤更新类型、注册、前端展示、示例、文档和测试。
+
 #### 1.7.7 步骤六：更新前端展示

 | 文件                                        | 修改内容                                                     |
@@ -586,8 +590,8 @@ export function registerCheckers(registry = checkerRegistry): void {

 - **调度**：`ProbeEngine` 用 `es-toolkit/groupBy` 按 interval 分组，每组独立 `setInterval` 定时触发
 - **并发控制**：`es-toolkit/Semaphore` 限制全局最大并发数（`maxConcurrentChecks`），`acquire()` 阻塞等待
- **Runner 选择**：`engine.runCheck()` 按 `target.type` 分发到 `runHttpCheck` 或 `runCommandCheck`
- **超时控制**：HTTP 用 `AbortController`，Command 用 `setTimeout` + `proc.kill()`
+- **Runner 选择**：`engine.runCheck()` 通过 `checkerRegistry.get(target.type)` 获取 checker，并调用 `checker.execute(target, { signal })`
+- **超时控制**：`ProbeEngine` 为每次检查创建 `AbortController` 并按 `target.timeoutMs` 触发 abort；checker 必须使用 `CheckerContext.signal` 感知超时，HTTP 将 signal 传给 `fetch()`，Command 在 signal abort 时 `proc.kill()`
 - **结果写入**：检查结果通过 `store.insertCheckResult()` 写入 SQLite，engine 通过 `targetNameToId` 缓存 name→id 映射
 - **生命周期**：`start()`/`stop()` 管理定时器，`stop()` 清理所有 `setInterval`

@@ -598,7 +602,7 @@ export function registerCheckers(registry = checkerRegistry): void {
 **HTTP 校验流程**：

 ```
-runHttpCheck → 收集观测(statusCode/headers)
+HttpChecker.execute → 收集观测(statusCode/headers)
 → status → headers → (early duration) → body(按需) → (final duration)
 → 首个失败即停止，返回 CheckFailure
 ```
@@ -608,8 +612,8 @@ HTTP checker 的 `durationMs` 覆盖完整执行（含重定向、响应体读
 **Command 校验流程**：

 ```
-runCommandCheck → 收集观测(exitCode/stdout/stderr/durationMs)
-→ checkCommandExpect → exitCode → duration → stdout → stderr
+CommandChecker.execute → 收集观测(exitCode/stdout/stderr/durationMs)
+→ exitCode → duration → stdout → stderr
 → 首个失败即停止
 ```

--- a/src/server/checker/runner/command/runner.ts
+++ b/src/server/checker/runner/command/runner.ts
@@ -35,7 +35,7 @@ export class CommandChecker implements Checker {
    try {
      proc = Bun.spawn([t.command.exec, ...t.command.args], {
        cwd: t.command.cwd,
-        env: { ...process.env, ...t.command.env },
+        env: t.command.env,
        stderr: "pipe",
        stdin: "ignore",
        stdout: "pipe",
--- a/src/server/checker/runner/http/expect.ts
+++ b/src/server/checker/runner/http/expect.ts
@@ -1,9 +1,7 @@
-import type { HeaderExpect, HttpExpectConfig } from "../../types";
+import type { HeaderExpect } from "../../types";
 import type { ExpectResult } from "../shared/duration";

-import { checkBodyExpect } from "../shared/body";
-import { checkDuration } from "../shared/duration";
-import { errorFailure, mismatchFailure } from "../shared/failure";
+import { mismatchFailure } from "../shared/failure";
 import { applyOperator } from "../shared/operator";

 export function checkHeaders(
@@ -45,40 +43,6 @@ export function checkHeaders(
  return { failure: null, matched: true };
 }

-export function checkHttpExpect(
-  statusCode: number,
-  headers: Record<string, string>,
-  body: null | string,
-  durationMs: number,
-  expect?: HttpExpectConfig,
-): ExpectResult {
-  if (!expect) {
-    return checkStatus(statusCode, [200]);
-  }
-
-  const statusResult = checkStatus(statusCode, expect.status ?? [200]);
-  if (!statusResult.matched) return statusResult;
-
-  const headersResult = checkHeaders(headers, expect.headers);
-  if (!headersResult.matched) return headersResult;
-
-  if (expect.body && expect.body.length > 0) {
-    if (body === null) {
-      return {
-        failure: errorFailure("body", "body", "body is null but body rules are configured"),
-        matched: false,
-      };
-    }
-    const bodyResult = checkBodyExpect(body, expect.body);
-    if (!bodyResult.matched) return bodyResult;
-  }
-
-  const durationResult = checkDuration(durationMs, expect.maxDurationMs);
-  if (!durationResult.matched) return durationResult;
-
-  return { failure: null, matched: true };
-}
-
 export function checkStatus(statusCode: number, allowed: Array<number | string>): ExpectResult {
  const matched = allowed.some((pattern) => {
    if (typeof pattern === "number") return statusCode === pattern;
--- a/src/server/checker/store.ts
+++ b/src/server/checker/store.ts
@@ -277,8 +277,9 @@ export class ProbeStore {
    const tx = this.db.transaction(() => {
      for (const t of targets) {
        const type = t.type;
-        const target = buildTargetDisplay(t);
-        const config = buildTargetConfig(t);
+        const serialized = checkerRegistry.get(t.type).serialize(t);
+        const target = serialized.target;
+        const config = serialized.config;
        const expect = t.expect ? JSON.stringify(t.expect) : null;

        if (existingMap.has(t.name)) {
@@ -299,14 +300,6 @@ export class ProbeStore {
  }
 }

-function buildTargetConfig(t: ResolvedTarget): string {
-  return checkerRegistry.get(t.type).serialize(t).config;
-}
-
-function buildTargetDisplay(t: ResolvedTarget): string {
-  return checkerRegistry.get(t.type).serialize(t).target;
-}
-
 function ensureDir(dir: string): void {
  try {
    fsMkdirSync(dir, { recursive: true });
--- a/tests/server/checker/runner/command/runner.test.ts
+++ b/tests/server/checker/runner/command/runner.test.ts
@@ -7,6 +7,10 @@ import { CommandChecker } from "../../../../../src/server/checker/runner/command

 const checker = new CommandChecker();

+const processEnv = Object.fromEntries(
+  Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined),
+);
+
 function makeCtx(timeoutMs = 5000): CheckerContext {
  const controller = new AbortController();
  setTimeout(() => controller.abort(), timeoutMs);
@@ -21,7 +25,7 @@ function makeTarget(
    command: {
      args: ["hello"],
      cwd: "/tmp",
-      env: {},
+      env: processEnv,
      exec: "echo",
      maxOutputBytes: 1024 * 1024,
      ...command,
@@ -125,6 +129,22 @@ describe("CommandChecker", () => {
    expect(result.matched).toBe(true);
  });

+  test("execute 使用 resolved env", async () => {
+    const result = await checker.execute(
+      makeTarget(
+        {
+          args: ["-e", "console.log(process.env.DIAL_TEST_ENV ?? '')"],
+          env: { DIAL_TEST_ENV: "resolved-env" },
+          exec: process.execPath,
+        },
+        { expect: { stdout: [{ contains: "resolved-env" }] } },
+      ),
+      makeCtx(),
+    );
+
+    expect(result.matched).toBe(true);
+  });
+
  test("serialize 返回命令摘要和 config JSON", () => {
    const target = makeTarget({ args: ["hello"], exec: "echo" });
    const s = checker.serialize(target);
--- a/tests/server/checker/runner/http/expect.test.ts
+++ b/tests/server/checker/runner/http/expect.test.ts
@@ -1,152 +1,66 @@
 import { describe, expect, test } from "bun:test";

-import { checkHttpExpect, checkStatus } from "../../../../../src/server/checker/runner/http/expect";
+import { checkHeaders, checkStatus } from "../../../../../src/server/checker/runner/http/expect";

-function obs(
-  overrides: { body?: null | string; durationMs?: number; headers?: Record<string, string>; statusCode?: number } = {},
-) {
-  return {
-    body: overrides.body ?? "",
-    durationMs: overrides.durationMs ?? 100,
-    headers: overrides.headers ?? {},
-    statusCode: overrides.statusCode ?? 200,
-  };
-}
-
-describe("checkHttpExpect", () => {
-  test("无 expect 配置时默认检查 status [200] 匹配成功", () => {
-    const r = checkHttpExpect(obs().statusCode, obs().headers, obs().body, obs().durationMs);
-    expect(r.matched).toBe(true);
-    expect(r.failure).toBeNull();
+describe("checkHeaders", () => {
+  test("未配置 headers expect 时匹配成功", () => {
+    const result = checkHeaders({});
+    expect(result.matched).toBe(true);
+    expect(result.failure).toBeNull();
  });

-  test("无 expect 配置时 status 非 200 匹配失败", () => {
-    const r = checkHttpExpect(500, {}, "", 100);
-    expect(r.matched).toBe(false);
-    expect(r.failure).not.toBeNull();
-    expect(r.failure!.phase).toBe("status");
-    expect(r.failure!.kind).toBe("mismatch");
+  test("字符串格式按等值匹配", () => {
+    const headers = { "content-type": "application/json", "x-api": "v1" };
+
+    expect(checkHeaders(headers, { "content-type": "application/json" }).matched).toBe(true);
+    expect(checkHeaders(headers, { "content-type": "text/html" }).matched).toBe(false);
  });

-  test("status 匹配指定状态码", () => {
-    const cfg = { status: [200, 301] };
-    expect(checkHttpExpect(200, {}, "", 100, cfg).matched).toBe(true);
-    expect(checkHttpExpect(301, {}, "", 100, cfg).matched).toBe(true);
-    expect(checkHttpExpect(404, {}, "", 100, cfg).matched).toBe(false);
+  test("header 名称按小写响应头匹配", () => {
+    const headers = { "content-type": "application/json" };
+
+    expect(checkHeaders(headers, { "Content-Type": "application/json" }).matched).toBe(true);
  });

-  test("status 不匹配返回 phase=status 的失败", () => {
-    const r = checkHttpExpect(503, {}, "", 100, { status: [200] });
-    expect(r.matched).toBe(false);
-    expect(r.failure!.phase).toBe("status");
-    expect(r.failure!.expected).toEqual([200]);
-    expect(r.failure!.actual).toBe(503);
+  test("操作符格式匹配", () => {
+    const headers = { "content-type": "application/json" };
+
+    expect(checkHeaders(headers, { "content-type": { contains: "json" } }).matched).toBe(true);
+    expect(checkHeaders(headers, { "content-type": { match: "^application/" } }).matched).toBe(true);
+    expect(checkHeaders(headers, { "content-type": { contains: "xml" } }).matched).toBe(false);
  });

-  test("duration 在限制内匹配成功", () => {
-    const r = checkHttpExpect(200, {}, "", 50, { maxDurationMs: 100 });
-    expect(r.matched).toBe(true);
+  test("缺失 header 默认返回失败", () => {
+    const result = checkHeaders({}, { "x-missing": "value" });
+
+    expect(result.matched).toBe(false);
+    expect(result.failure!.phase).toBe("headers");
+    expect(result.failure!.kind).toBe("mismatch");
  });

-  test("duration 超过限制匹配失败", () => {
-    const r = checkHttpExpect(200, {}, "", 200, { maxDurationMs: 100 });
-    expect(r.matched).toBe(false);
-    expect(r.failure!.phase).toBe("duration");
-  });
+  test("缺失 header 且 exists=false 时匹配成功", () => {
+    const result = checkHeaders({}, { "x-missing": { exists: false } });

-  test("duration 恰好等于限制匹配成功", () => {
-    const r = checkHttpExpect(200, {}, "", 100, { maxDurationMs: 100 });
-    expect(r.matched).toBe(true);
-  });
-
-  test("headers 字符串格式检查（等于）", () => {
-    const h = { "content-type": "application/json", "x-api": "v1" };
-    expect(checkHttpExpect(200, h, "", 100, { headers: { "content-type": "application/json" } }).matched).toBe(true);
-    expect(checkHttpExpect(200, h, "", 100, { headers: { "content-type": "text/html" } }).matched).toBe(false);
-  });
-
-  test("headers 操作符格式检查", () => {
-    const h = { "content-type": "application/json" };
-    expect(checkHttpExpect(200, h, "", 100, { headers: { "content-type": { contains: "json" } } }).matched).toBe(true);
-    expect(checkHttpExpect(200, h, "", 100, { headers: { "content-type": { match: "^application/" } } }).matched).toBe(
-      true,
-    );
-    expect(checkHttpExpect(200, h, "", 100, { headers: { "content-type": { contains: "xml" } } }).matched).toBe(false);
-  });
-
-  test("headers 大小写不敏感匹配", () => {
-    const h = { "content-type": "application/json" };
-    expect(checkHttpExpect(200, h, "", 100, { headers: { "Content-Type": "application/json" } }).matched).toBe(true);
-  });
-
-  test("headers 不存在时返回失败", () => {
-    const r = checkHttpExpect(200, {}, "", 100, { headers: { "x-missing": "value" } });
-    expect(r.matched).toBe(false);
-    expect(r.failure!.phase).toBe("headers");
-  });
-
-  test("body 规则数组按顺序检查", () => {
-    const body = JSON.stringify({ count: 5, status: "ok" });
-    const r = checkHttpExpect(200, {}, body, 100, {
-      body: [{ contains: "ok" }, { json: { gte: 1, path: "$.count" } }],
-    });
-    expect(r.matched).toBe(true);
-  });
-
-  test("body 第一条规则失败立即返回", () => {
-    const r = checkHttpExpect(200, {}, "hello world", 100, {
-      body: [{ contains: "missing" }, { contains: "hello" }],
-    });
-    expect(r.matched).toBe(false);
-    expect(r.failure!.path).toBe("body[0]");
-  });
-
-  test("body 为 null 但有 body 规则时报错", () => {
-    const r = checkHttpExpect(200, {}, null, 100, { body: [{ contains: "test" }] });
-    expect(r.matched).toBe(false);
-    expect(r.failure!.kind).toBe("error");
-  });
-
-  test("完整流水线 status->headers->body->duration 全部通过", () => {
-    const r = checkHttpExpect(200, { "content-type": "application/json" }, JSON.stringify({ status: "healthy" }), 50, {
-      body: [{ json: { equals: "healthy", path: "$.status" } }],
-      headers: { "content-type": { contains: "json" } },
-      maxDurationMs: 100,
-      status: [200],
-    });
-    expect(r.matched).toBe(true);
-    expect(r.failure).toBeNull();
-  });
-
-  test("完整流水线 status 和 headers 通过但 duration 失败", () => {
-    const r = checkHttpExpect(200, {}, "", 500, { maxDurationMs: 100, status: [200] });
-    expect(r.matched).toBe(false);
-    expect(r.failure!.phase).toBe("duration");
-  });
-
-  test("完整流水线 status 通过但 headers 失败", () => {
-    const r = checkHttpExpect(200, { "x-api": "v1" }, "", 50, {
-      headers: { "x-api": "v2" },
-      maxDurationMs: 100,
-      status: [200],
-    });
-    expect(r.matched).toBe(false);
-    expect(r.failure!.phase).toBe("headers");
-  });
-
-  test("完整流水线 status/headers 通过但 body 失败", () => {
-    const r = checkHttpExpect(200, { "content-type": "text/plain" }, "error occurred", 50, {
-      body: [{ contains: "success" }],
-      headers: { "content-type": "text/plain" },
-      maxDurationMs: 100,
-      status: [200],
-    });
-    expect(r.matched).toBe(false);
-    expect(r.failure!.phase).toBe("body");
+    expect(result.matched).toBe(true);
+    expect(result.failure).toBeNull();
  });
 });

 describe("checkStatus 范围匹配", () => {
+  test("无 expect 配置时默认 status [200] 可由调用方使用 checkStatus 表达", () => {
+    const result = checkStatus(200, [200]);
+    expect(result.matched).toBe(true);
+    expect(result.failure).toBeNull();
+  });
+
+  test("status 不匹配返回 phase=status 的失败", () => {
+    const result = checkStatus(503, [200]);
+    expect(result.matched).toBe(false);
+    expect(result.failure!.phase).toBe("status");
+    expect(result.failure!.expected).toEqual([200]);
+    expect(result.failure!.actual).toBe(503);
+  });
+
  test("2xx 范围匹配 200", () => {
    expect(checkStatus(200, ["2xx"]).matched).toBe(true);
  });
@@ -163,11 +77,11 @@ describe("checkStatus 范围匹配", () => {
    expect(checkStatus(503, ["5xx"]).matched).toBe(true);
  });

-  test("混合精确值与范围模式 — 精确命中", () => {
+  test("混合精确值与范围模式命中精确值", () => {
    expect(checkStatus(301, ["2xx", 301]).matched).toBe(true);
  });

-  test("混合精确值与范围模式 — 范围命中", () => {
+  test("混合精确值与范围模式命中范围", () => {
    expect(checkStatus(204, ["2xx", 301]).matched).toBe(true);
  });

@@ -180,12 +94,6 @@ describe("checkStatus 范围匹配", () => {
    expect(checkStatus(404, [200, 201]).matched).toBe(false);
  });

-  test("范围匹配失败返回 phase=status 的 failure", () => {
-    const r = checkStatus(404, ["2xx"]);
-    expect(r.matched).toBe(false);
-    expect(r.failure!.phase).toBe("status");
-  });
-
  test("1xx 范围匹配 101", () => {
    expect(checkStatus(101, ["1xx"]).matched).toBe(true);
  });