写苍穹外卖学习日记的第一篇之前我纠结了好几版开场白。后来想明白了这个项目之所以能成为Java学习者绕不开的练手项目不是因为它用了多少花哨的框架而是因为它把一家真实外卖公司后台可能涉及的场景几乎全部搬到了代码里员工登录、分类管理、菜品与套餐维护、图片上传、订单流转、数据统计、定时报表、支付与消息推送。今天先不聊全貌就从最容易被忽略却最容易被追问的一环讲起——苍穹外卖本地上传图片到底怎么实现以及我在做这个模块前后踩过的那些坑。这篇日记适合三类人刚把SSM和Spring Boot基础语法学完、想找个完整项目检验自己的同学准备校招或社招、需要把项目讲清楚而不是单纯“跑起来”的求职者还有那些用云存储用得顺手、却不太清楚文件存储在本地时底层要处理哪些细节的开发者。我会按自己当时的学习顺序来写先看整体结构再拆上传模块接着贴出可复现的代码最后整理排查清单。至少能让你从“会点按钮”进阶到“能解释为什么要这么写”。1. 苍穹外卖项目初印象一个典型企业级业务闭环1.1 项目长什么样管理端、用户端、数据统计三条线苍穹外卖也叫苍穹外卖项目本质上是前后端分离的外卖业务系统。管理端给门店员工和商家用技术栈常见的是Vue Element UI用户端则是微信小程序给普通消费者下单用。后端统一由Spring Boot提供接口单体内聚、耦合不高适合个人学习者完整跑通。从业务线来看项目其实可以切成几条链路基础数据链路员工管理、分类管理、菜品管理、套餐管理这些是外卖系统运转的地基。核心交易链路用户端浏览菜品、加入购物车、下单、支付、商家接单、配送、完成订单。数据辅助链路营业状态管理、数据统计、导出运营报表。每条链路之间不是孤立的。比如菜品管理里必须包含图片字段图片上传的好坏直接影响前端展示而订单状态的变化会影响店铺营业统计。我第二次过这个项目的时候才真正意识到学习时如果只盯着某个接口的CRUD很容易丢掉这种业务串联能力。面试官问“你的项目为什么这么设计”本质考的就是这个。1.2 为什么要一行行啃代码而不是刷视频“假装学会”这个项目的体量对新手来说不算小。如果只是跟着视频敲一遍效果往往停留在“代码能跑”遇到报错还是两眼一抹黑。我建议至少做到三层第一层是能跑通。把项目下载下来把数据库导进去管理端登录进去能新增菜品、能看到图片回显。第二层是能讲清。每个模块为什么存在、表为什么这么设计、接口为什么返回这些字段。第三层是能改动。比如把本地图片存储改成对象存储把缓存策略从手动改成注解这种迁移能力才是面试和工作中真正用的。苍穹外卖特别适合用来做这三层训练因为它的代码风格相对规范和很多中小型公司的Java后端工程比较接近。你在这里养成的习惯比如统一返回结果、全局异常处理、公共字段自动填充到了真实项目里照样能用。2. 项目骨架与技术栈的选型逻辑2.1 从Maven多模块开始的工程结构苍穹外卖的典型工程结构分为三个Maven模块sky-server、sky-pojo、sky-common。很多人第一次看到这种结构会觉得“麻烦”其实它有实打实的好处。sky-pojo放实体类、DTO、VO。DTO负责接收前端参数VO负责返回给前端数据Entity对应数据库表字段。这样设计之后接口的入参和出参不会因为数据表变动而大面积失效。sky-common放通用工具类、统一返回结果Result、异常处理、JWT工具、阿里云OSS工具等。sky-server是核心业务模块Controller、Service、Mapper都在这里依赖sky-pojo和sky-common。为什么要把pojo和common拆出来因为项目变大后可能同时存在多个启动入口比如管理端接口、用户端接口、定时任务进程它们共享同一套基础类和工具类。拆成独立模块后依赖关系精准编译速度更快也不会出现“一个模块里所有东西都挤在一起”的混乱。我刚学习时觉得多模块是过度设计后来做项目才发现当初嫌麻烦的工程分层恰恰是别人能快速定位问题的主要原因。2.2 技术栈逐条说清Spring Boot、MyBatis、Redis、JWT外卖项目里技术栈不是随便堆的每一样都对应着真实问题。Spring Boot负责整体自动装配让配置从繁琐的XML里解放出来。MyBatis负责SQL和Mapper层因为外卖统计这类业务有大量联表查询和分组查询MyBatis写动态SQL比较灵活比纯JPA更容易掌控复杂SQL。Redis在项目里主要干两件事缓存菜品数据减轻数据库压力保存用户购物车和登录状态相关的临时数据。JWT则解决了无状态登录问题用户登录后拿到一个token后续每次请求带上它后端通过JWT工具解析出用户身份不需要在Session里保存登录态。这里我想多说一句选型背后的原因。外卖项目的菜品浏览是典型的“读多写少”菜品的分类、图片、价格变动频率不高但用户刷新的频率极高。如果每次都查数据库高峰期会直接把数据库打满。所以项目里对分类、菜品这些热门数据做Redis缓存失效策略一般跟商家操作关联商家修改菜品后清除对应缓存用户端下次拉取时重新加载。这种“缓存一致性”的写法面试官非常爱考。2.3 数据库设计与业务表关系苍穹外卖的表设计逻辑比较清晰。以核心几张表为例category表保存菜品分类type字段区分是“菜品分类”还是“套餐分类”。dish表保存菜品基本信息外键关联category同时包含image字段保存的就是图片URL。setmeal是套餐表通过setmeal_dish表跟dish建立多对多关系。orders和order_detail保存订单主表与明细表明细表里会冗余菜品名称和图片因为历史订单里的菜品信息不能因为菜品被删除而丢失。这个设计能解释一个很常见的问题菜单的image字段为什么存的是URL而不是二进制数据因为数据库里保存二进制大对象BLOB会让表变得笨重查询性能差还不利于图片分发。实践中几乎所有系统都选择把图片上传到文件服务然后只把访问URL写入数据库。常见的URL就是类似http://localhost:8080/upload/dish/xxxx.jpg这种形式。理解清楚表关系之后再看图片上传接口思路就通了前端上传图片后端保存文件并返回URL前端把URL和其它菜品信息一起提交到新增菜品接口菜品的image字段最终落入dish表。3. “苍穹外卖本地上传图片”这个高频词背后的模块拆解3.1 为什么这个需求会被反复拿出来讨论最近一段时间苍穹外卖本地上传图片成了搜索热词很多人直接搜“苍穹外卖本地上传图片 报错”“苍穹外卖本地上传图片 404”。被问得多了之后我也认真想过原因。一个原因是很多教程默认教你直接使用阿里云OSS上传代码写得少、老练但本地存储才是最能体现基本功的部分。另一个原因是本地文件上传涉及的知识点特别杂MultipartFile接收、配置文件读取、文件目录创建、UUID生成文件名、文件扩展名校验、虚拟路径映射、URL拼接、跨域访问。任何一个环节没搞明白都会导致最终图片不显示。而这些细节恰恰是真实开发里特别常遇到的。运营一个外卖项目的早期阶段图片量不大用本地磁盘存储是最经济的做法。等用户量上来以后再切换对象存储服务也是很多创业公司真实走过的路径。所以本地存储不是过时技术而是理解存储演进的基础。3.2 上传模块的两种典型实现方式如果你去看不同的苍穹外卖教程会发现图片上传有两种实现写法。第一种是直接在Controller里做所有事情用RequestParam(file) MultipartFile file接收文件然后调用一个工具类把文件二进制写入磁盘返回URL。这种写法代码短、容易跑通适合第一次上手。第二种是接口驱动的写法。定义一个StorageService接口提供upload(MultipartFile file)和delete(String fileName)方法。本地存储实现类负责把文件写到磁盘将来如果要切OSS只需要再加一个实现类改一下配置业务层代码不用动。我强烈建议你学第二种。不是因为它“高深”而是因为苍穹外卖后续的课程确实会涉及OSS改造。如果从一开始就把上传逻辑封装成接口迁移的时候只动一个实现类而不是满项目搜索FileOutputStream这种组织能力也是工程经验的一部分。3.3 一次上传请求的完整链路把整条链路捋顺以后排查问题会快很多前端从微信小程序或管理端页面选择一个图片通过multipart/form-data格式POST到后端接口请求里带一个名为file的字段。后端的Controller方法用MultipartFile参数接收这个文件。进入Service层后先校验文件是否为空、大小是否超限、扩展名是否在白名单里。接着生成一个新的文件名规则一般是UUID 原始扩展名再把文件保存到本地的上传目录经常还会按日期分子目录比如202505/01/。与此同时Spring MVC已经把某个URL前缀比如/upload/映射到了硬盘上的上传目录所以前端可以直接用http://ip:port/upload/202505/01/uuid.jpg访问这张图片。后端把这个完整URL返回给前端前端再把它和菜品的其它字段一起提交最终存入数据库。这个链路里最容易出问题的三个点文件保存到哪个目录、URL怎么拼接、静态资源映射怎么配置。接下来我用实际项目中的写法把它们一一讲透。4. 本地图片上传的完整实操记录与参数解读4.1 把上传目录和访问前缀配置到application.yml我先看配置文件的部分。苍穹外卖项目中开发环境通常用application-dev.yml公共配置在application.yml里。为了让上传目录可以随时调整不建议把路径硬编码到代码里而是通过自定义配置项暴露出来。file: upload-path: D:/upload/images access-prefix: /upload有的教程会把路径写成src/main/resources/upload这种写法短期能跑但也有隐患。因为重新编译或打包时target目录会被清空上传的图片可能丢失。更稳妥的做法是放到项目工程之外的固定目录比如Windows下的D:/upload或者Linux下的/data/upload。这样服务重启、重新部署都不会影响已上传的图片。有些版本还会配上Spring对上传文件大小的限制spring: servlet: multipart: max-file-size: 10MB max-request-size: 10MB配置项的含义要分清max-file-size限制单个文件大小max-request-size限制整个请求体大小。如果表单里同时传图片和多个字段请求体大小通常会比单个文件大一些所以我会习惯把后者设置成前者的两倍左右比如单文件10MBrequest整体20MB。4.2 Controller、Service与工具类的实现代码先看Controller层。上传接口接收一个MultipartFile参数返回统一结果对象Result是苍穹外卖里常见的封装。RestController RequestMapping(/admin/common) Slf4j public class CommonController { Autowired private StorageService storageService; PostMapping(/upload) public ResultString upload(RequestParam(file) MultipartFile file) { if (file null || file.isEmpty()) { throw new BusinessException(上传文件不能为空); } String url storageService.upload(file); return Result.success(url); } }这里的字段名file必须和前端表单里字段名一致。很多同学遇到“接口收到的file为null”大概率就是这里对不上。接着定义一个存储服务接口这是日志里强调的接口化写法public interface StorageService { String upload(MultipartFile file); void delete(String fileName); }本地存储实现类是核心。它的职责包括校验扩展名、创建日期子目录、生成UUID文件名、写文件、拼接访问URL。Service public class LocalStorageService implements StorageService { Value(${file.upload-path}) private String uploadPath; Value(${file.access-prefix}) private String accessPrefix; private static final ListString ALLOWED_EXT Arrays.asList(jpg, jpeg, png, gif); PostConstruct public void init() { File dir new File(uploadPath); if (!dir.exists()) { dir.mkdirs(); } } Override public String upload(MultipartFile file) { String originalFilename file.getOriginalFilename(); String ext ; if (originalFilename ! null originalFilename.contains(.)) { ext originalFilename.substring(originalFilename.lastIndexOf(.) 1).toLowerCase(); } if (!ALLOWED_EXT.contains(ext)) { throw new BusinessException(不支持的文件类型 ext); } String datePath LocalDate.now().format(DateTimeFormatter.ofPattern(yyyyMM/dd)); File dir new File(uploadPath, datePath); if (!dir.exists()) { dir.mkdirs(); } String newFileName UUID.randomUUID().toString().replace(-, ) . ext; File dest new File(dir, newFileName); try { file.transferTo(dest.getAbsoluteFile()); } catch (IOException e) { log.error(本地文件上传失败, e); throw new BusinessException(文件上传失败); } return accessPrefix / datePath / newFileName; } Override public void delete(String fileName) { // 通过虚拟路径前缀删除文件重点注意安全校验防止路径穿越 } }几个细节我特别说明一下。PostConstruct在Spring初始化这个Bean之后、对外提供服务之前执行作用是确保目录一定要存在。如果不做这一步第一次上传时目录不存在transferTo会直接抛出异常用户第一次使用就报错体验非常差。文件名用UUID而不是原始文件名核心原因有两个。第一不同用户上传的文件可能重名直接覆盖会导致别人图片丢失第二中文文件名在URL拼接和容器解码时容易出现乱码。UUID生成的随机字符串没有业务含义也天然避免了脏字符。原始文件名只用来取扩展名别再多用。file.transferTo(dest)这一步是Spring封装好的方法内部会处理临时文件的移动。老一点的写法是file.getInputStream()配合FileOutputStream手动写我新手阶段也写过后来发现transferTo更不容易出问题因为临时文件的清理和文件句柄的关闭都由框架处理了。4.3 让图片能被浏览器访问虚拟路径映射文件保存到本地磁盘之后浏览器还不能直接访问。它知道的是域名和URL不知道你磁盘上有文件。所以必须告诉Spring MVC当请求的路径以/upload开头时去磁盘的哪个目录找文件。Configuration public class WebMvcConfig implements WebMvcConfigurer { Value(${file.upload-path}) private String uploadPath; Value(${file.access-prefix}) private String accessPrefix; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(accessPrefix /**) .addResourceLocations(file: uploadPath /); } }这个配置让前端的访问地址跟后端真实存储位置解耦。浏览器请求http://localhost:8080/upload/202505/01/abc.jpg时Spring会根据这段映射去D:/upload/images/202505/01/abc.jpg寻找文件返回。注意addResourceLocations里的路径结尾一定要带斜杠否则资源解析会出问题。另外一个容易忽略的点路径前缀不要乱用。如果前端静态资源本身也部署在/upload路径下就会和后端这个映射冲突。我习惯把上传访问前缀设置为比较特殊的短语比如/upload、/file或者直接放在独立的域名下。4.4 参数细节大小限制、类型白名单与命名规则MIME类型判断是安全性的第一道门槛。在实际项目里不能只判断扩展名因为扩展名可以伪造。更稳妥的做法是同时校验file.getContentType()比如要求image/jpeg、image/png、image/gif。但也要知道contentType来自前端上传时浏览器给出的信息同样可以被篡改所以它只是基础校验不是安全边界。命名规则上文件路径一般不能太深、不能包含特殊字符。我采用的方案是yyyyMM/dd/UUID.ext好处有三个按日期归档方便排查和清理过期文件同一目录下文件数量不会无限堆积避免文件系统性能下降UUID保证文件名全局唯一。配置项建议值说明max-file-size5MB~10MB外卖菜品图不需要太大超过限制直接拒绝max-request-size加倍配置防止表单多字段导致请求超限扩展名白名单jpg/jpeg/png/gif等控制上传类型避免上传恶意文件存储路径项目外部绝对路径防止编译清理导致图片丢失访问前缀/upload 或独立域名隔离静态资源与业务接口这些参数不是拍脑袋写的。菜品图片如果原图过大加载会很慢影响页面体验。5MB看起来够用实际上现在手机拍出来的照片经常6~7MB所以我在生产推荐里会调到10MB然后配合前端压缩这样体验和安全都能兼顾。5. 踩坑实录文件上传调试中的常见问题与排查思路5.1 上传成功但访问图片404资源映射的URL没对齐我第一次调通上传接口、把URL存进数据库后打开页面图片却裂了。控制台显示请求/upload/202505/01/xxx.jpg返回404。排查下来发现.yml里的access-prefix写的是/upload而addResourceHandlers里配置的addResourceHandler却写成了/file/**两个前缀对不上URL自然找不到资源。这种问题定位主要还是靠看日志和请求地址。先手动在浏览器访问返回的URL看Spring是否处理了这个路径。如果404再去检查映射配置里的前缀和返回URL里的前缀是否一致。如果URL能访问但页面不显示那问题才转移到跨域和前端解析上。5.2 上传后重启服务图片就丢了别把文件写进项目工程目录有段时间我把上传目录配成了src/main/resources/static/upload开发环境跑得好好的一重启服务上传的图片全部消失。原因是Spring Boot多模块项目构建时会把src/main/resources下的内容重新拷贝到target/classes加上Idea里的热编译机制target目录被重构原有文件直接没了。从此之后我对上传目录的原则就一条配置到项目工程之外。开发机用D:/upload/images服务器用/data/upload。这样无论是打包还是重启都不会动到这些文件。另外既然目录在项目外部署时要注意目录权限否则Java进程没有写文件权限会报FileNotFoundException或AccessDeniedException。5.3 中文文件名乱码从源头用UUID解决有朋友问我中文文件名上传后浏览器访问会乱码怎么转码我的建议是不要跟编码问题硬刚。中文名加上空格、特殊符号在URL编码、容器路由、数据库存储几层之间来回转很容易出现不一致。与其到处补URLEncoder.encode不如在保存文件的那一刻就彻底丢掉中文名只用UUID。原文件名可以保存到数据库的另一个字段比如originalName方便运营人员查询和管理。展示给用户的时候图片URL里有没有中文根本不重要因为图片内容才是核心。这个取舍我在实际项目里用过很多次稳定可靠。5.4 前端拿到URL却打不开IP、端口和跨域一起排查开发环境里后端地址是localhost:8080前端页面可能是localhost:5173这类Vue开发端口。图片URL里如果直接写http://localhost:8080/upload/xxx.jpg浏览器访问时会有跨域问题因为图片所在的服务端口和页面端口不一致。解决办法有两种。一种是后端接口处理跨域允许前端域名访问图片资源另一种是把图片访问路径配置成后端域名通过Nginx反向代理统一转发。苍穹外卖项目开发阶段一般直接用后端接口返回URL前端配置代理或后端开启CORS。问题现象可能原因排查方向上传报413或空指针文件超过max-file-size检查multipart配置图片404上传目录或资源映射地址不对检查前缀配置和物理目录图片打不开跨域、IP写死、端口不对检查前端访问地址和后端CORS文件上传成功但为0字节transferTo目标路径错误检查目标目录是否可写上传后服务重启图片消失配置到了target目录迁移到外部独立目录5.5 小文件上传偶尔报空指针先看form字段名另一个实际中遇到过的问题是前端明明选了图片后端接口却收到null。去翻前端代码发现表单里字段名是multipartFile后端参数名却是file两边没对上。Spring在解析Multipart请求时是根据字段名找到对应MultipartFile的名字不一致参数就是null。这个只需要把名字对齐或者加RequestParam(multipartFile)注解问题就解决了。这类低级错误最容易被忽略我每次排查第1步就是确认字段名。数据库里存的图片URL也应该提前约定好存相对路径还是绝对路径。苍穹外卖原版返回的是相对路径前端自己拼上域名访问。如果数据库中存了http://localhost:8080/upload/xxx.jpg这种绝对地址部署环境一变老数据的图片就全都访问不了。我建议数据库里存相对路径渲染时由前端或网关拼接baseURL这样环境迁移时图片地址不会失效。6. 苍穹外卖学习后续怎么推进个人节奏建议6.1 从本地存储切换到对象存储项目往前再走一步本地存储跑通之后下一步我认为值得做的改造就是对象存储。具体流程是在云服务商创建存储空间开通访问密钥引入SDK依赖新增一个OssStorageService实现StorageService接口。上传逻辑从“写文件到磁盘”变成“将输入流传到对象存储”返回的URL由云服务商生成。这个改造过程大约半天时间但你对“依赖抽象、面向接口编程”的理解会上一个台阶。面试的时候如果能把“为什么上传模块设计成接口”、“切换OSS时业务层为什么没动”讲清楚会比单纯背SSM知识更有说服力。苍穹外卖项目号称“前后端分离项目”其实“存储分离”同样是工程能力的一部分。6.2 后面值得深入吃的模块订单、缓存、定时任务图片上传只是苍穹外卖学习的第一步。如果你准备面试我的建议是把学习路线串成链路而不是知识孤岛。比如菜品这条线分类管理→菜品管理→图片上传→Redis缓存→清理缓存策略一口气拉通。比如订单这条线用户登录→购物车→下单→支付→商家接单→WebSocket推送订单状态→数据统计。每个链路跑通之后再去补细节。苍穹外卖里值得继续挖掘的还包括基于ThreadLocal保存当前登录用户、用AOP自动填充创建时间和修改时间、用PageHelper处理分页、用Spring Task处理营业状态和定时统计、用Apache POI导出报表以及微信支付的预支付下单流程。这些技术点每个都可以写成一篇独立日记不需要一次全吃透。我自己的经验是学这种体量的项目不要追求“看一遍全记住”而是“每看一个模块就动手改一个模块”。改一次比看十遍印象都深。最后再分享一个体会。苍穹外卖本地图片上传这个功能看着简单其实把所有上传要面对的问题都涵盖了。我后来在真实项目中对接OSS、对接流媒体存储、做文件清理任务追根溯源靠的都是这段时间打下的基础。如果你也正在啃这个项目别只满足于让代码跑通尽量沿着“为什么这么做”往后多看一层。多看一层面试和工作中能解决的问题就多一类。下一篇日记我准备把订单状态流转和WebSocket推送这部分整理出来到时候再聊。