使用 Node.js 与 TypeScript 设计生产就绪的订单管理 REST API

Source: Dev.to

中小企业往往不需要复杂的 ERP 系统。
它们真正需要的是一个可靠的后端 API 来管理产品、订单和库存——一个可以轻松接入网页或移动前端的解决方案。

本文展示了一个订单管理 REST API 的设计与实现，该 API 作为电商平台和物流类产品的真实后端基础。API 面向的常见使用场景包括：

• B2C 电商平台
• 中小企业内部订单管理工具
• 商业或物流领域的创业 MVP

它覆盖了订单的完整生命周期，从创建到交付，同时保持系统轻量且易于扩展。目标很简单：构建一个能够在生产环境中真实运行的后端，而不仅仅是演示项目。

核心功能

身份验证与角色

• 用户注册和登录
• 将 JWT 身份验证存储在 HTTP‑only Cookie 中
• 会话轮换和注销
• 密码更新

角色

• CLIENT – 可以下单并查看自己的购买记录
• ADMIN – 管理产品、库存和所有订单

产品与库存管理

• 完整的产品 CRUD 系统
  • 对产品列表和详情公开访问
  • 仅管理员可创建、更新和删除
• 每个产品包含名称、描述、价格和库存数量

订单管理

• 订单可包含多个产品
• 自动计算每个商品的小计
• 计算订单总金额
• 验证库存后方可确认
• 订单创建时记录产品快照（名称和价格）
• 客户只能查看自己的订单；管理员可以访问所有订单

订单生命周期

只有管理员可以更新订单状态，使系统适用于物流和履约工作流。

技术栈

• Node.js – 运行时
• Express.js – 极简 HTTP 框架
• TypeScript – 类型安全与可维护性
• PostgreSQL – 关系型数据库
• Prisma – 数据访问层
• Zod – 输入验证
• Swagger / OpenAPI 3 – API 文档

该技术栈强调清晰性、安全性以及长期可维护性。

架构与设计选择

项目使用基于领域划分的单体 REST 架构：

• authentication
• users
• products
• orders

每个领域分为：

• routes
• controllers
• services
• validations
• data access layers

该结构对小团队和自由职业者来说可扩展性良好，同时在需要时也易于重构为微服务。

数据建模与业务逻辑

• 一个用户可以拥有多个订单
• 一个订单包含多个订单项
• 每个订单项引用一个产品

一个关键的设计决定是 在下单时存储产品数据的快照，即使以后价格变化，也能确保历史准确性——这一细节可以防止重大业务不一致。

安全考虑

• JWT 存储在 HTTP‑only Cookie 中，以防止令牌泄露
• 在后端强制基于角色的授权
• 使用 Zod 进行严格的请求验证
• 不会不必要地暴露敏感数据

这些选择有助于避免早期产品常见的陷阱。

使用 Swagger 的 API 文档

该 API 使用 OpenAPI 3 完整记录：

• 按业务域分组的端点
• 清晰的请求和响应模式
• 已记录的错误响应
• 如订单创建等复杂操作的示例

良好的文档能够减少后端、前端和外部使用者之间的摩擦——将 API 打造成可用的产品。

成熟度水平与后续步骤

The API currently stands at an advanced MVP level:

• Feature‑complete for a simple e‑commerce platform
• Secure by default
• Clean data model
• Usable documentation

Planned improvements

• Pagination and filtering
• Logging and monitoring
• Automated testing
• Payment integration
• Advanced stock management (reservations, rollbacks)