《互联网产品的客户端架构·端形态与体验基础》4.3 用测试固化分层

// file: src/layers/arch-rules.ts
// tier: L1
// verify: node --test test/layers/arch-rules.test.ts

import { findCycles } from "./dependency.ts";
import type { ModuleGraph } from "./dependency.ts";

export type ArchLayer = "view" | "state" | "domain" | "data" | "shared";

export type RuleId =
  | "view-to-data"
  | "domain-to-view"
  | "cycle"
  | "unknown-import";

export interface SourceModule {
  /** 仓库内路径，同时作为模块标识 */
  path: string;
  layer: ArchLayer;
  /** 该文件 import 的模块路径 */
  imports: string[];
}

export interface ArchViolation {
  rule: RuleId;
  file: string;
  target?: string;
  message: string;
}

export interface Exception {
  file: string;
  rule: RuleId;
  /** 例外必须写明原因，空字符串直接拒绝 */
  reason: string;
}

export interface Waived {
  file: string;
  rule: RuleId;
  reason: string;
}

export interface ArchReport {
  checked: number;
  violations: ArchViolation[];
  suppressed: Waived[];
}

/** view 直接访问 data 的规则在这里集中声明，测试与 CI 共用同一份文本 */
export function checkArchitecture(
  modules: SourceModule[],
  exceptions: Exception[] = [],
): ArchReport {
  const byPath = new Map<string, SourceModule>();
  for (const module of modules) {
    if (byPath.has(module.path)) throw new Error(`重复模块: ${module.path}`);
    byPath.set(module.path, module);
  }

  for (const exception of exceptions) {
    if (exception.reason.trim().length === 0) {
      throw new Error(`例外 ${exception.file}/${exception.rule} 必须写明原因`);
    }
    if (!byPath.has(exception.file)) {
      throw new Error(`例外指向未声明模块: ${exception.file}`);
    }
  }

  const violations: ArchViolation[] = [];
  for (const module of modules) {
    for (const target of module.imports) {
      const imported = byPath.get(target);
      if (!imported) {
        violations.push({
          rule: "unknown-import",
          file: module.path,
          target,
          message: `${module.path} 导入了未声明的模块 ${target}`,
        });
        continue;
      }
      if (module.layer === "view" && imported.layer === "data") {
        violations.push({
          rule: "view-to-data",
          file: module.path,
          target,
          message: `视图 ${module.path} 直接访问数据层 ${target}`,
        });
      }
      if (module.layer === "domain" && imported.layer === "view") {
        violations.push({
          rule: "domain-to-view",
          file: module.path,
          target,
          message: `领域 ${module.path} 反向依赖视图 ${target}`,
        });
      }
    }
  }

  const graph: ModuleGraph = {
    modules: modules.map((module) => ({ name: module.path, layer: module.layer })),
    edges: modules.flatMap((module) =>
      module.imports
        .filter((target) => byPath.has(target))
        .map((target) => ({ from: module.path, to: target })),
    ),
  };
  for (const cycle of findCycles(graph)) {
    violations.push({
      rule: "cycle",
      file: cycle.path[0],
      target: cycle.path[1],
      message: `循环依赖: ${cycle.path.join(" -> ")}`,
    });
  }

  const kept: ArchViolation[] = [];
  const suppressed: Waived[] = [];
  for (const violation of violations) {
    const exception = exceptions.find(
      (item) => item.file === violation.file && item.rule === violation.rule,
    );
    if (exception) {
      suppressed.push({
        file: violation.file,
        rule: violation.rule,
        reason: exception.reason,
      });
    } else {
      kept.push(violation);
    }
  }

  const byLocation = (a: ArchViolation, b: ArchViolation): number =>
    a.rule.localeCompare(b.rule) ||
    a.file.localeCompare(b.file) ||
    (a.target ?? "").localeCompare(b.target ?? "");

  kept.sort(byLocation);
  suppressed.sort(
    (a, b) => a.rule.localeCompare(b.rule) || a.file.localeCompare(b.file),
  );

  return { checked: modules.length, violations: kept, suppressed };
}

/** 把报告转成可直接写进 CI 日志的文本行 */
export function formatReport(report: ArchReport): string[] {
  const lines = [`已检查 ${report.checked} 个模块`];
  if (report.violations.length === 0) {
    lines.push("未发现架构违规");
  }
  for (const violation of report.violations) {
    const target = violation.target ? ` -> ${violation.target}` : "";
    lines.push(`[${violation.rule}] ${violation.file}${target}: ${violation.message}`);
  }
  for (const waived of report.suppressed) {
    lines.push(`[waived:${waived.rule}] ${waived.file}: ${waived.reason}`);
  }
  return lines;
}

已检查 6 个模块
[cycle] src/state/draft-store.ts -> src/state/feed-store.ts: 循环依赖: src/state/draft-store.ts -> src/state/feed-store.ts -> src/state/draft-store.ts
[domain-to-view] src/domain/feed.ts -> src/view/toast.ts: 领域 src/domain/feed.ts 反向依赖视图 src/view/toast.ts
[view-to-data] src/view/feed.ts -> src/data/feed-repo.ts: 视图 src/view/feed.ts 直接访问数据层 src/data/feed-repo.ts

node --test test/layers/arch-rules.test.ts

✔ 逐层向内的干净模块图没有违规 (1.116208ms)
✔ 视图直接 import 数据层会被 rule view-to-data 拦住 (0.158625ms)
✔ 领域层 import 视图会被 rule domain-to-view 拦住 (0.086958ms)
✔ 状态层之间的循环依赖单独报告，并给出完整回路 (0.188958ms)
✔ 未声明的 import 被当成边界违规，而不是静默跳过 (0.090958ms)
✔ 失败样例稳定产出三条违规，顺序可直接比对 (8.367167ms)
✔ 有理由的例外可以豁免，但豁免记录必须保留在报告里 (0.178167ms)
✔ 空理由的例外被拒绝，避免用「临时」两个字绕过规则 (0.299666ms)
✔ 例外指向不存在的模块时直接抛错 (0.141333ms)
✔ 重复声明同一个模块路径会抛错，防止层归属被悄悄覆盖 (0.202333ms)
ℹ tests 10
ℹ suites 0
ℹ pass 10
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 194.255834