refactor: expect 类型模型重构，Raw/Resolved 双层分离与断言基础设施内聚

- 重命名 ContentRules→ContentExpectations, KeyValueExpect→KeyedExpectations - 新增 Raw/Resolved 双层模型：resolve 阶段物化为执行计划，store 持久化 Raw 快照 - HTTP body 按需读取：status/headers 失败或无 body expectation 时不读取 body - 新增 displayValueExpectation() 解包 failure.expected 用户可读展示 - 修复 checkEarlyTimeout 独立 lte/lt 检查，修复 KeyedExpectations JSON Schema - 新增 expect/value.ts(resolve/check/display)、keyed.ts、content.ts、headers.ts、status.ts - 删除旧 normalize.ts/matcher.ts/validate-matcher.ts/key-value.ts - 更新 DEVELOPMENT.md：expect 五层管线表、displayValueExpectation、1.7↔1.10 交叉引用 - 同步 13 个 main specs，归档 refactor-expect-type-model 变更（62/62 tasks）
2026-05-20 16:12:48 +08:00
parent 6098be2d9e
commit 60a54b483f
90 changed files with 2487 additions and 1493 deletions
--- a/src/server/checker/runner/db/execute.ts
+++ b/src/server/checker/runner/db/execute.ts
@@ -3,11 +3,12 @@ import { isError } from "es-toolkit";

 import type { CheckResult, RawTargetConfig } from "../../types";
 import type { CheckerContext, CheckerDefinition, CheckerValidationInput, ResolveContext } from "../types";
-import type { DbExpectConfig, DbTargetConfig, ResolvedDbTarget } from "./types";
+import type { DbTargetConfig, RawDbExpectConfig, ResolvedDbExpectConfig, ResolvedDbTarget } from "./types";

-import { checkContentRules } from "../../expect/content";
+import { checkContentExpectations, resolveContentExpectations } from "../../expect/content";
 import { errorFailure } from "../../expect/failure";
-import { checkValueMatcher } from "../../expect/matcher";
+import { resolveKeyedExpectations } from "../../expect/keyed";
+import { checkValueExpectation, resolveValueExpectation } from "../../expect/value";
 import { checkRowCount, checkRows } from "./expect";
 import { dbCheckerSchemas } from "./schema";
 import { validateDbConfig } from "./validate";
@@ -77,7 +78,7 @@ export class DbChecker implements CheckerDefinition<ResolvedDbTarget> {
          rowCount: null,
          rowsPreview: null,
        };
-        const durationResult = checkValueMatcher(durationMs, t.expect?.durationMs, {
+        const durationResult = checkValueExpectation(durationMs, t.expect?.durationMs, {
          message: "durationMs mismatch",
          path: "durationMs",
          phase: "duration",
@@ -138,7 +139,7 @@ export class DbChecker implements CheckerDefinition<ResolvedDbTarget> {
        };
      }

-      const durationResult = checkValueMatcher(durationMs, t.expect?.durationMs, {
+      const durationResult = checkValueExpectation(durationMs, t.expect?.durationMs, {
        message: "durationMs mismatch",
        path: "durationMs",
        phase: "duration",
@@ -186,7 +187,10 @@ export class DbChecker implements CheckerDefinition<ResolvedDbTarget> {
      }

      if (t.expect?.result && t.expect.result.length > 0) {
-        const resultCheck = checkContentRules({ rowCount, rows }, t.expect.result, { path: "result", phase: "result" });
+        const resultCheck = checkContentExpectations({ rowCount, rows }, t.expect.result, {
+          path: "result",
+          phase: "result",
+        });
        if (!resultCheck.matched) {
          return {
            detail: null,
@@ -223,17 +227,28 @@ export class DbChecker implements CheckerDefinition<ResolvedDbTarget> {
  resolve(target: RawTargetConfig, context: ResolveContext): ResolvedDbTarget {
    const t = target as RawTargetConfig & { db: DbTargetConfig; type: "db" };

+    const rawExpect = target.expect as RawDbExpectConfig | undefined;
+    const resolvedExpect: ResolvedDbExpectConfig | undefined = rawExpect
+      ? {
+          durationMs: resolveValueExpectation(rawExpect.durationMs),
+          result: resolveContentExpectations(rawExpect.result),
+          rowCount: resolveValueExpectation(rawExpect.rowCount),
+          rows: rawExpect.rows?.map((r) => resolveKeyedExpectations(r)!),
+        }
+      : undefined;
+
    return {
      db: {
        query: t.db.query,
        url: t.db.url,
      },
      description: null,
-      expect: target.expect as DbExpectConfig | undefined,
+      expect: resolvedExpect,
      group: target.group ?? "default",
      id: t.id,
      intervalMs: context.defaultIntervalMs,
      name: t.name ?? null,
+      rawExpect,
      timeoutMs: context.defaultTimeoutMs,
      type: "db",
    } satisfies ResolvedDbTarget;
--- a/src/server/checker/runner/db/expect.ts
+++ b/src/server/checker/runner/db/expect.ts
@@ -1,20 +1,20 @@
 import { isPlainObject } from "es-toolkit";

-import type { ExpectResult, KeyValueExpect, ValueMatcherInput } from "../../expect/types";
+import type { ExpectationResult, KeyedExpectations, ValueExpectation } from "../../expect/types";

 import { mismatchFailure } from "../../expect/failure";
-import { checkKeyValueExpect } from "../../expect/key-value";
-import { checkValueMatcher } from "../../expect/matcher";
+import { checkKeyedExpectations } from "../../expect/keyed";
+import { checkValueExpectation } from "../../expect/value";

-export function checkRowCount(actual: number, matcher: ValueMatcherInput): ExpectResult {
-  return checkValueMatcher(actual, matcher, {
+export function checkRowCount(actual: number, matcher: ValueExpectation): ExpectationResult {
+  return checkValueExpectation(actual, matcher, {
    message: `rowCount ${actual} 不满足条件`,
    path: "rowCount",
    phase: "rowCount",
  });
 }

-export function checkRows(rows: unknown, rules: KeyValueExpect[]): ExpectResult {
+export function checkRows(rows: unknown, rules: KeyedExpectations[]): ExpectationResult {
  if (!Array.isArray(rows)) {
    return {
      failure: mismatchFailure("row", "rows", rules, rows, "查询结果不是数组"),
@@ -39,7 +39,7 @@ export function checkRows(rows: unknown, rules: KeyValueExpect[]): ExpectResult
      };
    }

-    const result = checkKeyValueExpect(row, rule, { path: `rows[${i}]`, phase: "row" });
+    const result = checkKeyedExpectations(row, rule, { path: `rows[${i}]`, phase: "row" });
    if (!result.matched) return result;
  }

--- a/src/server/checker/runner/db/schema.ts
+++ b/src/server/checker/runner/db/schema.ts
@@ -2,7 +2,11 @@ import { Type } from "@sinclair/typebox";

 import type { CheckerSchemas } from "../types";

-import { createContentRulesSchema, createKeyValueExpectSchema, createValueMatcherSchema } from "../../schema/fragments";
+import {
+  createRawContentExpectationsSchema,
+  createRawKeyedExpectationsSchema,
+  createRawValueExpectationSchema,
+} from "../../schema/fragments";

 export const dbCheckerSchemas: CheckerSchemas = {
  config: Type.Object(
@@ -19,10 +23,10 @@ export const dbCheckerSchemas: CheckerSchemas = {
  defaults: Type.Object({}, { additionalProperties: false }),
  expect: Type.Object(
    {
-      durationMs: Type.Optional(createValueMatcherSchema()),
-      result: Type.Optional(createContentRulesSchema()),
-      rowCount: Type.Optional(createValueMatcherSchema()),
-      rows: Type.Optional(Type.Array(createKeyValueExpectSchema())),
+      durationMs: Type.Optional(createRawValueExpectationSchema()),
+      result: Type.Optional(createRawContentExpectationsSchema()),
+      rowCount: Type.Optional(createRawValueExpectationSchema()),
+      rows: Type.Optional(Type.Array(createRawKeyedExpectationsSchema())),
    },
    { additionalProperties: false },
  ),
--- a/src/server/checker/runner/db/types.ts
+++ b/src/server/checker/runner/db/types.ts
@@ -1,29 +1,44 @@
-import type { ContentRules, KeyValueExpect, ValueMatcherInput } from "../../expect/types";
+import type {
+  ContentExpectations,
+  KeyedExpectations,
+  RawContentExpectations,
+  RawKeyedExpectations,
+  RawValueExpectation,
+  ValueExpectation,
+} from "../../expect/types";
 import type { ResolvedTargetBase } from "../../types";

-export interface DbExpectConfig {
-  durationMs?: ValueMatcherInput;
-  result?: ContentRules;
-  rowCount?: ValueMatcherInput;
-  rows?: KeyValueExpect[];
-}
-
 export interface DbTargetConfig {
  query?: string;
  url: string;
 }

+export interface RawDbExpectConfig {
+  durationMs?: RawValueExpectation;
+  result?: RawContentExpectations;
+  rowCount?: RawValueExpectation;
+  rows?: RawKeyedExpectations[];
+}
+
 export interface ResolvedDbConfig {
  query?: string;
  url: string;
 }

+export interface ResolvedDbExpectConfig {
+  durationMs?: ValueExpectation;
+  result?: ContentExpectations;
+  rowCount?: ValueExpectation;
+  rows?: KeyedExpectations[];
+}
+
 export interface ResolvedDbTarget extends ResolvedTargetBase {
  db: ResolvedDbConfig;
-  expect?: DbExpectConfig;
+  expect?: ResolvedDbExpectConfig;
  group: string;
  intervalMs: number;
  name: null | string;
+  rawExpect?: RawDbExpectConfig;
  timeoutMs: number;
  type: "db";
 }
--- a/src/server/checker/runner/db/validate.ts
+++ b/src/server/checker/runner/db/validate.ts
@@ -1,10 +1,14 @@
-import { isPlainObject, isString } from "es-toolkit";
+import { isString } from "es-toolkit";

 import type { ConfigValidationIssue } from "../../schema/issues";
 import type { CheckerValidationInput } from "../types";

-import { normalizeExpectMatchers } from "../../expect/normalize";
-import { validateContentRules, validateKeyValueExpect, validateValueMatcher } from "../../expect/validate-matcher";
+import {
+  isPlainRecord,
+  validateRawContentExpectations,
+  validateRawKeyedExpectations,
+  validateRawValueExpectation,
+} from "../../expect/validate";
 import { issue, joinPath } from "../../schema/issues";

 export function validateDbConfig(input: CheckerValidationInput): ConfigValidationIssue[] {
@@ -12,7 +16,7 @@ export function validateDbConfig(input: CheckerValidationInput): ConfigValidatio

  for (let i = 0; i < input.targets.length; i++) {
    const target = input.targets[i] as unknown;
-    if (!isPlainObject(target)) continue;
+    if (!isPlainRecord(target)) continue;
    if (target["type"] !== "db") continue;
    issues.push(...validateDbTarget(target, `targets[${i}]`));
  }
@@ -24,11 +28,11 @@ function collectRowExpects(rows: unknown[], path: string, targetName?: string):
  const issues: ConfigValidationIssue[] = [];
  for (let i = 0; i < rows.length; i++) {
    const row = rows[i]!;
-    if (!isPlainObject(row)) {
+    if (!isPlainRecord(row)) {
      issues.push(issue("invalid-type", `${path}[${i}]`, "必须为对象", targetName));
      continue;
    }
-    issues.push(...validateKeyValueExpect(row, `${path}[${i}]`, targetName));
+    issues.push(...validateRawKeyedExpectations(row, `${path}[${i}]`, targetName));
  }
  return issues;
 }
@@ -41,18 +45,16 @@ function getTargetName(target: Record<string, unknown>): string | undefined {
 function validateDbExpect(target: Record<string, unknown>, path: string): ConfigValidationIssue[] {
  const targetName = getTargetName(target);
  const expect = target["expect"];
-  if (expect === undefined || expect === null || !isPlainObject(expect)) return [];
+  if (expect === undefined || expect === null || !isPlainRecord(expect)) return [];
  const issues: ConfigValidationIssue[] = [];
  const expectPath = joinPath(path, "expect");

-  normalizeExpectMatchers(expect, ["durationMs", "rowCount"]);
-
  if (expect["durationMs"] !== undefined) {
-    issues.push(...validateValueMatcher(expect["durationMs"], joinPath(expectPath, "durationMs"), targetName));
+    issues.push(...validateRawValueExpectation(expect["durationMs"], joinPath(expectPath, "durationMs"), targetName));
  }

  if (expect["rowCount"] !== undefined) {
-    issues.push(...validateValueMatcher(expect["rowCount"], joinPath(expectPath, "rowCount"), targetName));
+    issues.push(...validateRawValueExpectation(expect["rowCount"], joinPath(expectPath, "rowCount"), targetName));
  }

  if (expect["rows"] !== undefined) {
@@ -64,10 +66,9 @@ function validateDbExpect(target: Record<string, unknown>, path: string): Config
  }

  if (expect["result"] !== undefined) {
-    issues.push(...validateContentRules(expect["result"], joinPath(expectPath, "result"), targetName));
+    issues.push(...validateRawContentExpectations(expect["result"], joinPath(expectPath, "result"), targetName));
  }

-  // 检查未知字段
  const allowedKeys = new Set(["durationMs", "result", "rowCount", "rows"]);
  for (const key of Object.keys(expect)) {
    if (!allowedKeys.has(key)) {
@@ -83,18 +84,16 @@ function validateDbTarget(target: Record<string, unknown>, path: string): Config
  const targetName = getTargetName(target);
  const db = target["db"];

-  if (!isPlainObject(db)) {
+  if (!isPlainRecord(db)) {
    issues.push(issue("required", joinPath(path, "db"), "缺少 db.url 字段", targetName));
    issues.push(...validateDbExpect(target, path));
    return issues;
  }

-  // url 必填
  if (!isString(db["url"]) || db["url"].trim() === "") {
    issues.push(issue("required", joinPath(joinPath(path, "db"), "url"), "缺少 db.url 字段", targetName));
  }

-  // query 可选但不能为空字符串
  if (db["query"] !== undefined) {
    if (!isString(db["query"])) {
      issues.push(issue("invalid-type", joinPath(joinPath(path, "db"), "query"), "必须为字符串", targetName));
@@ -110,7 +109,6 @@ function validateDbTarget(target: Record<string, unknown>, path: string): Config
    }
  }

-  // 检查未知字段
  const allowedDbKeys = new Set(["query", "url"]);
  for (const key of Object.keys(db)) {
    if (!allowedDbKeys.has(key)) {