企业官网建设流程全解析

• 电商
• 后端
• 前端

Electronics-eCommerce-Shop-With-Admin-Dashboard-NextJS-NodeJS（Singitronic）是一个基于 Next.js 和 Node.js 的开源全栈电商网站项目，内置功能完整的 Admin 管理后台。它的后端由 Express 提供 REST API，共挂载了12 个 API 路由模块，覆盖商品、订单、搜索、用户、分类、商家、通知、批量上传等核心场景。本文是一份面向新手的 API 速查清单，帮助你 5 分钟摸清每个接口的用途、参数和调用方式。


项目 API 架构：前后端如何分离

这个项目采用经典的前后端分离架构，理解它的分工是调用 API 的第一步：

12 个路由模块统一在 server/app.js 中挂载，例如/api/products对应商品、/api/orders对应订单、/api/bulk-upload对应 CSV 批量上传。前端的 API 客户端封装在 lib/api.ts 中，基础地址由 lib/config.ts 决定（http://localhost:3001）。

💡 后端还额外提供了两个"体检"端点：GET /health健康检查和GET /rate-limit-info限流信息查询（见 server/app.js），非常适合在调试前先确认服务是否正常。

12个REST接口速查总表

下表是整个后端 API 的全景图，详细拆解见后续章节：

商品API：/api/products 的完整CRUD

商品接口是电商站点的基础，支持完整的增删改查：

• GET /api/products：获取商品列表，支持筛选、排序和分页参数，例如page（页码）、filterType=price、filterOperator=gte、filterValue=100、sort=lowPrice等。这些参数在白名单中做了安全校验（见 server/controllers/products.js），非法参数会被直接忽略。加上?mode=admin可返回后台所需的全量商品。
• POST /api/products：新建商品。
• GET /api/products/:id：按 ID 获取单个商品详情。
• PUT /api/products/:id：更新商品信息。
• DELETE /api/products/:id：删除商品。

与之配合的还有GET /api/slugs/:slug，它通过 URL 友好的 slug（如wireless-headphones）直接定位商品，正是前端/product/[productSlug]详情页背后的数据来源。

搜索API：一个query参数搞定全文搜索

搜索接口非常轻量，只有 1 个端点，定义在 server/routes/search.js：

GET http://localhost:3001/api/search?query=headphone

它会同时在商品的title和description两个字段中做contains模糊匹配（见 server/controllers/search.js），并把命中的商品以 JSON 数组返回。缺少query参数时返回 400 错误。

⚠️ 搜索接口有独立限流：每分钟 30 次请求（searchLimiter），比全局限流更严格。

订单API：/api/orders 与 /api/order-product 双层结构

订单模块采用了"订单 + 订单商品"的双表结构，对应两个 API：

订单与订单明细的完整定义分别在 server/routes/customer_orders.js 和 server/routes/customer_order_product.js。两者共享orderLimiter限流：15 分钟内最多 15 次操作，防止恶意刷单。

批量上传API：CSV一次导入上千个商品

这是本项目的明星功能，位于/api/bulk-upload（路由见 server/routes/bulkUpload.js），核心流程是：

1. POST /api/bulk-upload：上传 CSV 文件（字段名为file），服务端逐行校验后在一个事务中创建上传批次（batch）和商品。
2. GET /api/bulk-upload：查看历史批次列表，包含文件名、商品数、错误数和时间戳。
3. GET /api/bulk-upload/:batchId：查看单个批次的详细结果，状态分为COMPLETED/PARTIAL/FAILED。
4. PUT /api/bulk-upload/:batchId：修正批次内的错误项后重新处理。
5. DELETE /api/bulk-upload/:batchId?deleteProducts=false：删除批次；带deleteProducts=true可连同商品一起删除（若商品已被订单引用则会拒绝删除，保证数据一致性）。

配套文档非常齐全，建议配合阅读：

• 快速上手：BULK-UPLOAD-QUICK-REFERENCE.md
• 完整指南：BULK-UPLOAD-GUIDE.md
• 删除批次说明：DELETE-BULK-UPLOAD-GUIDE.md
• 空白 CSV 模板：bulk-upload-template-blank.csv

对应的管理页面是/admin/bulk-upload（源码见 app/(dashboard)/admin/bulk-upload/page.tsx/admin/bulk-upload/page.tsx)），支持拖拽上传并可视化展示上传历史（组件见 components/BulkUploadHistory.tsx）。

其余接口：分类、用户、商家、通知、图片

剩下的接口大多遵循标准 REST 风格，这里给出使用要点：

• /api/categories：分类的完整 CRUD，商品创建时依赖它做分类校验。
• /api/users：用户管理，特别注意GET /api/users/email/:email是按邮箱查用户的端点，被authLimiter限制为15 分钟内 5 次，用于防止账号枚举。
• /api/merchants：商家信息的 CRUD，对应后台的商家管理页。
• /api/notifications：站内通知系统，GET /:userId/unread-count为顶栏铃铛提供未读角标（组件见 components/NotificationBell.tsx），POST /mark-read支持批量标记已读。
• /api/images与/api/main-image：商品图片上传，共享uploadLimiter限流（15 分钟 10 次）。

限流与安全：调用前必须知道的3件事

后端在 server/app.js 中为不同路由组配置了差异化限流，完整数值可通过GET /rate-limit-info实时查询：

另外两点值得注意：

1. CORS 白名单：只允许localhost:3000/3001及环境变量指定的前端来源跨域访问，并开启了credentials（见 server/app.js）。
2. 请求日志：每个请求都会生成requestId并写入server/logs/，方便排查问题（中间件见 server/middleware/requestLogger.js）。

如何快速验证接口：一条curl命令上手

启动后端服务（server/目录下运行npm start，默认 3001 端口）后，可以用最简单的两条命令验证环境：

curl http://localhost:3001/health curl "http://localhost:3001/api/search?query=laptop"

第一条返回{"status":"OK"}即服务正常；第二条会返回匹配 "laptop" 的商品 JSON 数组。之后就可以按上面的速查表逐个调用各业务接口了。

写在最后

这份 12 个 REST 接口的清单覆盖了 Singitronic 电商站点的全部后端能力：用/api/products+/api/search支撑前台购物，用/api/orders+/api/order-product支撑交易闭环，用/api/bulk-upload支撑高效的批量运营。所有路由源码集中在 server/routes/ 与 server/controllers/ 目录，配合 prisma/schema.prisma 中的数据库模型阅读，可以完整理解从接口到数据的整条链路。

• 电商
• 后端
• 前端