企业官网建设流程全解析

• 文档
• 教程
• 后端

导读

在 Node.js 后端项目中，将API 声明（app）与网络相关配置（server）分离，是 Express 官方生成器（Express generator）引入并被社区广泛认可的一项核心架构实践。本文以nodebestpractices仓库中 separateexpress 章节 为骨架，结合仓库内其他架构与测试实践，系统讲解如何通过app.js+/bin/www的拆分实现进程内测试、提升测试执行速度、获得真实代码覆盖率，并让同一套 API 在多种网络条件下灵活部署。读完本文，你将掌握这一经典拆分模式的完整落地代码、super test 进程内测试写法，以及它与其他最佳实践（组件化分层、配置管理、API 测试）之间的联动关系。

一、为什么要把 app 与 server 拆开

现代 Express 应用最容易被忽视的问题之一，就是把“路由与中间件声明”和“端口监听、HTTP 服务启动”写在同一份文件里。这会让代码出现两类明显的代价：

• 测试被迫走真实网络：一旦app.listen()与路由声明耦合，测试就必须启动真实端口、占用系统资源，执行慢且难以获得准确的覆盖率数据；
• 部署灵活性差：端口、协议、绑定地址等网络参数被硬编码在业务代码中，难以在不同环境（本地、CI、容器、K8s）间移植。

Express 官方生成器给出的解法非常朴素但极其有效：把 API 声明放在app.js，把网络声明放在/bin/www，两者通过require单向依赖。正如该章节所总结的，这样做之后：

• 可以在不执行网络调用的情况下对 API 进行进程内（in-process）测试；
• 测试执行更快，且能顺带获得代码覆盖率指标；
• 同一份 API 可以在灵活、多样的网络条件下部署（换端口、换协议、交给容器平台托管）；
• 额外收益是更好的关注点分离与更清晰的代码结构。

二、API 声明层：app.js 只负责“是什么”

按照该实践，app.js应该只承载 API 的定义与装配，不关心端口和协议。核心代码如下：

var app = express(); app.use(bodyParser.json()); app.use("/api/events", events.API); app.use("/api/forms", forms);

这里的要点是：

1. 创建 Express 实例：app是一个纯函数化的请求处理器，它只描述“收到请求后怎么路由、怎么处理”；
2. 挂载中间件：bodyParser.json()负责解析 JSON 请求体；
3. 挂载子路由：/api/events与/api/forms分别委托给独立的路由模块，体现了仓库中 按业务组件拆分 的思想——路由按业务域组织，而不是按技术角色（controllers、services）堆叠；
4. 不监听端口：app.js文件末尾不应出现app.listen()，这是整个模式成立的关键约束。

从依赖方向看，app.js处于“业务/API 侧”，它只依赖 Express 和业务路由模块；而它本身不应该依赖任何网络层面的细节。这样app对象可以被测试框架直接消费，也可以被任意 server 容器复用。

三、网络声明层：/bin/www 只负责“怎么跑”

/bin/www是 Express 生成器默认的网络启动脚本，它承担所有与网络相关的配置：端口来源、HTTP server 创建与监听。核心代码如下：

var app = require('../app'); var http = require('http'); /** * Get port from environment and store in Express. */ var port = normalizePort(process.env.PORT || '3000'); app.set('port', port); /** * Create HTTP server. */ var server = http.createServer(app);

拆开来看，这段代码完成了三件事：

• 加载 API：require('../app')拿到第二步中装配好的app实例——这是连接两层的唯一纽带；
• 端口解析与注入：通过normalizePort从环境变量PORT读取端口，缺省回退到'3000'，再通过app.set('port', port)写回 Express 配置，端口成为运行时参数而非硬编码；
• 创建 HTTP server：http.createServer(app)把app作为请求处理器交给 Node 原生 HTTP 模块，之后server.listen(port)才真正对外提供服务（原文示例省略了listen调用，实际生成器模板中会紧接着调用）。

这里值得注意的设计信号是：协议也属于网络层。如果你想提供 HTTPS，只需要在/bin/www中改用https.createServer({ key, cert }, app)，app.js一行都不用改。这正是“同一 API 部署在不同网络条件下”的机制基础。仓库的 配置指南 也强调配置应当与环境相关且分层管理，process.env.PORT这种“运行时环境注入”正是其中的典型体现。

四、进程内测试：用 supertest 直接驱动 app

分离的最大红利在测试环节。因为app不监听端口，测试框架可以直接把它当作纯函数请求处理器来调用，从而跳过真实网络、避免端口冲突、让测试毫秒级完成。仓库原文给出了基于 supertest（流行的测试包）的典型写法：

const app = express(); app.get('/user', function(req, res) { res.status(200).json({ name: 'tobi' }); }); request(app) .get('/user') .expect('Content-Type', /json/) .expect('Content-Length', '15') .expect(200) .end(function(err, res) { if (err) throw err; });

这段示例展示了进程内测试的三个关键特征：

1. request(app)而不是request('http://localhost:3000')：直接把 Express 实例传入 supertest，Supertest 内部会为每次请求构造一个短暂的 server，请求结束后自动关闭，因此无需关心端口占用与服务器启停；
2. 链式断言：.expect('Content-Type', /json/)用正则匹配响应头，.expect('Content-Length', '15')精确校验响应体长度（{"name":"tobi"}恰好 15 字节），.expect(200)校验状态码——一个测试内可以叠加多个维度的断言；
3. 回调式完成：.end(function(err, res) { if (err) throw err; })接收最终结果，任何断言失败都会以err形式抛出，从而让测试失败可见。

在生产项目的测试文件里，这里导入的应当是app.js导出的app实例（记得在app.js末尾module.exports = app;），而不是/bin/www——后者会立刻监听端口，违背进程内测试的初衷。这也与仓库中 测试中间件 等章节倡导的“对组件进行快速、隔离的测试”一脉相承：由于无需真实网络，可以低成本地为每个路由、每个中间件、每个业务组件建立单元级测试，进而支撑仓库整体推荐的 API（组件）测试优先 策略。

五、这一模式与仓库其他实践如何协同

app/server分离不是孤立技巧，它与nodebestpractices仓库中多个章节相互支撑：

• 与组件化分层协同：app.js中app.use("/api/events", events.API)式的挂载，前提是路由已被拆分为独立组件，见 按业务组件拆分 与 三层分层；/bin/www则天然属于 web 层的边界之外；
• 与配置管理协同：端口来自process.env.PORT，验证了 环境感知、安全、分层的配置 中“配置由环境注入而非硬编码”的原则；
• 与部署实践协同：当 API 与网络解耦后，Docker 部署只需把npm start（内部执行/bin/www）作为容器入口，端口交给容器编排平台映射，参见 Docker 镜像多阶段构建 与 示例 Dockerfile；
• 与测试体系协同：进程内测试是仓库“至少编写 API 级测试”与“按 AAA 模式组织测试”等实践得以低成本实施的前提之一，相关章节见 sections/testingandquality 目录下的 test-middlewares。

六、落地建议与常见误区

要把这套模式落到现有项目，可参考以下清单：

1. 迁移顺序：先把app.listen()从app.js移除并改为module.exports = app;，再新建/bin/www承载normalizePort+http.createServer+listen，最后把package.json的start脚本指向node ./bin/www；
2. 不要反向依赖：/bin/www依赖app.js是允许的，但app.js绝不应反向require('/bin/www')，否则会形成环并重新引入监听副作用；
3. 保持 app.js 无副作用：任何“启动时立刻执行”的网络动作都应留在/bin/www，这是进程内测试不被破坏的底线；
4. 扩展协议时只改网络层：需要 HTTPS 或自定义 server 行为时，只改动/bin/www，业务代码保持零改动；
5. 测试导入对象要选对：测试文件中require的目标永远是app实例（app.js），而不是启动脚本（/bin/www）。

结语

app与server的分离，是 Express 生态中投入产出比极高的架构决策：它用一次简单的文件拆分，同时换来了快速的进程内测试、真实的覆盖率数据、灵活的网络部署能力和更清晰的职责边界。当这一模式与组件化分层、环境感知配置、容器化部署等实践组合使用时，它将成为 Node.js 后端项目从“能跑”走向“可持续演进、可测试、可移植”的基石。

• 文档
• 教程
• 后端