宠物用品商城这个题目放到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里必须带useUnicodetruecharacterEncodingutf8serverTimezoneAsia/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小时答辩演示时不会突然掉登录态。总结一个我自己排查接口问题的习惯先看后端日志再看网络请求的请求头与响应体最后看数据库实际数据。这三步能定位绝大多数问题比盲目改代码高效得多。如果后端日志里没有任何输出那问题多半出在请求根本没到达后端——检查前端代理配置和请求地址。如果到了后端却报错那把异常堆栈贴到搜索引擎里基本上都能找到答案。这个项目做完之后我最大的感受是商城类项目真正的技术难点不在某个单独的技术点而在整个业务链路的状态一致性。从加购到下单到库存扣减到支付回调每一步都有边界条件需要处理而这些边界条件恰恰是文档里最值得写、答辩时最值得讲的内容。如果你正在参考这个项目做自己的毕设或练手建议不要停留在让它跑起来的层面花时间把订单状态流转和库存扣减的边界条件捋清楚再把文档里的设计思路换成自己的话讲出来这个项目的价值就真正落地了。