“苍穹外卖 01”这个标题在Java后端的学习圈里几乎算得上一个“暗号”了。很多刚走完SSM或Spring Boot入门教程的人都会在某个阶段遇到这个名字。它不是一个真实上线的商业项目而是一个高度贴近真实业务场景的实战练习项目核心业务是一套外卖平台的完整后端服务覆盖管理端、客户端和骑手端三块最常见的业务域。01作为系列的第一篇承担的任务通常是需求梳理、技术选型、环境搭建和基础模块落地也就是把一个项目从“零”真正推到“能跑起来、能登录”的阶段。这篇文章就是围绕这个第一阶段来写的。里面会把这套项目的整体设计思路拆开把数据库建模、登录鉴权、员工管理这些核心模块的实现细节讲清楚最后再把我自己实操中踩过的坑和排错顺序一并整理出来。适合两类人看一类是刚学完框架基础、准备用完整项目练手的人另一类是已经做到中间阶段、想回头把地基部分补扎实的人。1. 项目整体设计与需求拆解1.1 外卖业务到底在做什么事先想清楚业务再碰代码。外卖平台表面看就是“用户下单、商家出餐、骑手配送”但真正落地成系统里面的角色关系比想象中复杂。苍穹外卖的业务模型大致围绕三个角色展开。管理端是平台运营方使用的负责管理商家入驻、菜品上下架、分类调整、订单监控和营业数据统计客户端是普通用户使用的负责浏览分类、挑选菜品、加入购物车、提交订单、在线支付和查看订单状态骑手端则是接单、取货、配送、完成订单的流转变现。01阶段主要聚焦在管理端的基础能力上。后台登录、员工管理、分类管理、菜品管理这几个模块是后续所有业务的地基。没有一套可靠的员工账号体系和权限边界后面无论做订单流还是数据统计都会失去身份依据和操作入口。1.2 核心功能模块的优先级排序新手拿到这种项目最容易犯的毛病是“全都要”。我见过有人一上来就规划十几个模块数据库建了二十多张表结果做了两个月还在调登录接口。我的建议是第一阶段的优先级一定是“管理端可登录、可维护基础数据”。按这个思路01阶段要落地的模块应该圈定在四个方面。员工登录与鉴权是最优先的一环没有它后续所有接口都无法做身份校验。其次是员工信息管理包括查询员工列表、新增员工、启用禁用账号、修改密码这类日常运维操作。然后是分类管理外卖平台的菜品分类支持一级和多级结构这是菜品模块的前置依赖。最后是菜品与套餐的基础管理包括文件上传、菜品的新增和分页查询。至于购物车、订单、支付、配送这些高业务复杂度的模块全部放到后面的阶段性规划里。这样安排的逻辑很简单每个阶段能“完整闭环”地上线一部分可演示的功能而不是做一个永远调试不完的半成品。1.3 标题里的“01”在整条学习线里的定位如果把这套项目比作盖楼01阶段就是“打地基”和“出正负零”的过程。它不做复杂的业务算法不碰高并发的订单峰值问题更不意味着把极简的框架Demo再抄一遍。它的真正价值在于让你用接近工业级的方式把一套前后端分离的看板结构搭起来并且跑通一个带鉴权后台的最小业务闭环。一个合格的01阶段至少应该达到三个验收标准第一管理后台能通过账号密码正常登录未登录状态访问业务接口会被拦截第二员工数据能通过后台进行增删改查密码不是明文存储第三数据库里的表结构不是拍脑袋设计的能支撑后续菜品、分类、订单等业务扩展。2. 技术选型与方案设计思路2.1 后端主框架为什么用 Spring Boot 搭配 MyBatis苍穹外卖的01阶段技术栈选型非常“经典”Spring Boot作为应用主框架MyBatis作为持久层框架MySQL作为主数据库Redis负责缓存与部分会话数据前端部分则通过小程序或管理后台Vue项目对接前后端通过JSON格式的RESTful接口交互。这个组合在当前环境下不是“最新潮”的但一定是“最适合教学和练手”的。Spring Boot解决的是传统Spring配置繁琐的问题它用自动配置把大量的基础设施工作压缩成几个注解和依赖坐标。MyBatis相比JPA和MyBatis-Plus保留了手写SQL的控制力这一点在教学阶段特别重要你能通过每一行SQL真实感知数据库交互的过程而不是被ORM框架过度封装。2.2 缓存、存储与工具组件怎么分工外卖系统天然是“读多写少”的业务模型。用户打开App最先看到的分类、菜品列表这些数据在一天之内变化频率极低但访问次数极高。这种场景非常适合引入Redis做缓存。01阶段虽然还没有完全展开客户端的高频读接口但缓存组件应该从一开始就预置进来否则后面再接入会觉得代码结构很别扭。文件上传也是外卖系统的刚需。菜品图片、营业执照、身份证照片都需要一个可靠的对象存储通道。在本地开发阶段最务实的做法是搭建一个本地文件存储服务实现文件上传后返回可访问的URL。这样既不需要依赖第三方云厂商又能让你理解文件上传的完整链路。等部署到服务器后再替换成云存储的SDK实现。2.3 前后端分离的项目结构怎么组织工程结构上这套项目采用前后端分离。前端的管理后台用Vue3或微信小程序实现后端统一提供/admin、/user、/common等前缀的RESTful接口。实际开发中前端代码和后端代码一定要分成两个独立工程目录不要混在一个仓库里。后端内部则按功能模块分包而不是按技术类型分包。举个例子controller、service、mapper这种按层分包的方式在小项目里看着挺清爽一旦功能模块变多包之间的依赖会越来越乱。更推荐的做法是先按业务域拆分成employee、category、dish、setmeal在每个业务域内部再组织controller、service、mapper子包。这样从包结构上就能看出系统有哪些业务模块而不是靠翻目录猜。3. 环境准备与核心数据模型设计3.1 开发环境的版本搭配建议01阶段的环境搭建卡住很多人往往不是能力问题而是版本搭配问题。Java、Maven、MySQL、Redis这几个组件版本不兼容会引发一堆让人抓狂的报错。我自己常用的组合是JDK 1.8或11、Maven 3.6.x以上、MySQL 8.0、Redis 5.x或6.x、前端管理后台用Node 16或18。重点提醒一句如果本机已经装了MySQL 5.x建议优先切换成8.0再开始这个项目。虽然5.7也能跑但密码认证插件变化会导致驱动连接配置出现差异。Spring Boot 2.7.x版本搭配mysql-connector-j8.0.x时driver-class-name是com.mysql.cj.jdbc.Driver连接串里别忘了加useSSLfalseserverTimezoneAsia/Shanghai这两个参数否则时区或SSL握手会报错。3.2 5张核心表的业务血缘关系01阶段的数据模型不需要一次性铺开全量表但关键的几张核心表必须在这个阶段里设计好。它们是后续扩展的地基。第一张是员工表employee主键用id核心字段包括username、password、name、phone、status外加create_time、update_time、create_user、update_user这类审计字段。外卖系统的管理员账号体系相对简单但密码字段绝不能用明文。第二张是分类表category核心字段包括name、type、sort、status。这里的type用来区分分类是菜品分类还是套餐分类取值为1或2。sort用于控制同类型分类在页面上的展示顺序数字越小越靠前。第三张是菜品表dish核心字段包括category_id、name、price、image、description、status。菜品对外卖系统来说是核心商品category_id通过外键逻辑关联到分类表。第四张是口味表dish_flavor它和菜品表是多对一的关系专门存放“辣度”“规格”之类的标签型数据。第五张是套餐表setmeal以及配套的套餐菜品关系表setmeal_dish。套餐本质上是菜品的组合所以setmeal_dish里既要有套餐ID又要有菜品ID和份数才能把多对多关系拆成两张表存储。3.3 建表SQL里的关键约束怎么写实际写建表语句时有四个细节值得特别强调。第一主键统一用bigint类型并配合自动递增不推荐业务主键尤其不推荐用手机号或用户名当主键一旦账号需要修改标识主键变动会引发连锁问题。第二业务表强制加create_time、update_time两个时间字段并让代码层统一维护这样查问题的时候能追踪数据演变的时序。第三status字段统一用tinyint0表示禁用1表示启用命名上直接见名知意不要用is_delete这种容易和逻辑删除混淆的词。第四价格字段用decimal(10,2)而不是double避免浮点精度造成金额偏差。员工表的初始化数据尤其要注意。系统必须内置一个超级管理员的初始账号否则后台连登录都进不去。常见做法是插入一条username为admin、密码为MD5加密后密文的记录。4. 后台登录与员工管理模块实现4.1 统一的响应结果与异常处理体系后台接口如果直接返回裸数据前后端联调时会出现一个很尴尬的问题接口要么返回对象、要么返回字符串、要么返回布尔值前端拿到什么都需要猜。工整的做法是先定义一套统一响应结果体通常包含三个字段code表示业务状态码msg表示提示信息data表示具体数据。这个封装类通常命名为Result提供静态方法success()和error()。业务中所有Controller的返回值都用这个类包一层。这样做的好处不只是规范更重要的是后续可以统一做全局异常兜底不管Service层抛出业务异常还是系统异常全局异常处理器都能捕获并返回统一格式的错误信息避免白屏和堆栈信息直接暴露给前端。01阶段就很值得把这件事做扎实后面你写的每个接口都会受益。4.2 JWT令牌的生成与登录态校验管理端是内部系统但也不能裸奔。登录状态管理在01阶段选用JWTJSON Web Token是合理的。用户在后台输入账号密码后端核验成功后生成一个JWT令牌令牌里可以存放员工ID和用户名这类非敏感信息作为后续接口的身份凭证。JWT的核心机制是签名防篡改。实现时可以用io.jsonwebtoken的Jwts库设置一个足够复杂的签名密钥通过Jwts.builder()设置主题、签发时间、过期时间再压入自定义的claims业务数据最后生成一个紧凑型字符串。登录接口返回这个令牌前端拿到后存到localStorage或请求头里后续每次请求携带token字段。权限控制最方便的做法是写一个拦截器。但这个拦截器有个特别容易踩的坑一定要在拦截器里放行登录接口、静态资源等白名单路径。如果把/admin/employee/login也拦截了用户连登录都提交不出去就会出现“启动没问题但一请求就401”的诡异状态。4.3 密码加密与员工信息管理外卖管理后台的密码存储不能是明文。就算这个项目是教学用途也应该从一开始就建立正确的安全意识。常用的做法是MD5加盐或BCrypt加密。MD5加盐相对简单使用门面类DigestUtils.md5DigestAsHex把原始密码和固定盐值拼在一起再取摘要。这里要注意盐值不能是随机值否则旧账号密码没法做校验。如果后面想做更强的方案使用BCrypt是更好的升级方向。员工管理接口在01阶段至少要实现四个分页查询员工列表支持按姓名模糊搜索新增员工用户名为唯一标识密码默认用初始密码加密后写入启用禁用员工账号前端通过修改status字段完成编辑员工基本信息并更新数据库。这里有个实际经验是分页查询的返回格式PageResult里要同时包含total总数和records列表数据前端的分页组件才能正确渲染总页数。4.4 为什么这个阶段要把登录代码写得格外细很多新手在练登录功能的时候觉得“能通就行”代码写得非常随意。用户名密码直接查库比对、不走缓存、不设过期时间、异常统一吞掉。等做到后面订单模块需要从登录令牌中拿用户身份时才发现claims里没放用户ID又回头改登录逻辑还不敢轻易动线上数据。所以我特别建议在01阶段就把登录链路按“生产级标准”写完整。包括密码加密验证、账号状态校验、JWT生成与过期策略、拦截器统一鉴权、全局异常处理。哪怕前端页面只有登录框和列表页这个闭环也是完整的。后面再加新接口只需要关注业务逻辑本身不需要反复回来补基础设施。5. 常见问题与排查技巧实录5.1 应用启动失败端口被占用这个问题出现的频率极高。Spring Boot默认使用8080端口如果本机有其他服务占用了8080启动会报Port already in use错误。排查顺序很简单先看报错信息java.net.BindException后面通常会带着端口号。然后执行netstat -ano | findstr 8080Windows或lsof -i:8080Mac/Linux找到占用进程的PID杀掉即可。如果不想杀进程也可以在application.yml里修改server.port但这会带来连锁问题前端开发环境的代理配置、后端自测的接口地址都要跟着改所以尽量还是保持默认端口。5.2 数据库驱动找不到或连接超时这个报错有两个常见方向。第一个是Maven依赖没拉下来pom.xml里写了mysql-connector-j依赖但本地仓库里缺包启动时出现ClassNotFoundException。解决办法是先执行mvn clean再执行mvn compile让Maven重新下载依赖文件。第二个是连接串配置错误。spring.datasource.url必须指定useUnicodetruecharacterEncodingutf-8否则中文数据写入后大概率出现乱码查询统计也会错乱。5.3 MyBatis查询结果为空但SQL在数据库能查到这是MyBatis新手最容易困惑的问题之一。数据库里明明有数据接口返回却是空列表或者在console里看不到SQL日志输出。先检查Mapper接口的包扫描配置MapperScan注解的basePackages必须指向Mapper接口所在的完整包路径。其次检查application.yml里的mybatis.mapper-locations配置如果映射文件放在resources/mapper下但是xml文件的命名空间和接口全限定名不一致就会出现这种“静默失败”。更隐蔽的一个问题是实体类的setter写错或者属性名和数据库字段对不上。MyBatis底层通过反射给属性赋值如果数据库列名是createTime而实体类属性是create_time又没有开启驼峰映射结果就是createTime一直是null。5.4 接口返回404或路径匹配不上Spring Boot的接口路径匹配规则比较严格。Controller类上的RequestMapping(/admin/employee)方法上的PostMapping(/login)实际请求路径就是/admin/employee/login。如果前端请求带了尾斜杠或者Controller类上漏写了路径前缀都会出现404。排查技巧是打开日志里的请求映射列表。在application.yml里配置logging.level.org.springframework.webdebug启动后会打印所有已注册的HandlerMapping路径。对照日志里实际注册的路径和前端调用的路径哪里对不上问题就浮出水面了。5.5 Token拦截导致登录接口永远不通拦截器配置的顺序问题我前前后后在这个坑里摔过三次。如果拦截器注册时没有排除登录接口会出现一个逻辑死锁登录接口本身需要放行拦截器却拦截了所有请求于是前端调/login时直接被拦截提示未登录无法走到登录逻辑。正确写法是在WebMvcConfigurer里配置拦截器时显式调用excludePathPatterns把登录接口、静态资源路径、文件上传预览路径都加进去。这里还要注意路径匹配的写法/admin/employee/login只匹配一个精确路径如果想排除整个模块的登录相关接口用/admin/employee/login/**通配会稳妥一些。5.6 前端联调时跨域请求被拦截前端开发服务器一般在localhost:8081或5173端口后端接口在8080浏览器会触发CORS跨域策略。解决办法是在后端添加一个WebMvcConfigurer的配置类重写addCorsMappings方法允许的源设为前端开发地址允许的请求头包含token字段。这里容易遗漏的是设置前端自定义的请求头。如果只设置了allowedOrigins前端请求带了Authorization或token头还是会被预检请求拦下来。所以allowedHeaders和exposedHeaders都要配全。结束语“苍穹外卖 01”这个阶段最难熬的往往不是代码本身而是从“会用框架写接口”到“能独立设计整个后台系统”的思维转变。我自己刚开始练这个系列时光是数据库表就推翻重来了一次——第一次建表没有审计字段没有状态字段做到员工禁用功能时发现缺字段只能回头改表结构、改实体、改接口牵一发动全身。所以我会特别强调01阶段宁可多花两天把需求拆透、把表设计稳也不要急着往下写功能。再有就是调试习惯。一套项目做到中后期大量时间其实花在排查问题上。我的习惯是日志一定从第一天就规范输出异常一定要有堆栈和上下文接口联调前先拿工具手测一遍。这些不起眼的习惯比多刷一百道题都管用。如果你现在正好卡在哪里跑不通先按第5节的顺序逐项检查大概率能找到问题的根源。这个项目后续的内容还很多分类、菜品、购物车、订单每一个模块都是在上面的地基上往上盖的。把01阶段真正吃透后面的路会顺很多。