最近完成了苍穹外卖项目的第一个学习阶段正好趁热打铁把这几天的踩坑和收获整理出来。作为一套非常接近真实企业级的外卖系统教学项目它把前端、后端、管理端、用户端串在了一起尤其是“苍穹外卖本地上传图片”这个功能我在做的时候反复折腾了好几次今天这篇日记就把核心知识点、实现步骤和遇到的坑一次性说清楚。如果你也是刚把Spring Boot学了七七八八、想找一个综合项目练手的人这篇学习日记应该能帮你少走不少弯路。1. 项目整体认知苍穹外卖到底在练什么1.1 为什么这个项目值得跟练说句实在话Spring Boot学完之后最大的困惑不是语法不会而是不知道真实系统里那一堆东西怎么串起来。苍穹外卖恰好解决了这个痛点。它包含管理端和用户端管理端给商家用用户端模拟C端下单两边业务是打通的一个闭环。从店铺营业状态、菜品管理、分类管理到微信登录、购物车、下单支付再到订单状态流转和管理员端的数据统计报表基本覆盖了互联网外卖业务的一整条链路。我第一次打开项目文档的时候先看了它的数据库设计总共好几十张表光订单相关就分了订单表、订单明细表、地址簿、购物车等好几张。当时心里是有点慌的但真正跟下来才发现表再多也是围绕主流程拆出来的理解了业务主线之后表之间的关系会自然变得清晰。这个项目能让我把之前零散的知识点统一在一个场景里用起来这是它最大的价值。1.2 技术栈拆解与模块划分苍穹外卖是典型的前后端分离结构后端用的技术栈跟我自己平时练的比较贴合基础框架Spring BootORMMyBatis部分版本用MyBatis-Plus数据库MySQL缓存Redis主要存用户登录状态、购物车临时数据等对象存储方案本地磁盘存储 阿里云OSS不同版本有差异接口文档Swagger或Knife4j项目里用的是Knife4j的增强版本权限认证JWT前端部分分两个角色管理端用的Vue ElementUI用户端是小程序接口调试用HBuilderX打开小程序工程。这里我建议不要纠结前端技术细节看明白接口怎么调、请求头里带什么内容就够了重心还是放在后端的业务实现上。模块划分也很清楚controller层拿参数、service层做业务逻辑、mapper层写SQL再加一个common模块放公共类、utils放工具类。我第一次跑起来之后特意梳理了一遍包结构发现它跟很多公司的真实项目分层方式几乎一样照着这个结构去理解其他项目也会快很多。2. 环境搭建与项目启动先把地基打牢2.1 环境与版本选型心得环境这块我觉得有必要记录一下。苍穹外卖用的是前后端分离前端工程有两个一个管理端、一个用户端后端工程是标准的分模块Maven项目。初次建议按顺序做安装JDK、配置Maven我用的是JDK 1.8版本后端工程用的是Spring Boot 2.x这个对应关系不要搞混安装MySQL 5.7或8.x导入数据库脚本。项目里提供了完整的sql文件直接执行就成安装Redis用作缓存服务。启动后端如果报了连不上Redis大概率就是这里没起用VSCode或HBuilderX打开前端工程依赖安装后把接口地址指向本机端口一个容易犯的错是把本机IP和localhost混用。前端工程里有配置请求baseURL的地方如果你是用真机调试小程序那就不能写localhost得换成电脑的局域网IP不然真机上请求发不出去。我第一次就是用localhost跑了半天页面一直报网络错误换成IP后立刻就好。2.2 项目结构初始化重点后端结构上分为sky-server、sky-pojo、sky-common这几个maven模块。刚接触Maven多模块工程时可能会不习惯但它的好处是公共类统一管理controller和service按业务分包非常清爽。启动配置里application.yml中需要配置MySQL、Redis、阿里云OSS或本地上传开关还有JWT的密钥。这套配置是整个项目能否跑起来的关键。我建议拿到代码之后先把配置和前端页面里对应的接口地址核对一遍保证环境变量全部对上。配置有问题花再多时间调试代码也白搭。启动后端后建议立刻打开Knife4j文档页面验证一遍接口是否都能正常访问看到文档里列出所有controller才算启动成功再接着做功能开发。3. 苍穹外卖本地上传图片功能拆解与代码实现3.1 “本地上传图片”到底解决什么问题在管理端操作菜品时需要为每个菜品上传图片比如菜品的新增、修改页面都需要先传图再提交表单。传统做法是把图片客户端传上来到服务器。这个功能有很多实现方式放OSS上有OSS的写法放本地磁盘上就是本地上传的方式。我做“本地上传图片”的时候发现工程里早就封装了一个FileService接口接口下有一个LocalFileServiceImpl实现类和一个OssFileServiceImpl实现类。默认配置可以通过yml中store.type参数切换用OSS还是本地存储。这个设计很巧妙业务代码只依赖接口具体存到哪由配置决定所以我选型时就先把这个封装的思路吃透了。“苍穹外卖本地上传图片”从本质上讲就是后端提供一个文件上传的接口接收前端提交的MultipartFile对象将文件保存到本地指定目录数据库保存图片的访问路径。之后前端把返回的路径回填到表单里提交菜品信息时一起完成入库。3.2 上传接口设计与代码示例我参考项目里预留的代码结构自己实现了一个通用上传接口处理逻辑分成三步校验文件、存储文件、返回URL。下面是我在苍穹外卖基础上整理出的核心代码RestController RequestMapping(/admin/common) public class CommonController { Autowired private FileService fileService; // 本地上传图片返回可访问的图片路径 PostMapping(/upload) public ResultString upload(MultipartFile file) { // 1. 文件校验非空、大小限制、后缀白名单 if (file null || file.isEmpty()) { return Result.error(文件不能为空); } String originalFilename file.getOriginalFilename(); String suffix originalFilename.substring(originalFilename.lastIndexOf(.)); if (!(.jpg.equals(suffix) || .png.equals(suffix) || .jpeg.equals(suffix))) { return Result.error(仅支持jpg/png格式); } // 2. 调用FileService实现本地上传 String filePath fileService.upload(file); // 3. 返回访问路径 return Result.success(filePath); } }FileService对应的本地上传实现类核心逻辑是构造日期目录、生成唯一文件名、复制文件public class LocalFileServiceImpl implements FileService { Value(${sky.file.local-path}) private String basePath; Override public String upload(MultipartFile file) { try { // 按yyyy-MM-dd创建子目录避免单个目录文件过多 String dateDir LocalDate.now().toString(); File dir new File(basePath dateDir); if (!dir.exists()) { dir.mkdirs(); } // 生成唯一文件名时间戳 随机串 后缀 String originalFilename file.getOriginalFilename(); String extension originalFilename.substring(originalFilename.lastIndexOf(.)); String newName UUID.randomUUID() extension; // 写入本地文件 file.transferTo(new File(dir, newName)); // 返回可访问的相对路径 return /upload/ dateDir / newName; } catch (IOException e) { throw new RuntimeException(文件上传失败, e); } } }有的版本把这一块直接写在controller里但我自己更偏向用工程里的FileService接口来做这样后续想切换到OSS时不用动controller代码。这里的重点在返回路径的设计一定要返回带目录的完整相对路径这样前端可以直接拿这个路径拼成完整URL用来展示图片而不是只返回一个文件名。3.3 本地目录映射与配置细节图片保存到本地后怎样才能让前端通过URL直接访问到答案是要设置静态资源映射。Spring Boot默认把static目录作为静态资源目录但你传到自定义目录后就需要通过配置或代码把URL和磁盘路径映射起来。我当时就在application.yml里加了前缀配置sky: file: local-path: /Users/你的用户名/upload/然后在启动类或配置类中加上资源映射逻辑把“/upload/”对应的URL映射到本地的“/upload/”目录Configuration public class WebMvcConfiguration implements WebMvcConfigurer { Value(${sky.file.local-path}) private String uploadPath; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/upload/**) .addResourceLocations(file: uploadPath); } }这一段我卡了小半天。一开始写完之后文件确实存到了本地但前端怎么都访问不到后来检查才发现是我映射路径写错了file:后面的路径必须以右斜杠结尾Windows上尤其容易踩这个坑。改完之后在浏览器里直接输入图片URL就能打开那一刻才算是真正跑通了。这个“本地上传图片”功能表面上看就是把一个图片从请求体里存到磁盘再返回一个路径但真正把它放到一个完整业务系统里要考虑存储目录结构、文件重名、静态资源映射、格式校验、大小限制、切换存储方案的可扩展性等等。把这些点一个个想明白比单纯背一套上传代码有价值。4. 核心业务与状态流转的串联理解4.1 店铺营业状态与Redis缓存做了图片上传之后我开始往后端核心业务推进。第一个让我有收获的是店铺营业状态接口。管理端可以修改营业状态用户端需要查询当前店铺是否在营业中。如果按传统思路每次查询都去读写数据库虽然可以但不够好。苍穹外卖的做法是把营业状态放到Redis里修改时更新Redis查询时读Redis利用Redis的高性能来承载高频读取请求。具体实现时定义了一个常量KEY比如“SHOP_STATUS”value用数字0或1来表示打烊/营业。转换Redis中状态时注意序列化问题项目里一般会配置RedisTemplate的序列化器。如果直接用默认的JdkSerializationRedisSerializer存字符串再取出来会有乱码或者强转类型时直接报错。这个问题在几乎所有用了Redis的Spring项目中都会遇到值得认真排查一遍。4.2 分类管理与菜品信息的增删改查菜品管理是整个管理端最核心的模块也是跟图片上传衔接最紧密的模块。新增菜品时需要填分类、名称、价格、口味和图片路径这里的图片路径就是上传接口返回的值。新增菜品和新增套餐在很多版本里是分开的但都会维护一张分类表分类里包含菜品分类和套餐分类。我在写这块时比较留意的是菜品状态字段。每道菜有一个status0表示停售1表示起售。起售的菜品才能出现在用户端的点餐列表里。菜品分类也一样如果分类里还有菜品或套餐就不允许删除分类否则会牵连到已有订单数据或展示数据。这些业务限制看起来琐碎但才是真实的业务逻辑练习很值得逐条抄进自己的笔记里。4.3 订单流转从下单到支付再到达成的状态机订单模块是这个项目里最复杂的部分。我刚开始直接打开订单controller看接口的时候差点被Order、OrderDetail、ShoppingCart三张表绕晕后来按流程拆开才理清楚用户选菜加购物车购物车数据可存Redis或数据库表提交订单前根据购物车明细组装Order和OrderDetail生成订单号、设置金额、状态为待支付支付成功后修改订单状态为待接单商家端接单后状态改为待派送或制作中派送中、已完成、已取消各种状态之间有明确的前置条件为了理解状态流转我直接在笔记里画了一张脑图风格的记录把每个状态转移对应到具体接口上。这样当我看到“商家拒单”或“用户取消”这样的接口时就知道它内部其实就是一次条件校验加状态更新加上可能的库存或流水扣减。实际项目中订单状态流转还会有更多分支但基于这个项目先掌握主干已经大有收获。5. 我的常见问题与排错笔记5.1 本地上传图片相关的QA速查为了以后遇到问题能快速回忆我把碰到过的和网上很多同学提到的典型问题整理成了速查表问题现象可能原因解决方案上传后浏览器404静态资源映射未配置在配置类添加addResourceHandlers映射上传后文件夹找不到图片basePath路径带中文字符或权限不足换纯英文目录并确认目录可写前端无法显示本地图片baseURL填的是localhost真机访问不到改为局域网IP文件名重复导致覆盖直接使用了原名用UUID或时间戳重命名文件格式导致前端预览不了大文件或非图片格式通过限制文件大小和后缀Windows路径打不开file:后面路径末尾没有斜杠补上斜杠并检查反斜杠比如Windows本地上传时上传目录使用反斜杠和正斜杠的问题File类一般能兼容但是URL映射上是需要file:绝对路径格式。为了省事我最后统一约定用正斜杠直接避免了很多跨平台路径的坑。5.2 在调试过程中学到的排查方法之前练习写代码遇到报错第一个动作就是去搜报错信息。这次做项目我慢慢改变了习惯遇到问题会先看日志栈再针对性地打断点。举一个例子我在做登录接口时一直出现“校验失败”的提示。一开始以为是JWT生成逻辑写错了后来打断点排查才发现是前端请求头里的参数名和后端拦截器读取的参数名不一致导致token拿出来是空串。如果一开始就盲搜很难快速定位到这种两边字段不匹配的低级问题。再比如说菜品分页查询接口返回总是少几条数据最后发现是SQL里category_id与分类表的关联条件写错了一个别名。这种问题在SQL控制台去执行一遍原句很容易暴露。我建议跟我一样基础不是特别扎实的同学遇到查询结果不符合预期时第一时间把日志里打印的SQL复制到数据库工具里跑一遍用真实数据对照着看基本能筛掉大部分由于SQL条件或关联导致的bug。另外值得一提的价值是项目的日志系统。苍穹外卖默认集成了logback的配置接口执行耗时、SQL日志都能在控制台看到。我在学习的过程中有意记录了每个接口在耗时上的表现比如带缓存和不带缓存的查询接口日志里对比就非常直观。对一些明显耗时的接口会去思考是不是有多余的for循环查询或者一条SQL能解决的非得拆成多次请求。这些其实是大型项目里的性能优化基本功远比单纯把功能跑通更有意义。6. 一些实用心得和新手易踩的坑6.1 不要过度依赖自动生成代码刚开始做苍穹外卖的时候我因为经常用MyBatis-Plus就想所有的增删改查都用它封装好的方法。后来发现这个项目有不少查询是多表关联或者在SQL里做了复杂的条件拼接如果依赖自动生成的方法反而绕。跟着手写XML里的SQL过了一遍我对动态SQL标签的掌握才真正上了一个台阶。现在回看用苍穹外卖学MyBatis的SQL写法是非常值的。比如where标签里如何正确拼接条件set标签怎么处理动态更新字段foreach怎么传集合参数这些都是实际工作中非常高频的场景。项目里那些看起来重复的mapper方法每一个都比直接在注解里写SQL更容易调优和维护我强烈建议初学者多看看XML的实现。6.2 前后端联调时注意请求体和请求头在管理端配置菜品页面时可能遇到新增成功但数据对不上的问题。后来发现是前端把图片路径放在formData里而后端又要求JSON两边字段格式没对齐。我自己的习惯是联调之前先把Knife4j里每个接口的请求示例看一遍确认参数类型是query、path还是body然后再去看前端代码传的是什么。只要两边对齐了大部分联调问题都能避免。6.3 多花时间理解JWT拦截器别只照着抄苍穹外卖在登录之后会返回一个JWT token后续所有请求都在请求头里带着这个token后端通过拦截器做统一校验。这个模块值得认真看。我第一次看拦截器代码时以为只要配置一个注册拦截器的类就行后来才发现还需要考虑白名单比如登录接口、店铺营业状态接口这些必须放行否则用户还没登录就没法看店铺状态了。项目里是通过一个路径列表来配置不需要拦截的URL的理解了这个机制之后再去看权限控制相关的需求就很轻松。如果我们只是照着抄配置把项目跑起来那可能只学会了复制粘贴但如果把拦截器执行顺序、token解析、用户信息放入ThreadLocal这几个点都理解了以后再写项目权限控制就会顺手得多。我自己在学完这一段后回顾之前自己写的小项目才发现当时根本没考虑过后端接口被绕过校验的风险现在再看就明白多了。6.4 记录笔记和代码提交的习惯这次跟练我给自己定了两个规矩一是每天结束前把当天的报错和解决思路记录到一个md笔记里二是在理解一个模块之后再用自己的话重构一遍相关的类和方法。这两个习惯的第一个作用是不让bug白踩第二个作用是逼迫自己检查是不是真的懂了。比如我学完员工管理模块的修改密码功能后自己尝试写了一个类似的密码重置接口在写的过程中发现需要额外处理参数校验的问题。这个时候我就意识到自己刚开始看代码时忽略了一些边界情况。搭这样一个项目最大的收获其实就是“知道一个项目真实长什么样”很多默认小事参数校验、统一返回对象、异常拦截、日志打印会在这个过程中慢慢变成自己的肌肉记忆。7. 这个项目的后续扩展方向如果你已经把苍穹外卖的整个主流程走完我建议尝试几个方向会让收获更大把本地上传图片切换为OSS存储对比两种存储方式的代码差异和优缺点。尤其是URL访问路径、前端回显过程切换后业务流程应该无感知这才是好的封装设计给订单模块加一个超时未支付自动关闭的定时任务可以用Spring Task或MQ延迟消息实现理解定时任务在业务系统里的真实落地场景把项目的分页查询从纯数据库分页结合Redis或加一层缓存对比查询性能日志的变化做一些简单的压测看看Tomcat默认配置下高并发请求的接口耗时和错误率变化再尝试调优线程池、数据库连接池拿我自己来说第一个计划就是把本地上传图片切换到OSS实现。因为接口层封装好了FileService我的切换成本很低这也让我体会到设计模式在真实工程里的价值——对应了我之前在学习工厂模式时有点抽象的理解。总的来说苍穹外卖这个项目非常适合用来打通“从接口到数据库再到前端展示”的完整链路。它的难度曲线比较平缓但涉及的知识点密度很高。如果你正准备找一个项目练手或者跟了一段时间觉得停留在表面不妨按我上面提到的方式把每一个模块都拆开再看一遍重点把图片上传、Redis缓存、JWT拦截器和订单状态流转吃透。最后再分享一个实用的收尾习惯每学完一个子模块就自己在纸上不看代码画一遍它的请求流程、表设计和工作原理画不出来就回头再看代码。我在做订单模块时用这个方法发现了不少“假懂”的地方补完之后整个项目就通透了。