夏哉ke: bcwit.top/413

在技术学习的道路上，“造轮子”是最有效的成长方式之一。当你亲手从零搭建一个完整的全栈应用时，你获得的不仅是代码能力，更是对技术选型、架构设计、工程化实践、问题排查的全面理解。

本文将以 React.js 为前端、Egg.js 为后端，从零构建一个完整的旅游电商应用。我将以“手把手”的方式，带你走过项目的每一个关键阶段：从技术选型到架构设计，从核心功能实现到难点攻克，从部署上线到复盘思考。这不是一份代码说明书，而是一份全栈实战的方法论沉淀。

一、 项目启动：为什么选择旅游电商？

1.1 场景复杂度决定了学习深度

旅游电商不是简单的“商品展示+购物车”，它天然具备全栈开发的典型复杂度：

• 复杂的商品模型：一个旅游产品往往包含多个SKU（不同出发日期、房型、套餐），每个SKU有独立的库存、价格、退改规则。

• 高并发场景：节假日秒杀、热门景点放票，对后端抗压能力提出严苛要求。

• 实时性要求：库存实时扣减、价格实时变动、订单状态实时同步。

• 丰富的交互：日期选择器、价格日历、游客信息表单、支付流程，涉及大量前端复杂交互。

攻克这些难点，意味着你掌握了从“能跑起来”到“能扛住业务”的全栈核心能力。

1.2 技术选型的考量

React.js 的选择基于：

• 组件化能力完美匹配旅游电商复杂的UI模块。

• Hooks机制让业务逻辑与视图分离，便于复用和测试。

• 生态成熟，路由、状态管理、UI组件库一应俱全。

Egg.js 的选择基于：

• 阿里系企业级框架，“约定优于配置”让团队协作更顺畅。

• 内置多进程模型、中间件机制、插件体系，天然适合构建API服务。

• 插件生态丰富（Sequelize、Redis、JWT），开箱即用。

二、 前端架构设计：React.js 的工程化实践

2.1 项目初始化与技术栈配置

项目启动的第一步是搭建前端工程化环境。我们选择了 Vite 作为构建工具，它比 Webpack 更轻量，开发热更新速度更快。技术栈组成：

• 核心框架：React 18 + React Router v6

• 状态管理：Redux Toolkit + React Query（TanStack Query）

• UI组件库：Ant Design Mobile（适配移动端旅游场景）

• HTTP客户端：Axios（配合拦截器统一处理鉴权、错误）

• 类型系统：TypeScript（全栈类型安全的基础）

2.2 组件分层设计：从原子到页面

我们遵循 原子设计理论，将UI组件分为五层，这是保证大型项目可维护性的基石：

• 基础原子组件：封装 Button、Input、Modal 等基础元素。这一层只关心UI样式，不包含任何业务逻辑。

• 分子组件：由基础组件组合而成，如“搜索框”（Input + Button + 历史记录下拉）、“商品卡片”（图片+标题+价格+标签）。这一层开始具备简单的交互逻辑。

• 有机体组件：承载复杂业务逻辑的组件，如“日期选择器”——需要处理日历渲染、价格查询、库存状态展示、不可选日期禁用等复杂逻辑。这是前端最难啃的部分。

• 模板组件：页面的骨架布局，如“商品详情页模板”包含轮播图、信息区、预订面板、评价列表等区块的位置规划。

• 页面组件：最终组装模板、处理路由参数、数据请求的入口。这一层最“薄”，主要负责协调。

这种分层带来的核心价值是可维护性：修改原子组件，所有引用处自动更新；替换有机体组件的实现方式，不影响上层调用。

2.3 状态管理的“组合拳”

我们摒弃了“一刀切”的状态管理方案，根据状态性质选择不同策略：

• UI状态（如弹窗显隐、表单临时数据）：使用组件内部的 useState 或 useReducer，生命周期随组件销毁而释放。这是React最基础的用法。

• 全局业务状态（用户信息、购物车、收藏夹）：使用 Redux Toolkit。借助 createSlice 简化reducer编写，利用 createEntityAdapter 规范化存储列表数据（如购物车商品），避免数据冗余问题。

• 服务端状态（商品列表、订单数据）：引入 TanStack Query（原React Query）。它将数据获取、缓存、重试、后台刷新逻辑与组件状态完全解耦。设置 staleTime 和 cacheTime，实现“用户切换页面再返回时，数据秒开”的体验——这是提升用户体验的关键。

2.4 路由设计与权限控制

使用 React Router v6 实现前端路由，重点处理三个问题：

• 动态路由：/product/:id 对应商品详情页，利用 loader 函数在路由加载前预取数据，避免页面闪烁。这是v6带来的重要改进。

• 路由守卫：封装 ProtectedRoute 组件，检查用户登录状态和权限（如“订单页”需要登录）。未登录时重定向到登录页，并将目标URL存入 location.state，登录后自动跳回——这是提升用户体验的细节。

• 懒加载：使用 React.lazy + Suspense 对支付页、后台管理等低频路由进行代码分割。首屏加载体积可减少约30%，对移动端场景意义重大。

2.5 性能优化的实战经验

旅游电商包含大量高清图片和长列表，我们做了针对性优化：

• 图片优化：编写自定义Hook useLazyLoad，利用Intersection Observer API实现图片懒加载。同时结合后端能力，根据屏幕分辨率请求不同尺寸图片，并优先使用WebP格式。这对首屏加载速度影响显著。

• 虚拟滚动：搜索结果页可能展示数百个商品，使用 react-window 实现虚拟滚动，只渲染可视区域内的DOM节点。实测滚动帧率从卡顿30fps提升到流畅60fps。

• 防抖与节流：搜索输入框使用防抖，避免每次按键都发起请求；滚动加载更多使用节流，控制触发频率。这些细节决定了用户感知的“流畅度”。

三、 后端架构设计：Egg.js 的企业级实践

3.1 项目初始化与目录结构

Egg.js 的“约定优于配置”让项目结构清晰统一。我们遵循以下目录规范：

app/
├── controller/      # 控制器层：接收请求，参数校验，响应输出
├── service/         # 业务逻辑层：核心业务实现
├── model/           # 数据模型层：定义表结构和关联关系
├── middleware/      # 中间件：鉴权、限流、日志等
├── extend/          # 扩展：挂载 helper、context 方法
├── schedule/        # 定时任务：凌晨价格计算、过期订单处理
└── utils/           # 工具函数：加密、日期格式化等

这种分层让代码职责清晰，后续维护和新人上手都更加顺畅。

3.2 分层架构：Controller → Service → Model 的严格划分

• Controller 层：只负责三件事——参数校验（利用 egg-validate 插件）、调用 Service、返回统一格式的响应。Controller层保持“薄”，不包含任何业务逻辑。这样做的价值在于：当业务规则变化时，只需修改 Service 层，Controller 层几乎不需要变动。

• Service 层：业务逻辑的核心。按领域拆分 Service（user.js、order.js、product.js），每个 Service 的方法对应一个业务用例。例如 order.create() 方法内部会调用 inventory.lockStock()、coupon.use()、payment.create()，并通过 Sequelize 的事务确保原子性。这是保证数据一致性的关键。

• Model 层：使用 Sequelize 定义数据模型和关联关系。旅游电商的关联关系复杂：一张订单关联多个游客信息（hasMany），一个商品关联多张图片（hasMany），一个用户有多个收藏（belongsToMany）。正确配置关联关系，让后续查询可以 include 关联数据，避免手写复杂JOIN。

• Helper 和 Extend：封装通用工具函数（如日期格式化、价格计算）挂载到 helper 上；在 ctx 上挂载 ctx.success() 和 ctx.error() 方法，统一响应格式，减少重复代码。

3.3 中间件：构建安全防线

Egg.js 的中间件洋葱圈模型让我们能够无侵入地增强功能：

• JWT鉴权中间件：除登录注册外，所有接口都经过此中间件。从 Authorization 头解析JWT，验证签名和有效期，将用户信息挂载到 ctx.user。我们实现了双Token机制：Access Token（短期，用于API调用）和 Refresh Token（长期，存储在 httpOnly Cookie 中）。当 Access Token 过期时，前端携带 Refresh Token 换取新 Token，实现无感刷新——这对用户体验至关重要。

• 限流中间件：针对“发送验证码”、“提交订单”等敏感接口，结合 Redis 实现基于 IP 和用户 ID 的滑动窗口限流。例如，同一手机号每分钟最多发送1条验证码，每天最多5条。这是防止恶意刷单的第一道防线。

• 日志中间件：记录每个请求的入参、耗时、响应码，输出到指定日志文件。线上问题排查时，这些日志是最重要的线索。

3.4 数据库设计：权衡范式与性能

• 选型：采用 MySQL（阿里云RDS）作为主数据库，利用 Sequelize ORM 管理表结构和迁移。迁移功能让数据库变更可版本化、可追溯。

• 核心表设计：

  • products 表：存储商品基本信息（标题、描述、主图、目的地）

  • skus 表：存储SKU级信息（出发日期、价格、库存、房型），与 products 表为多对一关系

  • orders 表：存储订单主信息（用户ID、总金额、状态、支付时间）

  • order_items 表：存储订单明细（SKU ID、数量、单价）

  • travelers 表：存储每个订单关联的游客信息（姓名、证件号、手机号）

• 索引优化：针对高频查询字段建立索引，如 orders.user_id、orders.status、products.category_id。同时注意避免过多索引影响写入性能——这是数据库设计的经典权衡。

3.5 缓存与分布式锁：应对高并发

• Redis 缓存：

  • 热点数据缓存：热门商品详情页数据缓存5分钟，减轻数据库压力。缓存更新采用“主动更新 + 被动过期”结合的策略：后台修改商品后主动删除缓存；用户查询时若缓存不存在，从数据库加载并写回。

  • 用户会话缓存：将用户登录态信息存储在 Redis，设置过期时间，支持分布式部署下的会话共享。

• 分布式锁：库存扣减是典型的并发场景。使用 Redis 的 SET NX EX 实现分布式锁，在“锁定库存 → 创建订单 → 扣减库存”的操作序列上加锁，避免超卖。锁的超时时间设置为业务逻辑预估执行时间的2-3倍，并配合 Lua 脚本保证释放锁的原子性——这是保证并发安全的核心手段。

四、 核心难点攻克：从“能做”到“做好”

4.1 库存扣减：保证不超卖，也不锁死

旅游电商的库存扣减有两个特点：一是用户下单后有30分钟支付缓冲期；二是支付失败后需释放库存。

我们的方案是 “预占库存 + 异步支付确认” 模式：

1. 下单预占：用户提交订单时，从 Redis 中扣减 SKU 库存（DECR），并创建订单记录，状态为“待支付”。同时将订单信息推送到延迟队列。

2. 延迟释放：延迟队列在30分钟后触发，检查订单状态。若仍为“待支付”，则自动取消订单，并恢复 Redis 库存（INCR）。

3. 支付确认：用户支付成功后，调用确认接口，将订单状态改为“已支付”，并将 Redis 扣减同步到数据库的最终库存（异步落库，避免阻塞主流程）。

这个方案的核心优势：Redis 操作毫秒级完成，大幅提升并发能力；延迟队列保证库存最终释放；数据库库存作为最终一致性的兜底。

4.2 价格日历：算法与性能的平衡

商品详情页的“价格日历”需要展示未来30天每天的最低价格和库存状态。若每次加载时实时计算30天的价格，数据库压力大且响应慢。

我们采用 “预计算 + 缓存” 策略：

• 每日凌晨定时任务（Egg.js 的 egg-schedule）计算未来30天的每日最低价，结果存入 Redis 的 Hash 结构（Key: price_calendar:{product_id}，Field: 日期，Value: 价格）。

• 前端加载时，直接读取 Redis，毫秒级返回。当库存发生变化时（如某天售罄），实时更新对应的 Redis 字段。

这个方案将“查询时计算”转化为“写入时预计算”，是典型的用空间换时间。

4.3 订单状态机：用状态模式管理复杂流转

订单有“待支付”、“已支付”、“已出票”、“已取消”、“已完成”、“退款中”等多种状态，不同状态允许的操作不同。

我们在 Service 层实现状态模式：

• 定义订单状态枚举，每个状态对应一组允许的操作（如“待支付”允许“支付”、“取消”；“已支付”允许“申请退款”）。

• 状态变更时，先校验操作是否允许，再执行对应的业务逻辑，最后更新状态并触发后续流程（如发送通知、释放库存）。

这种设计让订单逻辑清晰可控，新增状态时只需扩展枚举和允许操作集，符合开闭原则。

4.4 用户认证与安全

• 密码加密：使用 bcrypt 进行密码哈希存储，加盐处理，即使数据库泄露也无法还原明文密码。

• JWT 安全：Access Token 有效期为2小时，Refresh Token 有效期为7天。Refresh Token 存储在 httpOnly Cookie 中，防止 XSS 攻击窃取。

• 敏感数据脱敏：API 返回用户信息时，手机号中间4位脱敏（如 138****1234），身份证号部分脱敏。

五、 全栈联调：让前后端协作更高效

5.1 接口规范与 Mock

• 规范先行：使用 Swagger/OpenAPI 定义接口，Egg.js 通过 egg-swagger-doc 插件自动生成 API 文档。前端根据文档生成 TypeScript 类型定义（openapi-typescript），实现前后端类型安全——这是减少联调 Bug 的关键。

• Mock 并行：开发初期，后端接口未就绪时，前端使用 Mock Service Worker 模拟接口数据。MSW 在浏览器层面拦截请求，返回预设数据，让前端开发不依赖后端环境，大幅提升并行开发效率。

5.2 跨域与代理

• 开发环境：Vite 开发服务器配置代理，将 /api 路径的请求转发到本地 Egg 服务（http://localhost:7001），解决跨域问题。

• 生产环境：使用 Nginx 反向代理，将前端静态资源（React打包文件）和后端 API 服务部署在同一域名下，避免浏览器跨域限制，同时可配置静态资源缓存策略。

5.3 异常处理与错误码

• 统一错误码：定义全局错误码枚举（如 10001 参数错误，20001 未登录，30001 库存不足），前端根据错误码做差异化处理（如弹提示、跳转登录）。这让前端异常处理逻辑清晰统一。

• 全局异常捕获：Egg.js 通过 onerror 中间件统一捕获未处理异常，返回标准错误格式；前端通过 axios 拦截器统一处理异常响应，避免每个请求都写 try-catch 的重复代码。

六、 部署运维：让应用稳定运行

6.1 容器化部署

• Docker 镜像：编写 Dockerfile，将 React 前端打包为 Nginx 镜像，将 Egg 后端打包为 Node 镜像。

• 多阶段构建：前端镜像使用多阶段构建，先 Node 镜像打包，再将产物复制到 Nginx 镜像，最终镜像体积从 500MB 降到 50MB——这对部署速度和资源消耗意义重大。

• 编排：使用 docker-compose 编排前端、后端、MySQL、Redis 四个容器，实现一键启动完整环境，解决“本地正常、线上异常”的环境不一致问题。

6.2 日志与监控

• 日志管理：Egg.js 内置日志系统，按日切割，错误日志单独输出。使用 egg-logrotator 插件自动清理过期日志，防止磁盘爆满。

• 性能监控：接入 Sentry 捕获前端异常，接入阿里云 Node.js 性能平台监控后端 CPU、内存、慢接口。设置告警阈值（如接口响应超过500ms），及时发现问题。

6.3 CI/CD 流程

使用 GitHub Actions 搭建自动化流水线：

1. 代码 Push 到 main 分支

2. 运行单元测试（Service层核心逻辑）和 ESLint 检查

3. 构建前端静态资源和后端 Docker 镜像

4. 推送镜像到阿里云容器镜像服务

5. 通过 SSH 连接服务器，执行部署脚本，实现滚动更新（零停机发布）

这套流程让“一键发布”成为可能，大幅提升了交付效率和可靠性。

七、 复盘与思考：造轮子带来的认知升级

7.1 踩过的坑

• N+1 查询问题：在 Sequelize 中使用 include 关联查询时，若未正确配置，可能导致查询次数爆炸。通过开启 logging: console.log 观察实际 SQL，发现并修复。

• 状态不一致：早期使用前端 localStorage 存储购物车，导致多端登录时购物车数据不同步。后改为后端存储，前端每次渲染时请求最新数据。

• Session 与 JWT 混用：初期部分接口用 Session 鉴权，部分用 JWT，导致鉴权逻辑混乱。后统一为 JWT，利用 Redis 存储黑名单，实现登出功能。

7.2 收获的思维

• 架构分层思维：不再把代码写成一坨，而是清楚每一层的职责边界。Controller 薄、Service 厚、Model 稳——这套原则适用于任何后端项目。

• 工程化意识：从手动部署到 CI/CD，从本地调试到日志监控，工程化让代码交付更可靠、更可追溯。

• 业务与技术平衡：不追求技术炫技，而是根据业务场景做取舍。比如用 Redis 预扣库存而非复杂分布式事务，用预计算价格日历而非实时计算——这些都是基于业务需求的务实选择。

• 全栈视角：同时理解前后端的痛点，让协作更顺畅。前端需要什么数据结构，后端能提供什么能力——这种双向理解是全栈工程师的核心优势。

八、 写给未来的你

从零开始，用 React.js + Egg.js 造一个旅游电商应用的轮子，是一场全栈能力的综合检验。它让你不再满足于“会调 API”或“会渲染页面”，而是深入到数据流转的每一个环节、并发处理的每一个细节、工程化落地的每一个步骤。

这套实战带来的，不仅是一个可运行的旅游电商项目，更是一套可复用的全栈架构方法论——无论未来面对电商、社交、教育还是企业级应用，这套关于“组件分层、状态管理、接口设计、数据库建模、并发处理、部署运维”的思考框架，都将成为你技术进阶路上的坚实基石。