企业官网建设流程全解析

easy-vibe Stage 2 进阶任务实战：基于 API 网关与服务拆分的生鲜电商微服务系统开发

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe

本文是 easy-vibe 课程 Stage 2（初级与中级开发阶段）进阶任务“生鲜电商微服务系统”的完整技术指南。与前面所有单服务（Monolith）项目不同，本任务要求你将后端按业务领域拆分为鉴权、商品、库存、订单四个独立服务，并引入 API Gateway 统一对外路由。读完本篇后，你将掌握微服务系统的需求分析方法、服务边界设计、网关路由实现，以及库存扣减与订单状态之间的跨服务一致性处理策略，并能交付一个端到端可演示的微服务原型。

任务定位与系统总览

本任务在课程中属于 Stage 2 的“扩展任务”之一，建议在完成“Copywriting-生成网站”“在线考试与管理系统”两个主项目后再挑战（参见 Stage 2 课程索引）。它模拟的是真实工作中非常常见的微服务架构形态：每个服务可独立启动、独立维护，前端体验则必须像一个统一产品，而不是几个接口拼起来的东西。

你要构建的产品是一个生鲜电商微服务系统，包含两个子系统：

后端按业务拆分为五个部分：

完整的需求文档（PRD）位于仓库中：PRD：生鲜电商微服务系统。本任务的整体工作流分为四个阶段：

1. 需求分析：阅读 PRD，明确服务拆分、页面和交易链路；
2. 搭建骨架：生成前端、网关和各服务骨架；
3. 迭代开发：逐模块补接口、修复库存与订单一致性；
4. 联调上线：端到端跑通，部署并准备演示。

前置知识与学习目标

开始本项目之前，建议已完成 Stage 2 中的以下课程：

• 前端页面设计与组件库使用（UI 设计、现代组件库）
• 后端接口设计与开发（接口代码编写）
• 数据库基础与 Supabase（从数据库到 Supabase）
• Git 工作流与部署（Git 和 GitHub、部署 Web 应用）

完成本实战后，你将能够：

1. 阅读 PRD 并提取微服务系统的开发任务清单；
2. 按业务领域拆分服务边界（鉴权、商品、库存、订单）；
3. 设计和实现 API 网关路由；
4. 处理库存扣减和订单一致性等跨服务问题；
5. 完成端到端联调，交付可演示的微服务原型。

第一部分：需求分析

1.1 阅读 PRD 要回答的四个问题

打开 PRD 文档后，重点回答以下问题。这些问题决定了后续所有架构决策：

• 服务如何拆分？每个服务的职责边界是什么？
• 前台和管理端分别有哪些页面？
• 下单后库存扣减的策略是什么？成功 / 失败 / 超时各怎么处理？
• 第一版哪些复杂能力先不做？例如分布式事务、消息队列集群。

重要提示：如果以上问题没有明确答案，不要开始写代码。需求理解不清楚是导致返工的最常见原因。

1.2 确认系统架构

确认服务之间的调用关系与本图一致：PRD 驱动前端页面设计，所有外部请求经过 API Gateway 路由到各服务，Order Service 在下单时调用 Inventory Service 完成库存联动。

从源码结构看，PRD 还给出了更完整的站点级视角：三套入口（官网前台www.xxx.com、用户前台app.xxx.com、后台管理台admin.xxx.com）全部汇入同一个 API Gateway，再由网关分发到四个业务服务。这一约定是后面路由设计的基础。

第二部分：搭建项目骨架

2.1 用 AI 生成项目结构

本任务延续 easy-vibe 的 Vibe Coding 方法论：先给 AI IDE 一个结构化提示词，让它生成骨架，再由你负责审查与验证。提示词参考：

请基于当前 PRD，帮我生成一个生鲜电商微服务系统的项目骨架。 要求： 1. 生成前端用户端和管理端骨架 2. 生成 api-gateway、auth-service、catalog-service、inventory-service、order-service 五个目录 3. 每个服务先只做最小可运行入口 4. 先不接真实数据库和支付

这条提示词体现了两个关键约束：一是“最小可运行入口”——骨架阶段每个服务只要能启动、能响应健康检查即可，避免一次性生成大量不可验证的代码；二是明确“先不接真实数据库和支付”，把范围锁定在 MVP 内（PRD 规定第一版不做真实支付、优惠券、秒杀、消息队列集群和分布式事务框架）。

2.2 验证项目结构

生成后逐项检查，全部通过才能进入迭代开发：

• 五个服务目录（api-gateway、auth-service、catalog-service、inventory-service、order-service）结构清晰
• API Gateway 可以启动并转发请求
• 各服务健康检查接口（health check）可用
• 前端用户端和管理端页面可访问

第三部分：迭代开发

3.1 按模块推进的开发顺序

PRD 推荐的开发顺序与模块依赖一致：先打通网关与鉴权，再做数据服务，最后做交易闭环，管理端最后补齐：

1. API Gateway：路由配置、JWT 校验中间件
2. Auth Service：注册、登录、JWT 颁发
3. Catalog Service：商品 CRUD、列表查询
4. Inventory Service：库存查询、库存扣减
5. Order Service：订单创建、状态流转、库存联动
6. 管理端：商品管理、库存管理、订单管理

每个模块完成后，通过下表对应的验证方法做自检，再进入下一个模块：

第四部分：联调与上线

4.1 端到端测试场景

联调阶段至少要跑通两条完整业务链路：

• 用户链路：浏览商品 → 加入购物车 → 下单 → 查看订单
• 管理员链路：添加商品 → 更新库存 → 查看订单

验证重点不是“页面能打开”，而是两条链路中的状态一致性：下单成功后库存应减少、订单状态应更新；管理端调整库存后，用户端商品详情看到的库存状态应同步变化。

PRD 技术规格深度解析

骨架验证通过后，PRD 中的以下技术规格是迭代开发的“事实依据”，这里结合原文逐项展开。

技术选型与站点入口约定

PRD 给出的推荐技术栈：

站点入口约定为：官网前台www.xxx.com、用户前台app.xxx.com、后台管理台admin.xxx.com。三套入口共用一个 Gateway，这意味着网关的路由配置天然成为“按域名/路径分发到不同前端与服务”的边界。

MVP 范围与角色权限

第一版必须包含：API Gateway、Auth 服务、Catalog 服务、Inventory 服务、Order 服务、用户端商品列表/详情/下单、管理端商品与库存管理。

第一版明确不做：真实支付、优惠券和促销、秒杀、消息队列集群、分布式事务框架。

页面架构：3 套入口，9 个大页面

PRD 建议的关键前端组件包括：商品卡片、购物车抽屉/页面、订单状态标签、管理后台表格、库存调整弹窗。产品设计上借鉴 Instacart 的用户购物路径：商品页和购物车页强调价格、库存状态和操作反馈，管理端更像运营后台，突出状态管理。微服务拆分服务于业务边界，但前台体验必须尽量统一。

建议数据模型

PRD 给出的 PostgreSQL 数据模型草案如下，注意各服务的表归属即其数据边界：users归 Auth 服务，products归 Catalog 服务，inventory_items归 Inventory 服务，orders/order_items归 Order 服务。

users ( id uuid primary key, email text, password_hash text, role text, created_at timestamptz ) products ( id uuid primary key, name text, category text, price_cents int, status text, created_at timestamptz ) inventory_items ( id uuid primary key, product_id uuid, available_quantity int, reserved_quantity int, updated_at timestamptz ) orders ( id uuid primary key, user_id uuid, total_amount_cents int, status text, created_at timestamptz ) order_items ( id uuid primary key, order_id uuid, product_id uuid, quantity int, price_cents int )

其中inventory_items同时设计了available_quantity与reserved_quantity两个字段，这是“预扣库存”策略的数据基础：下单时先占用（reserved），确认订单后才真正扣减（available 减少）；若订单取消或超时，则回滚预扣。

下单主链路与一致性规则

这是整个任务的技术核心。PRD 定义的下单主流程：

1. 用户提交订单
2. Gateway 完成鉴权
3. Order 服务校验商品
4. Inventory 服务预扣库存
5. Order 服务创建订单
6. 成功则确认库存，失败则补偿回滚

关键规则：

• 库存不足直接失败——不允许超卖，也不需要排队重试；
• 同一个订单只允许一次成功创建——幂等性要求，防止重复提交产生重复订单；
• 所有状态变化要可追踪——配合 PRD 中“服务之间日志可追踪”的非功能要求。

对应的两条关键状态流：

• 订单：待创建 → 已创建 → 已完成 / 已取消
• 库存：可用 → 预扣 → 确认扣减 / 回滚

接口草案

所有外部接口统一走 Gateway，PRD 给出的接口清单：

从接口路径可以看出网关的路由规则：按 URL 前缀/api/auth/*、/api/catalog/*、/api/orders/*、/api/inventory/*、/api/admin/*转发到对应服务；同时/api/admin/*与用户端接口分开，正好对应模块自检表中的“权限隔离”检查项。

POST /api/orders请求示例：

{ "items": [ { "productId": "p1", "quantity": 2 }, { "productId": "p2", "quantity": 1 } ] }

非功能要求与后台指标

PRD 的非功能要求包括：本地一键启动（由 Docker Compose 支撑）、服务之间日志可追踪、接口返回结构统一、关键链路有错误处理和补偿逻辑。

管理端建议至少展示这些业务指标：下单成功率、库存回滚次数、热销商品排行、订单状态分布、库存预警数；基础监控建议覆盖：网关错误率、鉴权服务成功率、库存服务超时率、订单创建失败率。

待确认项

PRD 结尾保留了几个开放问题，实现时先做出明确选择并记录在 README 中：

• 前端是否做购物车持久化
• 服务间通信先用 HTTP 还是预留消息机制
• 商品与库存是否拆独立数据库
• 管理端是否允许直接修改订单状态

交付物与评分标准

交付物清单

完成本项目后，需要提交：

• 可访问的线上演示链接
• 源码仓库链接（含 README）
• PRD 文档
• 核心页面截图（商品列表、下单页、订单页、管理后台）
• 60 秒演示视频

评分标准

从评分表可以看出本任务的验收重心：不是页面数量，而是跨服务的一致性闭环（下单 → 扣减 → 状态可追踪）与工程完整度（服务可独立启动、可编排、可部署）。

参考资料

• UI 设计
• 使用现代组件库更新你的界面
• 从数据库到 Supabase
• 大模型辅助编写接口代码与接口文档
• Git 和 GitHub 工作流
• 如何部署 Web 应用
• PRD：生鲜电商微服务系统
• Stage 2 课程索引

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe