微服务项目结构与搭建

使用 Express 搭建用户、订单、库存和模拟支付四个独立服务,理解项目结构和公共代码边界,并验证各服务能够独立运行。

🎯 引言

上一篇已经决定把商城划分为用户、订单、库存和模拟支付四个服务。现在需要把这些职责落实为可以运行的项目:每个服务有自己的入口和启动命令,一个服务停止时,不会把其他进程一起关闭。 本篇搭建后续课程持续使用的项目骨架,并说明公共代码应该放在哪里。你已经学过 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}`);
});

四个服务都使用 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 服务是否真的可以独立运行:

  1. 分别启动用户、订单、库存和模拟支付服务。
  2. 依次请求四个服务的 /health 接口,确认返回的 service 名称正确。
  3. 停止订单服务,再次访问订单服务和库存服务的 /health 接口。
  4. 重新启动订单服务,确认它能恢复响应。

验收标准: 四个服务均可单独启动;停止订单服务后,其接口无法访问,但库存服务仍可正常响应;重新启动订单服务后,接口恢复正常。


🎉 恭喜你完成本篇学习!现在你已经有了四个能够分别启动的 Express 服务,下一篇将让它们真正开始协作。