微服务项目结构与搭建
🎯 引言
上一篇已经决定把商城划分为用户、订单、库存和模拟支付四个服务。现在需要把这些职责落实为可以运行的项目:每个服务有自己的入口和启动命令,一个服务停止时,不会把其他进程一起关闭。 本篇搭建后续课程持续使用的项目骨架,并说明公共代码应该放在哪里。你已经学过 Node.js 和 HTTP,这里不重复讲解路由或框架基础。
🧱 微服务项目应该怎样组织
这次把四个服务放在同一个 Git 仓库中,方便学习时统一管理。这种组织方式叫 Monorepo(单仓库)。它只说明代码存放在哪里,不规定服务必须一起启动或一起发布。
microservices/
├── services/
│ ├── users/
│ │ ├── package.json
│ │ └── src/
│ │ └── app.mjs
│ ├── orders/
│ │ ├── package.json
│ │ └── src/
│ │ └── app.mjs
│ ├── inventory/
│ │ ├── package.json
│ │ └── src/
│ │ └── app.mjs
│ └── payments/
│ ├── package.json
│ └── src/
│ └── app.mjs
└── README.md
这里的目录各有用途:
services/:集中存放不同的业务服务。- 每个服务自己的
package.json:保存服务名称、Express 依赖和启动命令。 src/app.mjs:服务的程序入口。后续可以在各自的src/中添加业务文件,不必提前建立复杂目录。
🛠 创建四个独立服务
以下命令适用于 macOS 或 Linux 终端。示例使用 Node.js 22.x、Express 5.1.0,采用 ESM 模块,不重新讲解 Express 的路由基础。
1. 创建目录
mkdir -p microservices/services/{users,orders,inventory,payments}/src
cd microservices
2. 为每个服务建立独立的 Node.js 项目
先在 services/users/package.json 写入:
{
"name": "users-service",
"private": true,
"type": "module",
"scripts": {
"start": "node src/app.mjs"
},
"dependencies": {
"express": "5.1.0"
}
}
其他三个服务使用相同结构,只需将 name 分别改为 orders-service、inventory-service、payments-service。这样每个服务都能分别管理依赖与启动命令。
分别为四个服务安装依赖。以下命令均在 microservices/ 项目根目录执行,每一条只安装对应服务 package.json 中声明的依赖:
npm install --prefix services/users
npm install --prefix services/orders
npm install --prefix services/inventory
npm install --prefix services/payments
如果你已进入某个服务目录,也可以直接执行 npm install;无需在项目根目录重复安装 Express。
安装后,每个服务会产生自己的 package-lock.json 和 node_modules/。项目提交到 Git 时应保留锁文件,并在根目录的 .gitignore 中写入 node_modules/,避免提交依赖目录。运行 npm install 需要能够访问 npm 软件包仓库。
3. 编写 Express 服务入口
下面分别创建四个服务的 src/app.mjs。使用标签页切换查看并将完整代码写入对应文件;无需复制文件后再手动修改。
services/users/src/app.mjs:
import express from 'express';
const app = express();
const serviceName = 'users';
const port = 3001;
app.get('/health', (req, res) => {
res.json({ service: serviceName, status: 'ok' });
});
app.listen(port, () => {
console.log(`${serviceName} listening on ${port}`);
});
services/orders/src/app.mjs:
import express from 'express';
const app = express();
const serviceName = 'orders';
const port = 3002;
app.get('/health', (req, res) => {
res.json({ service: serviceName, status: 'ok' });
});
app.listen(port, () => {
console.log(`${serviceName} listening on ${port}`);
});
services/inventory/src/app.mjs:
import express from 'express';
const app = express();
const serviceName = 'inventory';
const port = 3003;
app.get('/health', (req, res) => {
res.json({ service: serviceName, status: 'ok' });
});
app.listen(port, () => {
console.log(`${serviceName} listening on ${port}`);
});
services/payments/src/app.mjs:
import express from 'express';
const app = express();
const serviceName = 'payments';
const port = 3004;
app.get('/health', (req, res) => {
res.json({ service: serviceName, status: 'ok' });
});
app.listen(port, () => {
console.log(`${serviceName} listening on ${port}`);
});
四个服务都使用 Express 提供 /health 接口,方便检查服务是否能正常响应。这个接口目前只验证 HTTP 入口可访问,不能证明数据库、消息队列等依赖正常。本篇只创建服务入口,尚未实现服务间请求;订单服务如何调用库存服务,会在下一篇讲解。
⚙️ 保持服务各自独立
四个服务分别拥有自己的 package.json、src/app.mjs 和监听端口。即使它们位于同一个仓库,修改订单服务的代码,也不需要修改其他三个服务的入口文件。
| 服务 | 监听端口 | 负责的业务 |
|---|---|---|
| 用户服务 | 3001 | 用户资料与账号状态 |
| 订单服务 | 3002 | 创建订单与维护订单状态 |
| 库存服务 | 3003 | 库存查询、预留与释放 |
| 模拟支付服务 | 3004 | 记录模拟支付结果 |
本地学习时先使用固定端口,便于启动和验证。每个服务以后都可以扩展自己的业务文件和依赖,而不要求其他服务使用完全相同的项目结构。
🧩 公共代码应该怎样管理
四个服务放在同一个仓库,很容易想把重复代码全部提取出来。但代码放在一起,不代表业务规则应该共用。
例如,日期格式化函数只是把时间转换成统一格式,几个服务共享它通常问题不大。可是“订单是否允许取消”取决于订单业务状态,应由订单服务决定。如果库存服务直接导入订单服务内部的取消判断函数,以后订单规则一改,库存服务也可能被迫修改或重新发布。
| 可以考虑共享 | 不应该直接共享 |
|---|---|
| 稳定的日期格式化工具 | 订单服务内部的订单状态判断逻辑 |
| 不含业务规则的通用日志格式 | 库存服务内部的库存 SQL 操作 |
| 稳定的通用工具函数 | 支付服务内部的支付状态变更逻辑 |
本篇不需要建立公共工具包。只有在多个服务真正重复使用一项稳定、通用的能力时,再考虑提取为独立包。服务间需要的业务能力应通过约定好的接口或事件提供,而不是直接导入对方的内部业务文件。
✅ 启动并验证服务独立性
分别打开四个终端。所有命令都从 microservices/ 项目根目录执行:
npm start --prefix services/users
npm start --prefix services/orders
npm start --prefix services/inventory
npm start --prefix services/payments
每条命令放在不同终端运行,终端工作目录均为
microservices/。
再打开第五个终端,检查四个 Express 服务:
curl http://localhost:3001/health
curl http://localhost:3002/health
curl http://localhost:3003/health
curl http://localhost:3004/health
应依次看到类似结果(每条命令返回一行):
{"service":"users","status":"ok"}
另外三个响应的 service 分别为 orders、inventory、payments。
最后,在运行订单服务的终端按 Ctrl + C 停止它。再次访问:
curl http://localhost:3002/health
curl http://localhost:3003/health
此时订单服务应连接失败,但库存服务仍会返回正常结果。这证明它们是独立运行的进程。它尚不能证明真实业务在依赖服务故障时也能正常工作;后面讨论超时、重试与容错时,才会解决那个问题。
❓ 知识问答
Q1:一个仓库中的服务,能分别部署吗?
可以。Git 仓库决定代码如何管理,部署则取决于服务是否有独立构建、配置和发布的能力。本篇先建立独立运行的基础。
Q2:每个服务都必须有自己的 package.json 吗?
不是硬性要求。单仓库也可以通过工作区统一管理依赖。本课程让每个服务有独立的 package.json,是为了让 Express 依赖、服务边界和启动方式更直观。
Q3:为什么不直接把订单服务需要的库存函数 import 进来?
因为那样会让订单服务依赖库存服务的内部实现。库存规则变化可能同时影响两个项目;通过库存服务对外提供的接口协作,更容易保持职责边界。
🧪 小练习
请验证四个 Express 服务是否真的可以独立运行:
- 分别启动用户、订单、库存和模拟支付服务。
- 依次请求四个服务的
/health接口,确认返回的service名称正确。 - 停止订单服务,再次访问订单服务和库存服务的
/health接口。 - 重新启动订单服务,确认它能恢复响应。
验收标准: 四个服务均可单独启动;停止订单服务后,其接口无法访问,但库存服务仍可正常响应;重新启动订单服务后,接口恢复正常。
🎉 恭喜你完成本篇学习!现在你已经有了四个能够分别启动的 Express 服务,下一篇将让它们真正开始协作。
