深度防御验证Skill Defense-in-DepthValidation

---

name: 深度防御验证 description: 在数据通过的每一层进行验证，使bug不可能发生 when_to_use: 当无效数据导致深层执行失败时，需要在多个系统层进行验证 version: 1.1.0 languages: 所有

深度防御验证

概述

当你修复由无效数据引起的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('workspace初始化需要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. 映射所有检查点 - 列出数据通过的所有点
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：

• 不同的代码路径绕过了入口验证
• 模拟绕过了业务逻辑检查
• 不同平台的边缘情况需要环境防护
• 调试日志识别了结构性误用

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