接手苍穹外卖这个项目差不多是每个Java后端学习者都会经历的一道坎。Day 1看起来只是搭环境、理需求但恰恰是整个项目成败最容易被低估的一天。我带过不少学员第一天顺顺利利的后面代码写得飞快第一天糊里糊涂的等到开发用户端登录接口时再来补课成本就完全不一样了。这篇就把Day 1该做的事、该避的坑、该想清楚的问题一次说透你照着走就行。1. 内容整体设计与思路拆解1.1 苍穹外卖是什么先搞清楚自己在做什么项目苍穹外卖是一套完整的外卖业务系统典型的前后端分离架构。后端基于Spring Boot搭建前端分成用户端小程序/H5和管理端PC后台两条线。你要做的是商家端的后台管理、用户端的点餐下单以及订单流转、支付对接、店铺营业状态管理这些核心业务。技术栈上Spring Boot MyBatis是主体Redis负责缓存和登录状态MySQL存业务数据再配上Nginx做静态资源访问和反向代理JWT做登录令牌Spring Task做定时任务WebSocket用来推送订单状态——整套下来就是真实企业里外卖类SaaS系统的标准技术组合。Day 1的核心目标不复杂把环境全部搞定把需求完整看懂把数据库搭起来把项目跑起来。听起来简单但很多人栽就栽在跑起来这一步上因为这套系统涉及的服务太多了任何一个环节版本不匹配整个链路就卡住。1.2 Day 1在整条学习路径中的定位很多新手有个误区觉得Day 1没什么技术含量随便看看就行真正的大头在后面。这个想法坑了很多人。我的经验是苍穹外卖的学习曲线是前低后高、中段陡峭到了Day 4接Redis、Day 5上Spring Task定时任务、Day 6搞WebSocket的时候每一块都是新知识叠加。如果Day 1没有把项目骨架和业务流程吃透后面课程里老师讲这里应该更新订单状态因为之前需求分析里已经有这个流程了你就会一脸懵。反过来Day 1做好了你头脑里会建立一张地图用户端和管理端各有什么页面、对应哪些后端接口、数据怎么流转、订单状态怎么变化。后面每天写代码的时候你是在地图上添砖加瓦而不是摸着石头过河。这个差别到项目中期会体现得淋漓尽致。2. 核心细节解析与实操要点2.1 开发环境准备的标准套餐与版本搭配苍穹外卖Day 1环境这块我建议你用一套固定的版本组合别东换西换。我自己带学员时默认推荐开发环节选用方案说明IDEIntelliJ IDEA建议 2022.2 以上版本教育版或社区版也能跑但专业版对Spring Boot的支持更顺手JDK1.8 或 11推荐1.8项目官方教学配置以JDK 8为主新版JDK反而不建议一上来就试构建工具Maven 3.6用IDEA内置的Maven也行但建议确认本地仓库位置数据库MySQL 5.7 或 8.05.7更稳妥8.0需要调整驱动和时区配置缓存Redis 5.x / 6.xWindows版/ Linux版均可注意Windows版最高到5.0.14后续接入Redis时版本别搞混反向代理Nginx 1.18管理端静态文件、反向代理都用它接口调试Postman 或 Apifox推荐Apifox中文友好团队协作也方便代码托管Git Gitee/GitHub建议本地建远程仓库每天提交一次这里我要特别提醒一点JDK版本和Spring Boot版本的匹配关系是新人最容易翻车的点。苍穹外卖教学版用的是Spring Boot 2.x如果你的JDK是17、18甚至21很多依赖会起冲突各种莫名其妙的报错能把人折腾到怀疑人生。听我一句劝老老实实用JDK 8 Spring Boot 2.x等你把项目跑通想升级再说。MySQL这边也有个坑。5.7和8.0的驱动类名不同5.7是com.mysql.jdbc.Driver8.0是com.mysql.cj.jdbc.Driver8.0还需要额外加时区参数serverTimezoneAsia/Shanghai。如果你用的是8.0连接串就必须写成下面这样否则数据库层直接报时区错误spring.datasource.urljdbc:mysql://localhost:3306/sky_take_out?serverTimezoneAsia/ShanghaiuseUnicodetruecharacterEncodingutf-8useSSLfalse spring.datasource.usernameroot spring.datasource.password你的数据库密码2.2 项目结构认知为什么说Spring Boot父子工程是一大重点苍穹外卖的项目结构用的是父子工程多模块Maven工程这跟很多入门课程里的单模块项目完全不同。根目录的pom.xml负责依赖版本管理和公共依赖子模块各有各的职责。Day 1你不需要把每个模块都看得透透的但至少要搞清楚每个模块将来干什么用sky-server启动类模块后面你将在这里写上所有Controller、Service、Mapper业务代码的绝大部分都在这。sky-pojo实体类模块放实体类Entity、DTO、VO。比如数据库里employee表对应的Employee实体接收参数的EmployeeDTO返回给前端展示的EmployeeVO全在这。sky-common公共模块放常量、工具类、统一返回结果类、异常处理类。像Result、JwtUtil这种高频工具都在这里。很多学员第一天上手就想在各个模块里互相调用结果类找不着、依赖报错。这里我建议你先记住一个原则依赖关系是server依赖pojo和commonpojo和common之间别互相乱引。你脑子里先有个模块依赖图后面写代码才知道类放哪里import才不会迷路。再补充一点关于分层架构的认知。苍穹外卖的Controller层、Service层、Mapper层是一套非常标准的规范用到了大量VO和DTO的转换。有不少同学到了后面写着写着浑身难受觉得为什么要建这么多类直接传实体不就好了——这种想法很危险。DTO是前端给你看的参数VO是你给前端看的数据Entity是数据库表的结构。真正开发里绝不会把数据库表结构直接暴漏给前端所以才有这一层转换。Day 1认识到这层意义后面写起来会顺畅很多。2.3 数据库导入别用SQLyog直接拖学会命令行导入苍穹外卖项目自带sql目录里面有建表语句和初始化数据。环境里用的是MySQL导入方式有好几种但我要重点推荐命令行方式。为啥因为IDEA的Database面板、Navicat、SQLyog这些图形化工具导入大SQL文件时偶尔会中途卡住或者字符集不对尤其SQL文件里有中文注释和初始数据图形工具一旦默认编码没对上中文直接乱码后面查数据你会疯掉。我的标准操作流程是# 登录MySQL mysql -u root -p # 创建数据库如果sql文件里没有建库语句需要手动建 CREATE DATABASE sky_take_out DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; # 退出mysql命令行回到操作系统命令行执行导入 mysql -u root -p sky_take_out sky_take_out.sql导入完成后用SHOW TABLES;确认表数量。苍穹外卖的数据库表大概有十张左右比如employee、category、dish、setmeal、orders这些。如果你导入后发现表少了几张多半是SQL文件执行时报错中断了回看下错误信息再处理。这里有个小细节值得注意employee表里默认的密码是加密存储的。苍穹外卖里管理员密码用的是MD5加密教学环境默认密码一般是123456的MD5值。你拿原始密码查肯定查不到后面开发登录功能时也要用相同方式加密比对这个知识点Day 1先记下后面写登录接口必用。2.4 端口概览9101、8080、80、6379……别让它们打架苍穹外卖的端口设计我梳理成一张速查表你Day 1就刻在脑子里服务默认端口说明后端服务sky-server8080项目里可配置默认通常8080管理端前端Nginx静态资源80Nginx默认端口直接访问本机IP即可用户端前端小程序或H58081或独立前端服务看具体版本配置Redis6379缓存、登录状态存储MySQL3306数据库在上环境的时候最典型的问题是本机已经占用了某个端口。比如之前装过Nginx或者Apache80端口被占管理前端就起不来比如跑过别的Spring Boot项目8080端口被占后端启动就报Port 8080 was already in use。排查端口占用我常用的命令Windows、Mac/Linux各一套# Windows netstat -ano | findstr 8080 # Mac/Linux lsof -i :8080看到占用端口进程的PID后用任务管理器Windows或kill -9 PIDMac/Linux清掉。如果那个进程没法杀你也可以改项目配置但前端静态页面里写好的后端接口地址跟着变麻烦所以能清理端口就别改配置。3. 实操过程与核心环节实现3.1 第一步搭建工程骨架并跑通启动类环境配好以后最直接的目标就是把后端项目启动起来浏览器里看到一个启动日志。我建议你按下面顺序操作每一步都能在终端或者控制台看到明确反馈用IDEA打开解压后的sky-take-out项目根目录。等待Maven自动导入依赖。这一步可能比较久尤其第一次下载依赖建议用国内Maven镜像阿里云镜像速度能提升好几倍。不会配镜像的在settings.xml里加这个mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror找到sky-server模块下的启动类类名一般是SkyApplication上面标着SpringBootApplication。右键直接Run。观察控制台日志看到类似Started SkyApplication in X.XX seconds就说明启动成功。启动日志里埋了很多隐藏信息别只盯着最后一行。往后翻你能看到项目加载了哪些配置、连接了哪个数据库、注册了哪些接口。如果启动失败多半不是代码问题而是配置问题最常见的就是数据库连不上、Redis没启动、端口被占。我见过不少学员拿着报错截图问为什么启动失败点开一看全是这三个雷。3.2 第二步用接口调试工具验证后端是活的项目启动不代表万事大吉还要验证接口能通。苍穹外卖的管理端登录接口是后续开发会写的但Day 1咱可以用最简单的办法来验证——访问一个不需要登录就能访问的接口或者直接看Nginx的转发是否正常。如果你需要快速验证可以先跑一个临时接口来确认服务真的活着。通常我会顺手在Controller里加一个测试接口亲测有效RestController public class TestController { GetMapping(/test) public String test() { return sky take out is running; } }重启项目后浏览器访问http://localhost:8080/test看到那段字符串说明后端服务正常运行数据库连接也没问题因为Spring Boot启动时如果数据库连不上会直接报错启动失败。验证完记得把这个测试接口删掉免得后面提交代码时带上不干净的测试代码。3.3 第三步启动Nginx把管理端页面跑起来后端服务只是一半管理端的前端页面需要靠Nginx来托底。苍穹外卖的资料里通常会带一个前端编译好的dist目录里面是管理后台的静态文件。Nginx的核心任务就是托管这个目录同时把/api开头的请求反向代理到后端的8080。Nginx配置里最核心的几行我拆开讲一下server { listen 80; server_name localhost; # 管理端前端静态页面 location / { root /path/to/sky-manager/dist; index index.html; } # 后端接口反向代理 location /api/ { proxy_pass http://localhost:8080/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }这个配置的核心逻辑是浏览器访问http://localhost/时Nginx把dist目录下的index.html返回给你页面里的JS/CSS也从这个目录加载当页面需要请求后端数据时比如/api/employee/loginNginx就把请求转发给Tomcat所在的8080端口。有几点你检查时要留意root路径不能配错必须指到有index.html的那一层目录。dist目录如果用IDEA打开路径分隔符注意系统差异。Nginx的proxy_pass后面的/api/必须完整写清楚少一个斜杠都可能404。启动Nginx后浏览器访问http://localhost/看到的是管理端登录页。因为后端登录功能还没开发你输入账号密码点登录大概率会报错或没反应这是正常的别慌。Day 1能看到登录页面就算成功了一半。3.4 第四步掌握导入资料的合理顺序这一步不是技术操作但我觉得值得单独拿出来讲因为太多人一上来就把所有资料解压得到处都是最后连哪个文件对应哪个环节都找不到。我推荐你按这个顺序来梳理资料sql目录里的SQL脚本 → 第一批使用导入数据库。后端工程代码sky-take-out → 第二批打开启动后端。前端dist目录 → 第三批部署到Nginx看到页面。接口文档通常是YApi或Markdown → 第四批阅读配合IDE看接口定义。开发笔记或代码讲解视频 → 配合学习别当成替代品。资料整理还有一个好处你知道什么阶段该看哪份文档。以后开发新功能时接口文档就是你的需求说明书代码只是实现。很多人写代码全靠背或者抄完全不看接口文档写到一半才发现字段名不一致、返回结构不对返工成本极高。Day 1就养成看文档的习惯后面每天都是受益者。4. 常见问题与排查技巧实录4.1 启动失败数据库连接不上这是Day 1翻车率最高的问题没有之一。报错长这样Cannot create PoolableConnectionFactory (Communications link failure The last packet sent successfully to the server was 0 milliseconds ago...排查思路按顺序来MySQL启动了没Windows下可以看服务列表Mac/Linux下用brew services list或systemctl status mysql。密码对不对在命令行用mysql -u root -p手动连一次试试。防火墙挡了没本地开发一般没事但如果MySQL装在远程虚拟机里就要确认3306端口放行。配置文件里的数据库名对不对注意是sky_take_out别写成sky-take-out。这里有个百分之八十的人都会踩的低级错误——连接的数据库里还没有导入表或者连错了库。用SHOW TABLES确认一下别等启动成功后查询数据时才发现表全空。4.2 端口被占用换个端口不如杀进程Spring Boot项目启动报Web server failed to start. Port 8080 was already in use.很多人的第一反应是改配置文件换端口。如果你只是单纯想快速跑起来改端口确实能解决但这会给后面Nginx反向代理带来额外工作——Nginx里写死了转发到8080你改了后端端口就得同步改Nginx配置改漏一个地方接口全挂。我的建议是杀进程别换端口。Windows下netstat -ano | findstr 8080 taskkill /PID 你的PID /FMac/Linux下lsof -i :8080 kill -9 PID处理完重新启动项目日志就干净了。4.3 前端页面打不开Nginx的坑全在路径管理端页面在浏览器访问http://localhost/却空白/403/404十有八九是Nginx配置里root路径不对。Nginx的root指令要求的是绝对路径。比如你解压出来的目录在C:\workspace\sky-manager\dist配置就必须写成这个绝对路径少一个分隔符、多一个中文目录名都可能出问题。改完Nginx配置别忘了重载nginx -s reload如果你不确定Nginx配置有没有语法错误先执行nginx -t看到test is successful再重启。这个习惯能帮你省下大量排错时间。4.4 依赖导入失败Maven镜像问题Day 1最容易把人搞崩的还有依赖下载超时。第一遍配环境Maven中央仓库在国内访问极慢下载依赖动不动就卡半小时最后报一堆红色错误。这个问题根源就是镜像。解决方案刚才已经写了在settings.xml里配置阿里云镜像。配置完记得刷新Maven工程点IDEA右侧Maven面板的刷新按钮等依赖重新导入。这里多说一句别用默认的Maven仓库地址就硬等网络自己好。省下这个时间够你多看三节需求课程了。4.5 管理端登录无反应别慌这是Day 2的活很多学员在Day 1拿到前端页面后会习惯性点登录、输密码发现请求发不出去或报错就以为自己环境有问题。其实不是Day 1管理端登录接口还没开发前端页面虽然渲染出来了但后端还没有对应的登录接口点登录当然没反应。判断标准很简单打开浏览器F12开发者工具切到Network网络面板点登录按钮看请求是否发出去了。如果请求发到/api/employee/login响应404——说明Nginx和后端链路是通的只是接口不存在这完全正常第2天写完登录功能再回来验证。如果请求都没发出去那才需要回到Nginx配置去排查。5. 本地上传图片功能提前看Day 1就该懂的图片流标题里的热搜词苍穹外卖本地上传图片很多人到Day 6开发菜品的图片上传功能时才接触。但我想说Day 1就把这个功能的主线逻辑想明白后面项目推进会顺很多。5.1 图片上传在项目里的业务场景苍穹外卖里有两类核心业务需要图片上传管理端添加菜品时要上传菜品图片用户端浏览店铺时展示店铺图片。管理端的图片上传功能是练手重点——前端用ElementUI的上传组件用户选择本地图片后前端把图片以multipart/form-data格式POST到后端接口后端接收后把图片存起来返回给前端一个可访问的图片URL前端用这个URL来显示图片。图片本身存到哪里两种方案本地磁盘存储和生产环境的对象存储。项目开发阶段最简单可靠的方式是存到本机某个目录然后通过Nginx或后端静态资源映射暴露出去。后面如果上线就会换成云存储服务各大云厂商都有但接口设计逻辑一样。5.2 本地存储方案目录设计、文件名生成、访问映射我在实际教学中建议的本地存储方案是这样的定义一个图片存储根目录比如/Users/xxx/sky_images/、D:/sky_images/这个目录不放在项目内部。为啥不放在项目里因为Spring Boot项目打包成jar后jar内部的静态目录不好写文件而且重启会丢。放项目外重启也在。文件名用UUID 原始后缀名的方式生成避免中文文件名乱码、避免重复。比如a3f2c11e-8b5c-4f2e-b1a1-2e20934a1f55.jpg。每天或者每月按目录再分一层比如2025/06/方便后期维护和清理。接口核心代码逻辑写给你参考PostMapping(/upload) public ResultString upload(MultipartFile file) { // 1. 拿到原始文件名提取后缀 String originalFilename file.getOriginalFilename(); String suffix originalFilename.substring(originalFilename.lastIndexOf(.)); // 2. 生成新文件名UUID 后缀 String fileName UUID.randomUUID().toString() suffix; // 3. 按月份创建子目录 String datePath DateTimeFormatter.ofPattern(yyyy/MM).format(LocalDateTime.now()); File dir new File(basePath datePath); if (!dir.exists()) { dir.mkdirs(); } // 4. 保存文件 file.transferTo(new File(dir, fileName)); // 5. 返回可访问的URL地址 return Result.success(/images/ datePath / fileName); }图片可访问这件事有两种做法把图片目录映射成静态资源路径在Spring Boot里通过WebMvcConfigurationSupport的addResourceHandlers方法将磁盘目录映射到/images/**虚拟路径。使用Nginx映射Nginx配一个location /images/ { alias /path/to/sky_images/; }效率更高也更接近生产环境。5.3 为什么Day 1要提前搞懂图片上传很多学员觉得图片上传是后面的事现在看纯属浪费时间。恰恰相反图片上传牵涉到HTTP协议中的表单上传格式、后端文件接收、URL映射、前端组件联动这条链路是苍穹外卖项目里少数需要前后端联动的功能点。Day 1先把逻辑主线记住等后面真正开发时你的注意力只需要放在代码细节上而不是这个功能到底要做什么。而且图片存储方案涉及本地路径规划、静态资源映射、Nginx配置这些技能本身就是Java开发面试里常被问到的点早掌握早受益。Day 1这一整套流程走下来说实话真的不复杂装好环境、启动后端、用Nginx托管前端、数据库灌好数据、心里对项目的表结构和接口文档有一个大致印象。但你要知道很多人在这一步就倒下了然后不断怀疑自己是不是不适合编程。其实真不是你不行绝大多数问题就是上面那些固定的坑——版本不匹配、端口冲突、依赖下载慢、路径写错。我见过太多启动失败然后就搁置项目的真实情况说实话问题都很简单。Day 1的核心价值不是把代码背下来而是把项目跑起来让自己对全盘有一个掌控感。你把这个基础打好后面每一天的推进速度都会远超你现在的想象。