第 12 章 · 毕业项目：shop-spring 电商后台 MVP
本章目标：在 ch01～ch11 基础上，独立交付 shop-spring-demo 电商后台 API 最小可行产品（MVP）；覆盖用户登录、商品管理、订单流程、REST API 与统一响应；按 5 天计划实施；通过 100 分验收表自评；完成 curl 冒烟与答辩演示。
学时建议：5 天 × 6～8 小时（合计 30～40 小时）
前置：完成本模块 ch01～ch11；前端联调可参考 frontend-framework API 章节。
12.1 项目背景与边界
shop-spring-demo 是一家虚构的「轻量电商后台 API 平台」，为运营 SPA 与内部工具提供 JSON 接口。服务部署在 https://api.example.com（本地等价 http://127.0.0.1:8080）。
┌──────────────────────────────────────────────────────────┐
│ shop-spring-demo MVP（本章） │
├──────────┬──────────┬──────────┬─────────────────────────┤
│ 用户登录 │ 商品 API │ 订单 API │ 横切与运维 │
│ 注册/会话 │ CRUD+分页 │ 创建/查询 │ 缓存/日志/测试/部署 │
└──────────┴──────────┴──────────┴─────────────────────────┘
│
▼
MySQL（教学可用 H2）
Redis（缓存 ch10）
| 模块 | MVP 必须 | 不做（进阶 ch13～ch19） |
|---|
| 用户 | 注册、登录、/api/users/me、密码哈希 | JWT 无状态（ch15）、OAuth2 |
| 商品 | 列表、搜索、创建/编辑、上下架、封面上传 | SKU 矩阵、库存扣减事务优化 |
| 订单 | 创建、我的订单、状态流转（待付/已付/取消） | 支付网关、分布式事务 |
| API | REST + Result<T> 统一 envelope | SpringDoc 完整文档（ch14） |
| 安全 | Spring Security 表单/Session 或基础 JWT | RBAC 细粒度（ch16） |
| 运维 | .env.example、jar 文档、健康检查 | Docker/K8s 全量（ch19） |
严禁将真实公司内部域名、数据库连接串、密钥写入仓库或答辩材料。统一使用 shop-spring-demo、api.example.com。
12.2 技术栈与目录结构
| 层级 | 技术 | 对应章节 |
|---|
| 框架 | Spring Boot 3.x | ch01 |
| Web | Spring MVC REST | ch03、ch07 |
| ORM | Spring Data JPA | ch05 |
| 安全 | Spring Security | ch06 |
| 响应 | 统一 Result + 错误码 | ch07 |
| 上传 | MultipartFile | ch08 |
| 横切 | AOP + Interceptor + Logback | ch09 |
| 缓存异步 | Redis Cache + @Async + @Scheduled | ch10 |
| 测试部署 | MockMvc + jar + systemd | ch11 |
shop-spring-demo/
├── .env.example
├── docker-compose.dev.yml # MySQL + Redis
├── docs/
│ ├── API.md
│ ├── DEPLOY.md
│ └── SELF_REVIEW.md # 100 分自评表
├── scripts/smoke.sh
├── src/main/java/com/example/shop/
│ ├── config/ # Security, WebMvc, Redis, Async
│ ├── domain/ # User, Product, Order
│ ├── repository/
│ ├── service/
│ ├── web/ # REST Controller
│ ├── dto/ # ch13 深化
│ ├── common/ # Result, 异常, 错误码
│ ├── aop/
│ └── job/ # @Scheduled
└── src/test/java/... # MockMvc 测试
12.3 核心实体与 API 清单
User 1 ──* Order
Product 1 ──* OrderItem *── 1 Order
| 实体 | 关键字段 | 说明 |
|---|
| User | username 唯一 | BCrypt 密码 |
| Product | published | 下架商品不出现在公开列表 |
| Order | PENDING_PAYMENT 等枚举 | ch10 定时取消 |
| OrderItem | priceSnapshot | 下单时价格快照 |
认证
| 方法 | 路径 | 说明 |
|---|
| POST | /api/auth/register | 注册 |
| POST | /api/auth/login | 登录返回 Token 或 Session |
| GET | /api/users/me | 当前用户 |
商品
| 方法 | 路径 | 说明 |
|---|
| GET | /api/products | 分页列表 page,size,keyword |
| GET | /api/products/{id} | 详情 |
| POST | /api/products | 创建（ADMIN） |
| PUT | /api/products/{id} | 更新 |
| POST | /api/products/{id}/cover | 封面上传 ch08 |
| PATCH | /api/products/{id}/publish | 上下架 |
订单
| 方法 | 路径 | 说明 |
|---|
| POST | /api/orders | 创建订单 {items:[{productId,qty}]} |
| GET | /api/orders/me | 我的订单分页 |
| GET | /api/orders/{id} | 订单详情 |
| POST | /api/orders/{id}/pay | 模拟支付成功 |
| POST | /api/orders/{id}/cancel | 取消 |
统一响应：
{
"code": 0,
"message": "ok",
"data": { ... },
"timestamp": "2026-08-19T10:00:00+08:00"
}
12.4 五天实施计划
Day 1：骨架与领域模型
| 时段 | 任务 | 产出 |
|---|
| 上午 | 初始化项目、docker-compose MySQL+Redis | 可启动空应用 |
| 下午 | User/Product/Order 实体与 Repository | 表自动创建 |
| 晚上 | 种子数据 CommandLineRunner（dev） | admin 账号可登录 |
验收：GET /actuator/health 为 UP。
Day 2：安全与商品 API
| 时段 | 任务 | 产出 |
|---|
| 上午 | Spring Security + 登录注册 | /api/auth/* |
| 下午 | Product CRUD + 统一 Result | ch07 错误码 |
| 晚上 | 商品列表分页与 keyword 搜索 | MockMvc 2 条用例 |
验收：GET /api/products 无需登录；POST 需 ADMIN。
Day 3：订单与上传
| 时段 | 任务 | 产出 |
|---|
| 上午 | 创建订单、库存校验 | 库存不足返回业务错误 |
| 下午 | 我的订单、模拟支付/取消 | 状态机正确 |
| 晚上 | MultipartFile 封面上传 + Profile | ch08 完成 |
验收：完整下单流程 curl 可跑通。
Day 4：横切能力
| 时段 | 任务 | 产出 |
|---|
| 上午 | AOP 耗时 + ACCESS 日志 + traceId | ch09 |
| 下午 | Redis 缓存商品详情 + @CacheEvict | ch10 |
| 晚上 | @Async 订单通知 + 定时关单 | 日志可见异步 |
验收：第二次读商品详情无重复 SQL。