Skip to content

dependency-management.md

Latest commit

 

History

History
192 lines (155 loc) · 5.65 KB

dependency-management.md

File metadata and controls

192 lines (155 loc) · 5.65 KB
Raw

依赖与供应链管理

目的

规范项目依赖的引入、更新、审计和移除流程，确保依赖安全、可控、可维护，避免"依赖地狱"和供应链攻击风险。

适用时机

  • 引入新的第三方依赖时
  • 定期更新依赖版本时（每周/每月）
  • 收到安全漏洞通知时
  • 依赖出现破坏性变更时
  • 项目初始化确定技术栈时
  • 清理无用/冗余依赖时

流程步骤

第一部分：依赖引入评估

引入前必须回答：

  1. 这个功能自己实现需要多少时间？（< 2 小时考虑自研）
  2. 这个库的维护状态如何？（最近更新时间、Issue 响应速度）
  3. 社区活跃度？（Star/Fork/Contributor 数量）
  4. 许可证是否兼容？（MIT/Apache 2.0 通常安全）
  5. 包大小和依赖树深度？
  6. 是否有已知安全漏洞？

评估清单：

## 依赖评估：[包名]

- 用途：[解决什么问题]
- 替代方案：[还考虑了哪些]
- 自研成本：[估算时间]
- 维护状态：[最近 commit / release 时间]
- 社区规模：[Star / 周下载量]
- 许可证：[MIT / Apache / GPL / ...]
- 包大小：[安装后大小]
- 依赖数量：[直接 + 间接依赖数]
- 安全审计：[有无已知漏洞]
- 结论：引入 / 不引入 / 观望

第二部分：版本管理策略

语义化版本（SemVer）：

  • MAJOR.MINOR.PATCH
  • MAJOR：不兼容的 API 变更
  • MINOR：向后兼容的功能新增
  • PATCH：向后兼容的 Bug 修复

锁定策略：

依赖类型 锁定方式 说明
生产依赖 精确锁定（lock 文件） 确保一致性
开发依赖 精确锁定（lock 文件） 确保环境一致
间接依赖 由 lock 文件管理 不手动修改

版本范围规则：

  • 生产项目：使用 lock 文件锁定精确版本
  • 新项目/原型：可用 ^（兼容更新）
  • 永远不要在生产依赖中使用 * 或 latest

第三部分：依赖更新

更新频率：

类型 频率 方式
安全补丁 立即 收到通知即更新
PATCH 更新 每周 批量更新
MINOR 更新 每两周 逐个评估
MAJOR 更新 按需 单独分支、充分测试

更新流程：

1. 创建更新分支：git checkout -b deps/update-xxx
2. 更新依赖版本
3. 运行完整测试套件
4. 检查 CHANGELOG 中的 Breaking Changes
5. 必要时修改代码适配
6. 本地验证功能正常
7. 提交并推送（触发 CI）
8. CI 通过后合并

批量更新工具：

  • Dependabot（GitHub 内置）
  • Renovate（更灵活）
  • npm-check-updates / pip list --outdated

第四部分：安全审计

定期审计：

# Node.js
npm audit
npm audit fix

# Python
pip-audit
safety check

# 通用
# GitHub Security Alerts（自动）

审计频率：

  • 自动化：每次 CI 运行（GitHub Dependabot Alerts）
  • 手动：每月一次全面审计
  • 紧急：收到 CVE 通知立即处理

漏洞响应：

严重度 响应时间 处理方式
Critical 24 小时内 立即更新或临时移除
High 3 天内 尽快更新
Medium 1 周内 排入更新计划
Low 下次更新周期 记录跟踪

第五部分：依赖清理

清理信号：

  • 代码中已不再 import/require
  • 被更好的替代方案取代
  • 已停止维护（> 1 年无更新）
  • 功能已被语言/框架原生支持

清理流程：

  1. 使用工具检测未使用依赖
  2. 确认确实无引用（包括配置文件、脚本）
  3. 移除依赖
  4. 运行测试确认无影响
  5. 更新文档

第六部分：供应链安全

防护措施：

  • 始终使用 lock 文件（package-lock.json / poetry.lock）
  • CI 中使用 npm ci（而非 npm install）
  • 启用 GitHub Dependabot / Security Alerts
  • 不随意升级未经审查的依赖
  • 注意 typosquatting（包名仿冒）
  • 私有包使用 scope（@myorg/package）
  • 定期审查 lock 文件变更

红旗信号（可能恶意包）：

  • 包名与知名包极度相似（差一个字符）
  • 下载量极低但突然暴增
  • 安装脚本执行可疑操作
  • 维护者突然变更
  • 版本跳跃异常（1.0.0 → 99.0.0）

检查清单

  • 新依赖引入有评估记录
  • 使用 lock 文件锁定版本
  • CI 中启用了安全审计
  • Dependabot/Renovate 已配置
  • 每月进行一次依赖审计
  • 安全漏洞有响应 SLA
  • 无用依赖定期清理
  • MAJOR 更新有单独分支和测试
  • 许可证兼容性已确认
  • 了解供应链攻击防护 basics

输出物

输出物 格式 存放位置
依赖评估记录 Markdown docs/dependency-eval/
更新日志 Git commit 版本控制
安全审计报告 文本/JSON CI 输出 / docs/security/
依赖清单 lock 文件 项目根目录

常见误区

误区 正确做法
永远不更新依赖 定期更新，避免积累太多 Breaking Changes
一有更新就立即升级 区分安全补丁和功能更新，分级处理
不锁版本 必须使用 lock 文件
引入依赖不评估 先评估再引入，避免依赖膨胀
忽略安全告警 建立响应机制，Critical 24h 内处理
只关注直接依赖 间接依赖同样需要审计

相关文档