架构文档
从代码库生成架构文档（图 + 数据流 + 决策）。
文档与重构高级
为什么
GitHub 2024 调查发现 81% 的开发者预期 AI 工具未来一年在代码文档中更深度集成，为所有工作流中最高。含图、数据流与关键决策的架构文档快速上手并保留意图。
从代码库（入口、边界、数据流）生成保持其接地，非理想化。
何时使用
上手慢或架构未文档化时用。大变更时刷新。
如何做
1. 识别入口（main、路由、worker）。
2. 映射模块边界与依赖。
3. 追踪主用例数据流。
4. 提示："架构文档：图（mermaid）、数据流、关键决策、边界"。
5. 将文档加到 /docs；从 README 引用。
示例
```mermaid
flowchart LR
Client --> Router[API 路由]
Router --> Auth[中间件/认证]
Router --> Books[api/books]
Books --> DB[(Postgres)]
Books --> Cache[(Redis)]
```
数据流：请求 → 认证 → 路由 → zod 验证 → 服务 → DB → 响应。
关键决策：zod 验证；Redis 限流；无 ORM（经 pg 原生 SQL）。
常见问题
- ⚠重构后 Error: Cannot find module 'xxx' → 重跑 `npm install` 和 `npx tsc --noEmit`；重构常丢或重命名 import。
- ⚠错误：重构后 "Cannot read properties of undefined" → 跑测试套件（`npm test`）捕获行为变更；重构须保持行为。
- ⚠错误：文档漂移：示例无法运行 → 在 CI 执行示例（`npm run docs:check`）；被测示例不会漂移。
最佳实践
- ✓从真实入口与边界生成图。
- ✓在 ADR 关联章节文档关键决策（为何，非仅什么）。
- ✓用具体指标衡量结果（节省时间、缺陷率、测试覆盖率），使实践可被论证和改进。
常见问题解答
什么是架构文档？
从代码库生成架构文档（图 + 数据流 + 决策）。 它可帮助开发者快速理解 架构文档 的核心价值与适用场景。
如何开始使用架构文档？
开始使用 架构文档，建议先掌握以下要点：识别入口（main、路由、worker）。
架构文档 的常见误区有哪些？
使用 架构文档 时常遇到的问题包括：重构后 Error: Cannot find module 'xxx' → 重跑 `npm install` 和 `npx tsc --noEmit`；重构常丢或重命名 import。；错误：重构后 "Cannot read properties of undefined" → 跑测试套件（`npm test`）捕获行为变更；重构须保持行为。；错误：文档漂移：示例无法运行 → 在 CI 执行示例（`npm run docs:check`）；被测示例不会漂移。。
架构文档 的最佳实践是什么？
架构文档 的最佳实践包括：从真实入口与边界生成图。；在 ADR 关联章节文档关键决策（为何，非仅什么）。；用具体指标衡量结果（节省时间、缺陷率、测试覆盖率），使实践可被论证和改进。。
如何深入学习架构文档？
从官方文档入手，再在 GitHub 上搜索真实示例；先在小实验仓库验证模式，再应用到生产代码。