用途:Screaming Architecture(“会喊叫的架构”)主张项目顶层结构应体现业务领域,而非框架或技术分层。文件夹名对应业务能力与用例,而不是 controllers、models、services 这类技术角色。该理念由 Robert C. Martin 提出:架构应告诉读者系统是什么,而不是用了哪些框架。
主要能力与要求:
- 领域优先的根结构:顶层目录命名业务能力,如 orders/、users/、payments/,而非按技术层划分。
- 功能自包含:每个领域模块自带模型、服务、路由与测试,例如 orders/ 下含 order.entity.ts、order.service.ts、order.routes.ts、order.test.ts。
- 前端同样适用:React 项目按 features/orders/ 组织,组件用 PascalCase 无后缀,业务逻辑用 use 前缀 hooks,状态用 store/slice,数据请求用 Api 后缀,类型与功能同置;跨功能导入必须经过该功能的 index.ts,shared/ui/ 放通用设计系统组件,app/ 只放路由与 providers。
- 框架在边缘:框架相关代码位于最外层,领域核心不导入框架。例如 order.entity.ts 保持纯领域,Express 只出现在 order.routes.ts。
- 共享内核:真正跨领域的关注点放入 shared/ 或 infrastructure/,如 database、logger、config、errors。
禁止事项:根目录按技术角色分层;建立无领域上下文的 utils/ 或 helpers/ 大杂烩。
使用方式与决策:新项目从领域优先开始,每个业务能力一个文件夹;已有技术分层项目应增量重构,一次迁移一个功能,避免大爆炸式重写;功能超过 15–20 个时按子域分组,如 catalog/、fulfillment/、identity/;monorepo 用 packages/orders/ 等,每个包自包含。判断两个概念是否同模块:它们是否因同一业务原因一起变化。
适用场景:新项目或服务起步;围绕框架惯例膨胀后的代码库重构;多人难以定位业务概念位置;目录结构读起来像“Express 应用”或“MVC 项目”而非实际领域。
限制与不适用:非常小的脚本或工具、整个领域只有一个概念的项目,分区无收益。框架惯例可能冲突:NestJS 默认按功能分模块较契合;Express、Fastify 无约定需显式应用;Next.js 的 app/ 按 URL 路径路由,领域逻辑应放在 src/domain/ 或 src/features/ 与路由层分离。若两个功能共享概念(如 Money),应放入 shared/domain/ 或 kernel/,而非 utils/。
其他资料:clean-architecture 提供分层规则(与 screaming arch 正交);domain-driven-design 的限界上下文映射顶层模块;hexagonal-architecture 的端口与适配器体现框架在边缘。具体安装命令、收费与平台信息暂未提供。