structure-modularity

Lens C —— 结构与依赖

目录结构是架构的外在表现。这一 lens 必须配合实际的依赖图/环检测（用工具跑，别凭空想象）。

9. 目录结构 (Directory Structure)

**检查项：**

• [ ] 目录结构是否反映架构意图
• [ ] 目录划分依据是否一致（按功能/按层次/按领域）
• [ ] 目录深度是否合理（不超过 4-5 层）
• [ ] 目录命名是否清晰表达职责

**常见组织模式：**

按层次组织（技术视角）：          按领域组织（业务视角）- 推荐：     按功能组织（特性视角）：
├── controllers/                  ├── order/                        ├── features/
├── services/                     │   ├── order.entity.ts           │   ├── checkout/
├── repositories/                 │   ├── order.service.ts          │   ├── user-profile/
├── models/                       │   └── order.repository.ts       │   └── search/
└── utils/                        ├── payment/                      └── core/
                                  └── shared/

**违规模式：**

• 目录结构与代码依赖关系矛盾
• 同一目录下文件职责差异大
• `utils/`、`helpers/`、`common/` 成为垃圾堆
• 目录过深或过浅

10. 模块化 (Modularity)

**检查项：**

• [ ] 模块边界是否清晰
• [ ] 模块职责是否单一
• [ ] 模块接口是否明确（导出了什么）
• [ ] 模块间通信是否规范
• [ ] 模块是否可独立理解和测试

**模块健康度指标：** | 指标 | 理想值 | 警告值 | |-----|-------|-------| | 模块内文件数 | 3-10 | > 20 | | 模块对外导出 | 1-5 个 | > 10 个 | | 模块依赖数 | ≤ 5 | > 10 | | 循环依赖 | 0 | > 0 |

**违规模式：**

• 模块间存在循环依赖
• 模块内部结构暴露给外部
• 模块过大（> 20 文件）或过小（1 文件）
• 模块间通过共享状态通信

11. 依赖方向 (Dependency Direction)

**核心原则：依赖指向稳定。**

稳定性排序（从稳定到不稳定）：        依赖方向：不稳定 → 稳定
1. 领域模型（最稳定）
2. 领域服务
3. 应用服务
4. 基础设施
5. UI/API（最不稳定）

**检查项：**

• [ ] 依赖是否指向更稳定的模块
• [ ] 核心领域是否零外部依赖
• [ ] 基础设施是否可替换
• [ ] 是否遵循依赖倒置

> 置信度提示：**确凿的循环依赖**（工具验证过、能画出环）是 100 分必报；"这个依赖方向理论上可以更优雅"但无实际危害是 ≤25 分，不报。