宠物用品商城这个题目，放到Spring Boot项目里几乎是每个学Java的人绕不开的一道坎。选了它的人，基本都能说出一串理由：业务链路完整、前后端交互典型、数据库设计有发挥空间、答辩时有东西可讲。但真正把它从"能跑"做到"能看、能答辩、能演示完整闭环"，中间踩坑的点其实比想象中多得多。这篇文章把我做这套基于Spring Boot的宠物用品商城网的完整思路、核心模块实现、文档怎么写、坑怎么避，一次性讲透。
1. 项目概览与核心定位
1.1 这个宠物商城解决了什么问题
先说这个项目到底在做什么。宠物用品商城网，本质上就是一个B2C电商系统，用户端能注册登录、浏览商品、加购物车、下单支付，管理员端能管理商品分类、上下架商品、处理订单。业务模型和淘宝京东这类平台是同构的，只是把商品域换成猫粮、狗粮、宠物玩具、洗护用品这些垂直品类。
选择这个题目做Spring Boot练手或毕设，最大的价值在于它的业务链路足够完整。一个商城项目会自然地牵出用户体系、商品体系、订单体系、支付回调、库存扣减这一整套电商核心逻辑，比单纯的CRUD管理系统有嚼头得多。同时，宠物用品这个垂直领域又有自己的特性：商品类目区分度明显（食品、玩具、医疗保健、服饰）、商品详情需要图文描述、用户对宠物信息的关联需求（比如按宠物品种推荐用品），这些都能在项目里做出差异化亮点，不至于落成千篇一律的"图书管理"。
从技术角度看，这个项目覆盖了Spring Boot最常见的生产级能力：RESTful接口设计、Spring Security或JWT做认证、MyBatis Plus操作MySQL、Redis做缓存、文件上传、全局异常处理、接口文档生成。做完这一套，你对一个企业级Java后端项目的认知会是完整的，不是片面的。
1.2 适合谁参考这套方案
这个项目的源码和文档适合三类人：
第一类是课程设计要求做Java Web项目的学生，需要的是一个结构清晰、模块完整、能讲清楚设计思路的参考实现。第二类是准备毕业设计的学生，需要的是有业务深度、有技术亮点的项目来支撑论文和工作答辩。第三类是刚工作不久、想找个练手项目梳理Spring Boot知识体系的初级开发。
这套方案里，我把代码组织和文档结构都按照"能直接拿去改、拿去讲"的标准来规划。你不需要从零设计表结构和接口，拿到之后改改包名、换换业务字段、加两个自己的功能，就能变成一个带着自己思考痕迹的项目。这也是我反复强调的一个观点：参考源码不是让你照抄，而是让你站在一个完整的设计之上，去做增量。
1.3 源码加文档这套交付形态怎么用
这个项目以"源码+文档"的形式交付，原因很实际。源码解决的是"怎么做"的问题，文档解决的是"为什么这么做"和"怎么跑起来"的问题。很多人在拿到项目源码后第一反应是打开IDEA直接Run，然后被一堆报错劝退。文档的价值就是提前把环境要求、数据库初始化步骤、配置文件修改点、启动顺序写清楚，让你在动手前就知道会发生什么。
我见过太多人写文档就是贴一张ER图加一段"系统采用B/S架构"的空话。真正有用的项目文档应该包含：项目简介与功能清单、技术栈说明、环境准备、数据库脚本说明、配置文件解释、启动步骤、核心接口列表、项目结构说明。这套东西看起来琐碎，但恰恰是答辩和接手维护时最救命的内容。后面我会专门用一个章节讲文档怎么写。
2. 技术选型与架构设计
2.1 后端技术栈的选型逻辑
后端以Spring Boot为核心，这个选择没什么好纠结的，它已经是Java后端的事实标准。具体到版本，如果你是用Spring Boot 2.x，对应的JDK 8或11，生态最成熟，遇到问题搜解决方案最容易；如果你愿意用Spring Boot 3.x，那就要搭配JDK 17以上，整体更现代，但部分老教程和第三方组件的适配要留意。我在这套源码里用的是Spring Boot 2.7.x加JDK 8的组合，理由很简单：兼容性最好，学生在自己电脑上部署时踩坑最少。
持久层我选了MyBatis Plus而不是原生MyBatis或Spring Data JPA。原因有三：第一，MyBatis Plus的单表CRUD几乎不用写SQL，开发效率高，适合这种业务相对规整的商城项目；第二，它的分页插件、条件构造器在商品列表筛选这种场景下非常好用；第三，国内绝大多数企业的Java技术栈就是MyBatis系，做完这个项目去公司上手成本低。当然，如果你特别想在文档里展示复杂SQL能力，可以在订单统计、销量排行这类报表场景手动写XML，这也是一个很不错的亮点。
数据库用MySQL 5.7或8.0都可以，配合Druid连接池和druid监控页面，能在答辩时多一个可视化看板。缓存层加了Redis，主要用在两方面：一是首页轮播图和热门商品的热点数据缓存，二是购物车在未登录状态下可以用Redis做临时存储。这两个使用点不复杂，但能体现你对"缓存解决什么问题"是有真实理解的。
2.2 前端交互方案与接口联调方式
前端我采用的是前后端分离的Vue 3加Element Plus组合，而不是传统的Thymeleaf模板渲染。前后端分离有几个实际好处：接口调试时逻辑清晰，前端项目可独立部署，演示时可以用Vue脚手架自带的代理转发解决跨域。这套源码里前端项目放在单独目录，通过package.json里的代理配置把/api开头的请求转发到后端的8080端口，开发体验非常顺畅。
不过我要提醒一句：如果你的目标环境是纯课程设计，且老师要求单体架构、传统Java Web结构，被迫用Thymeleaf也不是不行。但从做项目和写简历的角度，前后端分离是当前主流，付出一点学习成本是值得的。前端不需要你自己写得有多花哨，Element Plus的表格、表单、弹窗、分页组件拉起来就是一套很规整的后台管理系统，用户端页面配合商品卡片和购物车交互，视觉上已经完全够用了。
接口文档我用了knife4j，它是Swagger的增强版，界面比原生Swagger UI好看得多，支持接口调试和参数说明。只要在Controller上加好注解，Knife4j会自动扫描生成文档，这对联调和后期写文档都是效率翻倍的事情。
2.3 数据库设计：核心表与关键字段
商城系统的数据库设计决定了整个项目能走多远。我设计核心表的时候遵循了一个原则：表可以不多，但字段设计必须经得起追问。整套数据库一共八张核心表：用户表、商品分类表、商品表、购物车表、订单表、订单明细表、轮播图表、地址表，外加中间性质的表（比如收藏表）。
用户表重点包含用户名、密码（BCrypt加密存储，绝对不能明文）、手机号、邮箱、头像、角色标识（区分普通用户和管理员）。密码加密这一点，答辩时基本必问，你要能说出为什么不加密的危险性以及BCrypt强度可配置的原理。
商品表是信息量最大的表，包含商品名称、所属分类ID、主图、轮播图、详情描述、价格、原价、库存、销量、上下架状态、创建时间。这里有个容易犯的错：把库存做成Integer后直接在代码里扣减，不做乐观锁处理。我在项目里用version字段做乐观锁，并在扣库存时用update ... where id=? and stock>=? and version=?这种条件更新，这是高并发场景下防止超卖的基础手法。
订单表和订单明细表是分开设计的，一个订单头存总金额、状态、收货信息、下单时间、支付单号；订单明细存每个商品的单价、数量、小计。这样做的好处是同一个订单买了多个商品时，明细能清晰记录快照信息——注意，商品价格和名称必须冗余到订单明细里，因为商品表将来可能改价或改名，订单历史不能跟着变。
3. 核心业务模块拆解
3.1 用户注册登录与JWT认证
用户模块是整个商城的入口，做的质量直接影响后续所有接口的安全性。我选了JWT做无状态认证，没有引入复杂的Spring Security全家桶，而是用拦截器加JWT工具类的轻量方案。原因是在商城这种场景下，Spring Security的过滤器链对初学者来说黑盒感太强，一旦配置错了很难排查，而拦截器方案逻辑直白，代码量少，出了问题你能一眼看穿。
注册流程里做了三层校验：前端表单校验、后端参数校验（通过@Valid注解加自定义正则）、数据库唯一性校验。用户名和手机号都要做唯一索引，这是数据库层面的最后一道防线。注册时密码用BCrypt加密再入库，登录时用BCrypt的matches方法比对原文和密文。这里有个细节：不要在数据库里存MD5或SHA256这种可逆查表的散列值，BCrypt内置随机盐，同样的密码每次加密结果都不同，安全性高一个量级。
登录成功后在服务端生成JWT，就是把用户ID和角色塞进token里，设置7天的过期时间，然后返回给前端。前端把token存到localStorage，每次请求在拦截器里加上Authorization: Bearer xxx头。后端写一个LoginInterceptor，只拦截需要登录的路径，放行登录注册接口和商品浏览接口，通过@Autowired注入的工具类解析token失败时直接返回401。管理员接口再在拦截器里加一个角色判断，权限粒度虽然不细，但够用。
3.2 商品浏览、搜索与分类
商品模块是用户进来第一个接触的功能，体验好不好就看这一个模块。首页要展示轮播图和精选商品，轮播图我做了缓存，因为它是全站访问频率最高的数据之一，每次都查数据库太浪费。商品列表页需要支持分类筛选、关键词搜索、价格排序、分页展示，这里用MyBatis Plus的条件构造器非常顺手。
分页参数我统一用pageNum和pageSize，排序字段通过白名单机制控制，不让前端任意传入排序字段字符串拼进SQL，防止注入。分类表设计成两级：大类（猫用品、狗用品、小宠用品）和小类（猫粮、猫砂、零食），通过parent_id关联。相对扁平的结构对查询更友好，真要做无限级分类，递归查询的复杂度和收益在小项目里不成正比。
商品搜索如果数据量大，用LIKE '%关键词%'会全表扫，这是性能隐患。但商城项目常规数据量下，只要在商品名称字段建了普通索引，配合前端做防抖和必要的分页限制，体验完全能接受。文档里我会明确标注这个取舍，答辩时如果被问到，你也能解释清楚为什么没上Elasticsearch——不是不会，而是当前数据规模用不上，属于合理的技术选型而非能力缺失。
3.3 购物车与下单流程
购物车是商城项目里埋坑最多的地方。我采用的方案是登录状态下购物车数据存数据库表，关联用户ID和商品ID，数量可增减。用户点加入购物车时先查是否已存在同款商品，如果存在就数量加一，否则新增一条记录。这个逻辑简单，但要处理好品控：每次查询时要把商品的最新价格和上下架状态带出来，避免用户加购后商品下架还显示在购物车里。
下单流程是整套业务里最值得在文档里画流程图的部分。流程是：购物车选中商品生成订单预览，回显商品信息和收货地址，用户提交订单，后端做三步校验（商品是否存在并上架、库存是否充足、价格是否与数据库一致），扣减库存，生成订单头和订单明细，清空对应购物车记录。这里价格必须以数据库查询为准，不能用前端传来的价格，不然一个恶意请求就能把商品改成0元下单。
订单状态我用一个数字状态机管理：0待支付、1已支付待发货、2已发货、3已完成、4已取消。所有状态流转都通过后端接口驱动，不允许前端直接改状态。取消订单时如果已支付要回滚库存，这个逻辑容易漏，我在代码里单独抽出recoverStock方法供取消和支付超时共用。关于库存回滚，我在做这个项目时反复验证过场景：用户下单未支付占用库存，超时或者手动取消必须释放，否则库存会越卖越少，这是实际运营里用户一定会投诉的问题。
3.4 后台管理与订单处理
后台管理模块面向管理员，功能包括：商品分类维护、商品上下架、订单列表查询、发货操作、轮播图配置。后台的所有接口在拦截器层面就要求ROLE ADMIN，前端路由也做了守卫，未登录管理员跳登录页。
订单处理要特别讲发货这个节点。管理员点击发货后，订单状态从待发货变为已发货，需要填写物流公司和物流单号。这里不要只更新一个status字段，要把物流信息冗余到订单表里，方便用户端随时查看。后台订单列表还需要支持多条件筛选：按订单号精确查、按状态查、按下单时间区间查。这些筛选场景在MyBatis Plus里用LambdaQueryWrapper的and条件组合即可，多写几个if判空就是一套完整的高级查询。
商品上下架尤其要注意与购物车、订单逻辑的联动。下架商品后，用户在商品页看不到它，但在购物车里可能还有历史记录。所以在查询购物车接口里要过滤掉已下架商品，并给前端返回一个标识让用户知道哪一件已失效。这个细节我在初版开发时漏掉过，后来测试发现购物车里出现了下架商品，才补上的过滤逻辑——类似这种小问题其实最能体现一个开发者对业务闭环的敏感度。
4. 核心代码实现与实操要点
4.1 项目初始化和目录结构怎么组织
拿到源码之后第一步不是看代码，而是先把项目结构认识清楚。我的后端包结构采用controller、service、mapper、entity、common、config、utils这套经典分包方式。common下面放统一返回结果Result类、异常处理器、常量类；config放拦截器注册、跨域配置、Knife4j配置；utils放JWT工具、文件上传工具。这样的结构在答辩时特别加分，因为面试官或老师一眼就能看出你是有工程化意识的，不是所有类堆在Controller里。
controller层只做参数接收和结果返回，不在里面写业务逻辑；service层是核心业务承载，事务注解加在需要保证原子性的方法上；mapper层就是MyBatis Plus的BaseMapper，复杂SQL走XML。分层清晰的第一个红利是出了问题你知道去哪里找，第二个红利是写文档时能照着结构讲，一张包结构图就能讲半小时。
代码里还有几个全局约定：接口路径统一以/api开头，用户端接口叫/api/user下的子路径，后台接口叫/api/admin下的子路径；所有接口返回统一封装成Result对象，包含code、message、data三个字段，前端根据code判断请求成败。约定统一的好处是前端处理逻辑简单，不用每个接口单独写异常分支。
4.2 统一响应与全局异常处理
统一响应和全局异常处理这两个东西，很多人觉得是花架子，实际作用是实打实的。如果没有全局异常处理，你的代码里就要到处写try-catch，前端拿到的报错信息要么是500白屏要么是一堆看不懂的堆栈。我在项目里用@RestControllerAdvice统一捕获异常，业务异常返回400加具体提示，SQL异常返回500加日志记录，兜底异常返回"系统繁忙"。
业务异常我自定义了一个BizException，继承RuntimeException，带code和message。比如库存不足、商品已下架、密码错误这类情况，直接在service里throw出来，由全局处理器转换成统一格式响给前端。这样做最直接的好处是Controller代码极简，没有任何一个catch块，阅读起来非常清爽。
全局异常处理器里还要区分状态码。401表示未登录或token过期，403表示无权限，前端拦截器收到401会跳转登录页并清除本地token。这个联动设计让登录失效的体验是流畅的，而不是报一个莫名其妙的错误。日志方面用Slf4j注解打关键操作日志，尤其是支付回调、订单状态变更这种敏感操作，出问题时能追溯。
4.3 商品图片上传的落地方案
图片上传是商城必备功能，也是初版项目里坑最多的地方。我的方案是后端提供一个上传接口，接收MultipartFile，校验文件类型和大小（只允许jpg、png、webp，单张不超过2MB），然后把文件写到服务器本地的一个upload目录，文件名用UUID重新生成防止重名。返回给前端的是一个能直接访问的URL路径。
本地存储的局限是显而易见的：应用重启后文件丢失、多实例部署时文件不同步。但作为课程设计和单体项目，它是最务实的选择，因为你不需要引入OSS对象存储服务，不用配密钥，也不牵扯额外费用。我建议在代码层面把存储逻辑抽成一个FileStorage接口，本地实现和OSS实现可以互换，这段设计的抽象层次在答辩时是一个很好的技术亮点。
文件上传还有两个配套要点：一是上传目录要在配置里可配置，不能硬编码在代码里；二是要配置静态资源映射，把/upload/**路径映射到实际文件目录，否则前端拿到的URL会404。这一点我在给几个朋友做review时发现他们经常漏掉，Spring Boot默认只映射classpath下的static目录，你写到磁盘上的文件不加映射是访问不到的。
4.4 模拟支付与订单回调的实现
真实商城对接支付宝或微信支付，需要商户号、证书、回调验签，这些对学习项目来说门槛太高也没有必要。我用的是模拟支付方案：用户点支付后，跳到一个写死的模拟支付页面，页面上显示应付金额和"确认支付"按钮，点击后后端直接将订单状态改为已支付，并记录支付方式和支付时间。
虽然逻辑简单，但我在设计上尽量逼近真实支付流程。支付成功后不是直接改状态了事，而是模拟了回调通知的入口：一个支付回调接口，业务处理和用户主动查询支付结果场景解耦。这样做的好处是，将来想对接真实支付，你只需要把模拟回调替换成微信/支付宝的异步通知接口，业务逻辑完全不用动。
模拟支付里有个细节值得一提：用户下单时订单表里生成了orderNo和订单金额，支付接口要做的第一件事是校验订单归属，防止A用户支付B用户的订单。校验方式是把订单创建时绑定的userId和当前登录token解析出的userId比对，不一致直接提示非法操作。这个越权校验在文档里我专门写了一节，因为它是电商系统安全测试的高频考点。
5. 文档撰写与源码交付经验
5.1 项目文档应该包含哪些内容
拿到源码之后很多人不知道配套文档该怎么写，要么堆功能截图，要么全是概念。我写这套项目的技术文档时定的原则是：让一个没看过代码的人，照着文档能跑通项目，并理解核心设计。文档结构我拆成了八部分：项目概述、功能清单、技术架构、环境要求、快速启动、核心模块设计、接口说明、测试数据说明。
快速启动这一章是文档里最重要的部分，我会写明需要安装JDK8、Maven 3.6+、MySQL 5.7+、Redis（可选），然后按步骤执行：创建数据库、导入sql脚本、修改application.yml里的数据库账号密码、启动后端、启动前端、访问地址。每一步都给出预期结果，比如启动成功看到什么日志、访问哪个URL能看到首页。你在写自己项目的文档时也应该这样要求自己。
数据库初始化脚本我放在sql目录里，包含建库语句、建表语句、初始数据。初始数据里我准备了几个分类、十几件商品、一个管理员账号和一个测试用户账号。这个细节很关键，因为如果评审老师按文档操作后打开项目是空数据的，体验会大打折扣。测试账号密码写清楚，管理员账号的角色标识也要有对应的插入语句，否则你登录后进不了后台。
5.2 接口文档和数据库说明怎么梳理
接口文档我用Knife4j自动生成，但仅仅依赖注解生成还不够，需要配套一份手动整理的接口清单，写明每个接口的请求方式、路径、参数、返回示例。这份清单不需要覆盖所有接口，但核心链路必须完整：注册、登录、商品列表、商品详情、加购、购物车列表、提交订单、模拟支付、后台发货。
在知识层面你会遇到一个常见疑问，就是接口文档是否完整就代表项目文档合格。我的回答是不够的。数据库设计说明一定要单独写，每张表给一句话的业务说明，关键字段举例说明。比如订单表的status字段，要写清楚0到4分别对应什么业务含义。答辩时老师非常喜欢针对表设计发问："这个字段为什么这么设计""那个状态为什么不在前端判断"。提前用文档把这些问题捋清楚，现场就不会慌张。
5.3 源码交付前要做好的清理和规范
源码交付有一个经常被忽视的处理：清理本地环境信息。电脑上的application.yml里可能带着你本地的数据库密码、文件路径、端口配置，交付前要把这些改成通用的占位值，改成你自己的数据库配置要写进文档里让别人改。另一个要清理的是IDE的本地配置文件，.idea、target这类目录不要打包进去，用.gitignore管理好。
代码规范同样要在交付前过一遍。统一字段命名（驼峰）、统一缩进、删掉注释掉的垃圾代码、给核心业务方法写中文注释。这些看起来是表面功夫，但对阅读体验的影响非常大。我见过太多源码里充斥着System.out.println和半截注释，这样的代码即便是功能完整的，给人的专业感也很差。代码是给人读的，文档是给人看的，这两者就是项目的门面。
6. 常见问题排查速查表
开发这个项目时我在本地反复部署、反复测试，把最容易出问题的环节整理成了一个排查清单，对初学者来说照表操作能省大量时间。
第一类问题是启动失败。常见的报错有端口被占用、数据库连不上、Redis未启动。端口被占用时，修改application.yml里的server.port或者杀掉占位进程；数据库连不上先ping一下是不是账号密码写错了，再确认MySQL服务有没有启动。Spring Boot启动时的日志是最直接的定位工具，看到什么级别的报错就去解决对应的配置项。
第二类问题是数据库时区与编码。连接MySQL时，URL里必须带useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai，否则中文数据会乱码，时间字段可能差8个小时。数据乱码是本地环境和线上环境最常见的差异问题，在文档里我把它写成了一条强制配置，建议你在自己的项目里也统一加上。
第三类问题是前端跨域。前后端分离开发时，前端页面访问后端接口，浏览器会拦截跨域请求。解决方式有CORS全局配置和后端放行。我用了Spring Boot的CorsFilter配置，允许本地开发端口访问。另一个常见做法是前端通过Vite或Webpack代理转发，两者选一种即可，但不要同时配，否则会出奇怪的请求异常。
第四类问题是MyBatis Plus相关报错。实体类字段名和数据库字段名不一致导致查询结果为空，这个非常容易踩。MP默认开启驼峰转下划线，userName会映射user_name，但如果你数据库字段就叫username，那就要用@TableField注解指定。还有updateById传了null值字段会更新为空，这也要注意用条件构造器或update策略控制。
第五类问题是JWT相关的权限报错。表现为登录后访问接口一直返回401，常见原因是token没传或者传错了Header名。前端拦截器要统一在请求头加Authorization字段，格式是"Bearer 空格加token"，后端解析时按这个格式去取。还有一个隐蔽的问题是token过期时间太短，用户操作一会儿就掉线，建议开发环境设置成24小时，答辩演示时不会突然掉登录态。
总结一个我自己排查接口问题的习惯：先看后端日志，再看网络请求的请求头与响应体，最后看数据库实际数据。这三步能定位绝大多数问题，比盲目改代码高效得多。如果后端日志里没有任何输出，那问题多半出在请求根本没到达后端——检查前端代理配置和请求地址。如果到了后端却报错，那把异常堆栈贴到搜索引擎里，基本上都能找到答案。
这个项目做完之后，我最大的感受是：商城类项目真正的技术难点不在某个单独的技术点，而在整个业务链路的状态一致性。从加购到下单到库存扣减到支付回调，每一步都有边界条件需要处理，而这些边界条件恰恰是文档里最值得写、答辩时最值得讲的内容。如果你正在参考这个项目做自己的毕设或练手，建议不要停留在让它跑起来的层面，花时间把订单状态流转和库存扣减的边界条件捋清楚，再把文档里的设计思路换成自己的话讲出来，这个项目的价值就真正落地了。
