name: defense-in-depth-validation description: 在数据传递的每个层次进行验证，使bug不可能发生。当无效数据导致执行深层失败时使用，需要在多个系统层次进行验证。 version: 1.1.0
深度防御验证
概述
当你修复一个由无效数据引起的bug时，在一个地方添加验证似乎足够了。但那个单一检查可能被不同的代码路径、重构或模拟绕过。
核心原则： 在数据传递的每个层次进行验证。使bug在结构上不可能发生。
为什么多层验证
单一验证：“我们修复了bug” 多层验证：“我们使bug不可能发生”
不同层次捕获不同情况：
- 入口验证捕获大多数bug
- 业务逻辑捕获边缘情况
- 环境防护防止特定上下文的风险
- 调试日志在其他层次失败时提供帮助
四层验证
第一层：入口点验证
目的： 在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}`);
}
// ... 继续
}
第二层：业务逻辑验证
目的： 确保数据对该操作有意义
function initializeWorkspace(projectDir: string, sessionId: string) {
if (!projectDir) {
throw new Error('workspace初始化需要projectDir');
}
// ... 继续
}
第三层：环境防护
目的： 防止在特定上下文中执行危险操作
async function gitInit(directory: string) {
// 在测试中，拒绝在临时目录外进行git初始化
if (process.env.NODE_ENV === 'test') {
const normalized = normalize(resolve(directory));
const tmpDir = normalize(resolve(tmpdir()));
if (!normalized.startsWith(tmpDir)) {
throw new Error(
`测试期间拒绝在临时目录外进行git初始化: ${directory}`
);
}
}
// ... 继续
}
第四层：调试仪器
目的： 捕获上下文用于取证
async function gitInit(directory: string) {
const stack = new Error().stack;
logger.debug('即将进行git初始化', {
directory,
cwd: process.cwd(),
stack,
});
// ... 继续
}
应用模式
当发现bug时：
- 追踪数据流 - 错误值从哪里起源？在哪里使用？
- 映射所有检查点 - 列出数据传递的每个点
- 在每个层次添加验证 - 入口、业务、环境、调试
- 测试每个层次 - 尝试绕过第一层，验证第二层能捕获
会话示例
Bug：空projectDir导致在源代码中进行git init
数据流：
- 测试设置 → 空字符串
Project.create(name, '')WorkspaceManager.createWorkspace('')git init在process.cwd()中运行
添加的四层：
- 第一层：
Project.create()验证不为空/存在/可写 - 第二层：
WorkspaceManager验证projectDir不为空 - 第三层：
WorktreeManager在测试中拒绝在临时目录外进行git初始化 - 第四层：git初始化前的堆栈跟踪日志
结果： 所有1847个测试通过，bug不可能复现
关键洞察
所有四层都是必要的。在测试期间，每层都捕获了其他层遗漏的bug：
- 不同的代码路径绕过了入口验证
- 模拟绕过了业务逻辑检查
- 不同平台上的边缘情况需要环境防护
- 调试日志识别了结构误用
不要只停留在一个验证点。 在每个层次添加检查。