统一 API 入口与请求转发
🎯 引言
前面我们把用户、商品和订单拆成了独立运行的服务,并通过 BFF 为订单详情页组合数据。现在,订单详情由 BFF(4000 端口)提供,创建订单由订单服务(4003 端口)负责。
为什么前端要知道这些内部端口? 如果订单服务以后换了地址,难道每个前端都得修改配置吗?
其实不需要。我们可以让前端只访问一个固定地址,再由统一 API 入口把请求送到正确的服务。本篇重点讲清楚这一层在架构中的作用和请求转发过程,并使用你在 Nginx 课程中学过的反向代理完成验证,不再重复讲解 Nginx 指令,也不额外编写 Node.js 转发程序。
⚠️ 为什么需要统一 API 入口
在目前的课程项目里,前端如果直接访问内部服务,就可能这样调用:
查询订单详情:GET http://127.0.0.1:4000/bff/orders/o1
创建订单: POST http://127.0.0.1:4003/orders
这里的两个端口不同,是因为 BFF 和订单服务是两个独立的进程,并不是因为“查询订单”和“创建订单”必须使用不同端口。订单服务本身也提供 GET /orders/:id;只是页面需要用户名、商品名称等组合数据,所以订单详情页调用了 BFF。
如果让前端直接连接多个内部服务,就会出现几个问题:
- 前端需要维护多个服务地址。
- 内部服务迁移端口或服务器时,可能需要修改前端配置。
- 不同客户端可能重复管理这些访问地址。
增加统一入口后,前端只访问 8080:
查询订单详情:GET http://127.0.0.1:8080/bff/orders/o1
创建订单: POST http://127.0.0.1:8080/api/orders
前端依赖的是稳定的公共地址和接口路径,而不再是每个服务的内部地址。 即使订单服务以后搬到另一台机器,只要公共路径保持不变,前端的调用方式就不需要跟着改变。
🧱 统一 API 入口是什么,位于哪里
统一 API 入口不是某个特定的 Node.js 框架或插件,而是系统对外接收 API 请求的统一访问位置。
在本课程中,可以由 Nginx 担任这个角色:它接收前端请求,根据路径选择目标服务,并将服务返回的响应交还给前端。
正在加载流程图…
四个分支代表不同的转发目标。每次请求只会根据路径转发到对应的一个服务,不是同时调用四个服务。 至于 BFF 怎样查询和聚合业务数据,前面的文章已经讲过,这里不再画进流程图。
🔀 一个请求是怎样转发到目标服务的
以创建订单为例,前端发送:
POST /api/orders
Content-Type: application/json
{"userId":"u1","productId":"p1","quantity":1}
整个过程可以分为四步:
- 接收请求:统一入口在
8080端口收到POST /api/orders。 - 匹配路由:根据事先约定的路径规则,确定目标是
4003端口的订单服务,并将公共路径/api/orders映射为内部路径/orders。 - 转发并处理:入口将请求交给订单服务。订单服务按照上一篇的逻辑查询用户和商品,计算金额并创建订单。
- 返回响应:订单服务返回
201和订单 JSON,入口再将响应返回前端。
正在加载流程图…
注意:入口只决定请求交给谁,不负责创建订单或计算订单金额。 业务逻辑仍由订单服务执行。
我们可以用一张表整理本例的路由约定:
| 前端访问路径 | 内部目标服务 | 内部实际路径示例 |
|---|---|---|
/api/users/u1 | 用户服务 4001 | /users/u1 |
/api/products/p1 | 商品服务 4002 | /products/p1 |
/api/orders | 订单服务 4003 | /orders |
/api/orders/o1 | 订单服务 4003 | /orders/o1 |
/bff/orders/o1 | BFF 4000 | /bff/orders/o1 |
统一入口的公共路径和服务实际路径可以不同,只要事先配置好映射即可。本表是课程设计的约定,并非所有项目必须采用相同的 URL。
⚖️ 统一 API 入口与 BFF 有什么区别
它们都位于前端与业务服务之间,但解决的问题不同。
| 对比 | 统一 API 入口 | BFF |
|---|---|---|
| 核心问题 | 请求应该去哪个服务 | 页面需要怎样的数据 |
| 主要工作 | 根据路径转发请求、返回响应 | 调用业务接口、聚合和适配数据 |
| 是否需要了解订单字段 | 通常不需要 | 需要了解页面使用哪些字段 |
| 本课程示例 | 将 /api/orders 转给订单服务 | 将订单、用户和商品数据组织为详情页 JSON |
例如,请求 /bff/orders/o1 会先经过统一入口,再到 BFF。统一入口不会替 BFF 拼接数据;BFF 也不需要承担所有外部请求的转发工作。
两者可以部署在不同进程中,也可以根据项目规模选择不同的组织方式;划分它们的关键是职责,不是技术名称或端口数量。
🛠 利用已有的 Nginx 反向代理实现统一入口
前面的 Nginx 课程已经介绍过反向代理,因此这里只复用配置完成本篇的服务路由,不重新教学 location 和 proxy_pass 的原理。
在本地 Nginx 的一个 server 配置中,使用以下规则(假设四个服务都运行在同一台机器上):
server {
listen 127.0.0.1:8080;
location /api/users/ {
proxy_pass http://127.0.0.1:4001/users/;
}
location /api/products/ {
proxy_pass http://127.0.0.1:4002/products/;
}
# 创建订单:精确匹配 /api/orders
location = /api/orders {
proxy_pass http://127.0.0.1:4003/orders;
}
# 查询某张订单:匹配 /api/orders/ 下的路径
location /api/orders/ {
proxy_pass http://127.0.0.1:4003/orders/;
}
location /bff/ {
proxy_pass http://127.0.0.1:4000/bff/;
}
}
这里将创建订单的路径和查询单张订单的路径分别匹配,是为了让 /api/orders 与 /api/orders/o1 都正确映射,又避免不相关的路径被误认为订单接口。
你只需要关注公共地址与内部服务地址的对应关系。例如:
/api/orders → 4003 的 /orders
/api/orders/o1 → 4003 的 /orders/o1
/bff/orders/o1 → 4000 的 /bff/orders/o1
确保用户、商品、订单与 BFF 四个 Node.js 服务已经启动;然后按照前面 Nginx 课程的方法检查配置并重新加载 Nginx。不需要新建 gateway.mjs,也不需要再启动第五个 Node.js 进程。
本例为了本地验证监听
127.0.0.1:8080。如果前端运行在其他机器上,不能直接使用这个仅本机可访问的地址,需要按部署环境调整监听地址及访问方式。实际项目还应根据需要处理 HTTPS、权限和网络访问控制,这些不是本篇的教学重点。
🧪 验证统一入口是否生效
分别调用用户服务、BFF 和订单服务,但所有请求都经过 8080 端口。
1. 查询用户
curl -i http://127.0.0.1:8080/api/users/u1
预期返回 200,正文类似:
{"id":"u1","name":"小林","email":"lin@example.test"}
2. 查询订单详情
curl -i 'http://127.0.0.1:8080/bff/orders/o1?view=mobile'
预期返回 200,正文是 BFF 聚合后的数据:
{
"id": "o1",
"customerName": "小林",
"productName": "机械键盘",
"totalCents": 59800
}
3. 创建订单
curl -i -X POST http://127.0.0.1:8080/api/orders \
-H 'Content-Type: application/json' \
-d '{"userId":"u1","productId":"p1","quantity":1}'
沿用前面章节的初始数据,首次创建成功时预期返回 201,订单金额为 29900 分;订单 ID 取决于当前运行进程里已有的订单数量。
4. 验证路径是否正确
# 订单不存在:请求会转给订单服务,由订单服务返回 404
curl -i http://127.0.0.1:8080/api/orders/missing
# 未配置的公共路径:由 Nginx 处理,不会自动转给某个业务服务
curl -i http://127.0.0.1:8080/api/unknown
在本例的 Nginx 配置下,未匹配的 /api/unknown 通常返回 Nginx 自己的 404 页面,不一定是业务服务的 JSON 错误格式。这也说明了为什么排查问题时,要先弄清楚错误是由入口还是业务服务返回的。
如果请求失败,先确认公共路径是否匹配正确、目标服务是否已经启动、内部端口是否对应。这些检查足以完成本篇的实践目标。
❓ 知识问答
Q1:统一 API 入口一定要自己开发一个 Node.js 网关吗?
不需要。统一入口描述的是架构职责,不限定实现技术。本课程直接复用 Nginx 反向代理;只有出现 Nginx 基础配置难以满足的特定需求时,才考虑其他专门的网关方案,而不是默认手写转发程序。
Q2:有了统一入口,就可以把所有内部服务直接开放给公网吗?
不应该。统一入口的一个好处就是让前端通过固定的公共地址访问系统,内部服务通常只供入口或其他可信服务访问;是否允许外部访问应根据实际业务和网络设计决定。统一入口也不能替代业务服务自身的权限检查。
🧪 小练习
保持商品服务代码不变,尝试让前端通过一个新的公共路径访问它:
前端:GET /api/catalog/p1
目标:GET http://127.0.0.1:4002/products/p1
在已有 Nginx 配置中增加一条对应的路径映射,然后完成验证:
- 请求
http://127.0.0.1:8080/api/catalog/p1,应得到商品信息。 - 请求
http://127.0.0.1:8080/api/catalog/missing,应收到商品服务返回的404。 - 解释:为什么新增公共访问路径,只需要修改入口配置,而不必修改商品服务?
验收目标: 能独立说清楚公共路径、内部目标地址和业务服务之间的关系。
🎉 理解统一 API 入口在多服务架构中的作用,并使用已有的反向代理能力完成请求转发!
