企业官网建设流程全解析

• 文档
• 教程
• 后端

本指南源自 nodebestpractices 仓库sections/projectstructre/breakintcomponents.french.md（组件化构建解决方案），核心解决"中等规模以上的 Node.js 应用如何避免代码面条（code spaghetti）"这一结构性问题。读完本文，你将掌握以自包含组件（self-contained components）组织项目根目录的方法，理解微服务作为"一组原则"而非"强制规范"的本质，并能结合仓库中分层、Express 边界与 npm 工具封装等配套实践，为未来演进到完整微服务架构铺平道路。

一、为什么中等规模以上的单体应用是糟糕的

原文档开门见山给出结论：对于中等规模及以上的应用，非模块化的单体应用是真正糟糕的（really bad）。一个包含大量依赖的大软件很难被理解，往往会退化成"依赖面条"式的代码。这里的痛点不仅仅是代码体积本身，而是变更的连锁反应：任何一处修改都需要小心翼翼地评估它对其他依赖对象的影响。

即便团队里存在足够聪明、有能力"驯服"这种巨兽并将其"模块化"的架构师，他们也需要在设计上投入巨大的心智成本——每一次变更都必须评估对其他依赖对象的冲击。也就是说，即使能勉强维持模块化，单体架构也让每次迭代背负了不成比例的认知负担。

引用一：Martin Fowler 论"伸缩需要伸缩整个应用"

原文档引用了 Martin Fowler 关于微服务的经典论述，直击单体的三个结构性缺陷：

单体应用也可以成功，但随着越来越多应用部署到云端，人们对它的挫败感与日俱增。变更周期被捆绑在一起——对应用一小部分做出的修改，需要重建并重新部署整个单体；随着时间推移，往往很难保持良好的模块化结构，本应只影响某个模块的改动越来越难以被限制在该模块内部；伸缩需要扩展整个应用，而不是其中需要更多资源的那些部分，因此需要消耗更多资源。

这段引述点明了单体在云原生环境下的致命伤：无法按需伸缩、无法隔离变更、模块边界随时间腐化。

引用二：Uncle Bob 的"Screaming Architecture（尖叫式架构）"

原文档还引用了 Uncle Bob 的著名比喻：

如果你走进一座图书馆的建筑，你很可能会看到宏伟的入口、办理借阅手续的区域、阅读区、小型会议室，以及一排排容纳所有藏书的书架。这座建筑本身就在"尖叫"：这是图书馆。

把这个比喻应用到工程上，问题就变成：当你查看应用顶层目录结构和顶层包中的源文件时，它们在"尖叫"什么？是"医疗系统""会计系统""库存管理系统"这样的业务语义，还是 "Rails""Spring/Hibernate""ASP" 这样的技术栈语义？

如果一个项目的目录结构只能让人看到技术框架、却看不出任何业务领域，那么它的架构就没有"尖叫"出它本应表达的领域信息。这正是"按技术角色分组文件"这一反面模式的语言学症状。

二、核心思想：微服务是一套原则，而非强制规范

原文档特别澄清了一个常见的认知误区：微服务不是一份你必须严格遵循的规范（spec），而是一组原则（a set of principles）。

你可以把许多原则落地为完整的微服务架构，也可以只采纳其中少数几条。只要软件整体复杂度保持在低位，两种做法都是好的。这一论述非常关键，它把"是否拆分"从二元对立的教条，还原为"以复杂度控制为目标"的工程权衡。

据此，原文档给出**最低限度（the very least）**的组件化要求：

1. 在组件之间建立基本的边界（borders）；
2. 为每个业务组件在项目根目录分配一个文件夹；
3. 让组件自包含——其他组件只能通过它的公共接口或 API 消费其功能。

这三点是让组件保持简单、避免"依赖地狱"（dependency hell）的基石，也是应用成长后平滑演进为完整微服务架构的起跑线。

三、推荐做法：以自包含组件构建解决方案

原文档（对照 英文原版）给出了完整的推荐目录结构示例：

my-system ├─ apps (components) │ ├─ orders │ │ ├─ package.json │ │ ├─ api │ │ ├─ domain │ │ ├─>my-system ├─ controllers │ ├─ user-controller.js │ ├─ order-controller.js │ ├─ payment-controller.js ├─ services │ ├─ user-service.js │ ├─ order-service.js │ ├─ payment-service.js ├─ models │ ├─ user-model.js │ ├─ order-model.js │ ├─ payment-model.js

这种结构的问题在于：它按技术层次而非业务领域切分文件。以 user 业务为例，其controller、service、model被拆散到三个不同的顶层目录中，代码库里根本找不到一个"user 组件"的完整载体。后果是：

• 新增或修改一个业务功能，需要在多个目录之间来回跳转，心智模型被割裂；
• 组件之间没有边界，任何模块都可以随意引用其他模块的内部文件，依赖呈网状蔓延；
• 顶层目录"尖叫"的是 controller/service/model 这种技术词汇，而不是业务领域，架构语义完全被遮蔽。

按技术角色分组的解决方案目录结构

五、组件内部如何落地：三层划分（entry-points / domain />my-system ├─ apps (components) │ ├─ component-a │ │ ├─ entry-points │ │ │ ├─ api # 控制器放在这里 │ │ │ ├─ message-queue # 消息消费者放在这里 │ │ ├─ domain # 功能与流程：DTO、服务、业务逻辑 │ │ ├─>// app.js / app.ts：API 声明放在这里 const app = express(); app.use(bodyParser.json()); app.use('/api/events', events.API); app.use('/api/forms', forms);

// /bin/www：网络层声明放在这里 const app = require('../app'); const http = require('http'); // 从环境获取端口并存入 Express const port = normalizePort(process.env.PORT || '3000'); app.set('port', port); // 创建 HTTP 服务器 const server = http.createServer(app);

这种"业务组件自包含 + Web 框架边界受限"的组合，正是 README.md 中 "Layer your app, keep Express within its boundaries"（🔗 Read More）所强调的：Express 只是 entry-points 层中的一个适配器，而不是整个应用的骨架。

七、配套实践二：通用工具以 npm 包方式共享

组件自包含并不意味着代码 100% 零共享。当应用成长、不同服务器上的多个组件都要消费相似工具时，依赖管理就成了新问题。仓库文档 wraputilities.french.md（英文版）给出了答案：先用你自己的代码包装第三方工具包，使其未来易于替换，然后把自己的工具代码发布为私有 npm 包。这样，整个代码库都可以通过 import 引用这份代码，免费获得 npm 自带的依赖管理能力。

发布私有 npm 包而不公开共享的方式包括：npm 私有模块（private modules）、私有 registry，或本地 npm 包（local npm packages）。这与原文档中libraries目录的定位一脉相承——通用能力通过包边界隔离，业务能力通过组件边界隔离。

八、落地清单：从这篇文章可以直接带走什么

综合原文档与仓库配套文档，落地组件化时可以遵循以下检查清单：

1. 根目录按业务领域建文件夹：apps/下每个业务组件（orders、users、payments）自包含，拥有独立的api、domain、data-access与package.json；
2. 组件只通过公共接口被消费：禁止跨组件直接引用内部文件，否则边界形同虚设；
3. 组件内部强制三层结构：entry-points 只做适配，domain 只处理与协议无关的业务逻辑，data-access 只负责数据库交互并暴露 repository 接口；
4. Express 只是入口适配器：API 声明与网络配置分离，让测试可以在进程内完成；
5. 通用工具走 npm 包路径：把跨组件的 logger、authenticator 等包装为私有 npm 包，而不是散落在共享文件夹里；
6. 让架构"尖叫"业务：顶层目录结构应该让人一眼看出这是医疗系统、会计系统还是库存系统，而不是 Rails/Express 这类技术框架。

这些实践共同服务于原文档那句核心主张：保持组件简单，避免依赖地狱，为应用成长后的完整微服务架构铺平道路。当你的 Node.js 应用规模还在中等以上、又不想立刻全面微服务化时，先在项目根目录划出组件边界，就是性价比最高的第一步。

延伸阅读：仓库 sections/projectstructre 目录下还收录了 配置管理最佳实践、框架选型（choose-framework） 与 TypeScript 考量（typescript-considerations），可作为组件化落地时的配套参考。

• 文档
• 教程
• 后端