Dependency Map

依赖关系分析（Dependency Map）

代码改动最怕的不是改错，而是不知道改动波及到了哪里。 本 skill 的使命：在改动之前，画出影响面地图。

第一步：确定分析目标

用 AskUserQuestion 确认：

• 分析什么：哪个函数/类/模块/文件？
• 为什么分析：准备改什么？删什么？还是纯了解？
• 分析深度：只看直接依赖，还是追踪到底？

分析请求
  │
  ├─ 改函数签名 → 追踪所有调用方
  ├─ 改数据结构 → 追踪数据的读写点
  ├─ 删文件/模块 → 追踪所有 import
  ├─ 改 API 接口 → 追踪前端调用 + 外部消费方
  └─ 改配置/环境变量 → 追踪所有引用点

第二步：静态依赖分析

2.1 Import/Require 分析

# 找到谁引用了目标文件
grep -r "import.*from.*'目标模块'" src/
grep -r "require('目标模块')" src/

# 或用 Grep 工具搜索

输出格式：

## 引用关系

### 被谁引用（上游，改目标会影响他们）
- `src/api/auth.ts:3` — import { login } from './services/auth'
- `src/api/user.ts:5` — import { validateToken } from './services/auth'
- `tests/auth.test.ts:1` — import { login, logout } from '../services/auth'

### 引用了谁（下游，目标依赖他们）
- `src/models/user.ts` — UserModel
- `src/utils/jwt.ts` — signToken, verifyToken
- `bcrypt` — 外部依赖

2.2 函数/方法级调用链

对于函数级分析，追踪更精细的调用关系：

# 搜索函数名的所有调用
grep -rn "目标函数名(" src/ --include="*.ts" --include="*.js"

输出格式：

## 调用链：validateToken()

定义：src/services/auth.ts:45

调用方：
├─ src/middleware/auth.ts:12 — authMiddleware() 每个请求都会调用
│   └─ 被 src/api/index.ts:8 的 app.use(authMiddleware) 注册为全局中间件
├─ src/api/user.ts:23 — getUserProfile() 手动调用做额外校验
└─ tests/auth.test.ts:34 — 测试用例

影响面评估：
- authMiddleware 是全局中间件 → 改签名会影响所有需要认证的接口
- 测试需要同步更新

第三步：数据流分析

当改动涉及数据结构时，追踪数据从哪来、到哪去：

3.1 数据结构变更

## 数据流：User 类型

### 定义位置
`src/types/user.ts:5` — interface User { id, name, email, role }

### 创建点（写入）
- `src/services/user.ts:createUser()` — 注册时创建
- `src/services/auth.ts:oauthCallback()` — OAuth 登录时创建

### 读取点
- `src/api/user.ts:getUserProfile()` — 返回给前端
- `src/middleware/auth.ts:12` — 从 token 解析出 user
- `src/services/order.ts:45` — 创建订单时读取 user.id

### 持久化
- `src/models/user.ts` — 数据库 users 表
- `src/utils/cache.ts:getUserCache()` — Redis 缓存

### 影响评估
如果给 User 加字段：
- 数据库需要 migration
- 缓存的序列化/反序列化需要兼容
- API 响应自动包含（如果没有字段过滤的话）

如果删 User 字段：
- 检查所有读取点是否还在用
- 前端是否依赖这个字段

第四步：输出影响面评估

4.1 影响面清单

## 影响面评估：<改动描述>

### 直接影响（必须改）
| 文件 | 行号 | 影响原因 | 改动类型 |
|------|------|---------|---------|
| src/api/auth.ts | 23 | 调用了要修改的函数 | 同步更新参数 |
| src/middleware/auth.ts | 12 | 依赖返回值结构 | 适配新结构 |

### 间接影响（需要验证）
| 文件 | 行号 | 风险点 | 验证方式 |
|------|------|--------|---------|
| src/api/user.ts | 45 | 使用了相同的类型 | 跑测试确认 |

### 不受影响（确认安全）
- src/services/order.ts — 虽然在同目录，但无依赖关系
- src/utils/format.ts — 纯工具函数，不涉及

### 测试影响
- tests/auth.test.ts — 需要更新测试用例
- tests/user.test.ts — 需要回归验证

4.2 风险等级

分析准则

• 宁多不漏：不确定的归入"需要验证"，不要归入"不受影响"
• 标注行号：每个影响点必须标注具体位置，方便定位
• 区分直接/间接：直接影响必须改，间接影响需验证，不要混在一起
• 关注隐式依赖：不只看 import，还要看运行时依赖（事件监听、全局状态、环境变量）
• 递归但有界：追踪调用链要有深度限制，一般追 3 层足够。超过 3 层的间接影响可忽略

与其他 skill 的关系

code-walkthrough（理解代码）→ dependency-map（评估影响）→ refactoring（执行改动）

dependency-map vs code-walkthrough：

• walkthrough：理解代码。"这段代码是什么，怎么运转"
• dependency-map：评估影响。"改这里会动到哪里"
• 通常先 walkthrough 建立理解，再 dependency-map 评估改动