name: 纵深防御 description: 用于当无效数据导致深层执行失败时，要求在多系统层进行验证 - 在数据传递的每一层进行验证，使bug结构上不可能发生

纵深防御验证

概述

当你修复由无效数据引起的bug时，在一个地方添加验证感觉足够。但那个单一检查可以被不同的代码路径、重构或模拟绕过。

核心原则： 在数据传递的每一层进行验证。使bug结构上不可能。

为什么需要多层

单一验证：“我们修复了bug” 多层验证：“我们使bug不可能发生”

不同层捕捉不同案例：

入口验证捕捉大多数bug
业务逻辑捕捉边缘案例
环境守卫防止上下文特定危险
调试日志帮助当其他层失败时

四层验证

层1：入口点验证

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

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory不能为空');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory不存在: ${workingDirectory}`);
  }
  if (!statSync(workingDirectory).isDirectory()) {
    throw new Error(`workingDirectory不是目录: ${workingDirectory}`);
  }
  // ... 继续
}

层2：业务逻辑验证

目的： 确保数据对此操作有意义

function initializeWorkspace(projectDir: string, sessionId: string) {
  if (!projectDir) {
    throw new Error('初始化工作空间需要projectDir');
  }
  // ... 继续
}

层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(
        `在测试期间拒绝在临时目录外执行git init: ${directory}`
      );
    }
  }
  // ... 继续
}

层4：调试工具

目的： 捕获上下文用于取证

async function gitInit(directory: string) {
  const stack = new Error().stack;
  logger.debug('即将执行git init', {
    directory,
    cwd: process.cwd(),
    stack,
  });
  // ... 继续
}

应用该模式

当你发现一个bug时：

追踪数据流 - 坏值起源于哪里？在哪里使用？
映射所有检查点 - 列出数据传递的每个点
在每一层添加验证 - 入口、业务、环境、调试
测试每一层 - 尝试绕过层1，验证层2捕捉到它

会话中的示例

Bug: 空的projectDir导致在源代码中执行git init

数据流:

测试设置 → 空字符串
Project.create(name, '')
WorkspaceManager.createWorkspace('')
git init在process.cwd()中运行

添加的四层:

层1: Project.create()验证非空/存在/可写
层2: WorkspaceManager验证projectDir非空
层3: WorktreeManager在测试中拒绝在tmpdir外执行git init
层4: 执行git init前的堆栈跟踪日志

结果: 所有1847个测试通过，bug不可能再现

关键洞察

所有四层都是必要的。在测试过程中，每一层都捕捉到其他层漏掉的bug：

不同的代码路径绕过入口验证
模拟绕过业务逻辑检查
不同平台上的边缘案例需要环境守卫
调试日志识别结构性误用

不要只在一个验证点停止。 在每一层添加检查。