Nexus/.cursor/skills/systematic-debugging/defense-in-depth.md

纵深防御校验

概述

当你修复了一个由无效数据引起的 bug 时，在一个地方加校验似乎就够了。但这个单点检查可能会被不同的代码路径、重构或 mock 绕过。

核心原则： 在数据经过的每一层都做校验。让这个 bug 在结构上不可能发生。

为什么需要多层校验

单层校验："我们修了这个 bug" 多层校验："我们让这个 bug 不可能再发生"

不同层级能捕获不同问题：

• 入口校验捕获大多数 bug
• 业务逻辑校验捕获边界情况
• 环境守卫防止特定上下文的危险操作
• 调试日志在其他层级失效时提供帮助

四个层级

第 1 层：入口校验

目的： 在 API 边界拒绝明显无效的输入

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  if (!statSync(workingDirectory).isDirectory()) {
    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
  }
  // ... 继续处理
}

第 2 层：业务逻辑校验

目的： 确保数据对当前操作是合理的

function initializeWorkspace(projectDir: string, sessionId: string) {
  if (!projectDir) {
    throw new Error('projectDir required for workspace initialization');
  }
  // ... 继续处理
}

第 3 层：环境守卫

目的： 防止在特定环境中执行危险操作

async function gitInit(directory: string) {
  // 在测试中，拒绝在临时目录之外执行 git init
  if (process.env.NODE_ENV === 'test') {
    const normalized = normalize(resolve(directory));
    const tmpDir = normalize(resolve(tmpdir()));

    if (!normalized.startsWith(tmpDir)) {
      throw new Error(
        `Refusing git init outside temp dir during tests: ${directory}`
      );
    }
  }
  // ... 继续处理
}

第 4 层：调试埋点

目的： 记录上下文信息以便事后分析

async function gitInit(directory: string) {
  const stack = new Error().stack;
  logger.debug('About to git init', {
    directory,
    cwd: process.cwd(),
    stack,
  });
  // ... 继续处理
}

应用模式

当你发现一个 bug 时：

1. 追踪数据流 —— 错误值从哪里产生的？在哪里被使用？
2. 标注所有检查点 —— 列出数据经过的每一个节点
3. 在每一层添加校验 —— 入口、业务逻辑、环境、调试
4. 测试每一层 —— 尝试绕过第 1 层，验证第 2 层能否捕获

实际案例

Bug：空的 projectDir 导致 git init 在源代码目录执行

数据流：

1. 测试准备 → 空字符串
2. Project.create(name, '')
3. WorkspaceManager.createWorkspace('')
4. git init 在 process.cwd() 中执行

添加的四层防御：

• 第 1 层：Project.create() 校验非空/存在/可写
• 第 2 层：WorkspaceManager 校验 projectDir 非空
• 第 3 层：WorktreeManager 在测试中拒绝在 tmpdir 之外执行 git init
• 第 4 层：git init 前记录堆栈跟踪

结果： 全部 1847 个测试通过，bug 不可能再复现

关键洞察

四个层级缺一不可。在测试过程中，每一层都捕获了其他层遗漏的 bug：

• 不同的代码路径绕过了入口校验
• mock 绕过了业务逻辑检查
• 不同平台的边界情况需要环境守卫
• 调试日志发现了结构性误用

不要止步于一个校验点。 在每一层都添加检查。