苍穹外卖这个项目做到Day3我原本的计划是直接铺菜品管理的增删改查结果刚动手就被一个“不起眼”的功能卡住了——菜品图片。前端要传图后端得把文件接住、存到本地、再返回一个能访问的URL整条链路不打通后面菜品模块怎么都做不踏实。所以Day3这一整天我就专心做了本地上传图片顺便把上传功能里那些容易踩的坑统统趟了一遍。这篇文章就当Day3的复盘笔记适合正在跟苍穹外卖课程、或者自己写管理系统碰到文件上传需求的同学参考。我尽量把每一步为什么这么做讲清楚而不是只贴代码让你抄。1. 为什么Day3把图片上传放在菜品管理前面1.1 Day2结束时的项目状态先说清楚这个项目做到哪一步了。到我Day3动手之前苍穹外卖的工程骨架已经能正常跑起来Spring Boot启动没有问题MySQL数据库连接通畅MyBatis的Mapper能查到数据员工登录接口配合JWT也调通了前端管理后台能看到返回的JSON数据。这些基础就绪之后下一步自然就是做菜品的增删改查。可菜品这个表和别的表不太一样它有一个image字段需要存一张图片地址。这就引出一个尴尬问题如果我先做增删改查图片字段填什么总不能在数据库里写死一个静态图片链接后面再做上传吧那样前端联调还得返工。所以我临时调整了计划Day3先做上传功能。这是项目开发里很常见的选择不是哪个功能看起来简单就先做哪个而是先做当前block住所有人的那个。1.2 图片上传是菜品模块的前置阻塞项菜品管理的界面长什么样做过后台系统的应该都能猜出来左侧一堆菜品分类右侧是菜品表格点新增或编辑会弹出一个表单表单里通常要选择菜品图片图片上传成功后再提交保存。如果没有上传接口前端开发就只能写死一个假图片等后端接口补齐后再回来改。这种返工虽然不复杂但很消耗精力而且容易出现“前端忘记替换图片地址”这种低级Bug。反过来先把上传接口做好菜品表单从第一天联调就是真实数据流程后面所有功能都建立在这条正确链路上。先做前置阻塞项后面的开发才会顺畅。1.3 一个上传接口背后牵扯的知识面很多人觉得上传图片不就是接一个MultipartFile然后写文件嘛两小时就搞定了。实际上这个功能真做起来牵扯的知识点并不少文件如何接收、格式校验怎么做文件存在哪里目录结构怎么组织本地磁盘路径如何映射成URL让前端能访问返回给前端的是什么格式图片回显路径怎么拼上传大小限制、重名文件、磁盘清理怎么处理后面如果换云存储代码怎么改动最小。这些点单独看都不难但串在一起就足够让一个新手踩半天坑。我Day3的时间基本都花在这些“边角料”上所以这篇复盘也按照这个顺序来写。2. 本地存储和云存储怎么选先跑通再迁移2.1 本地存储不是偷懒苍穹外卖或者类似的教学项目很多同学都会纠结一个问题我到底是直接接阿里云OSS还是用本地存储我的建议很明确Day3这种阶段先本地落盘。原因有三第一本地上传图片能把“文件上传”这件事的核心链路练明白。你亲手写了磁盘存储才会真正理解OSS那种返URL的设计到底解决了什么问题。直接调OSS接口你只是用了别人的SDK对上传本质的理解并不会加深。第二本地存储不依赖外网不依赖云账号调试最快。每天开发到一半突然去配置OSS的AccessKey还得考虑网络开通没必要。第三后面真正部署或者需要云存储时我们不是把代码推倒重写而是把上传逻辑抽成接口替换实现类。这一点我在第7章专门讲只要一开始设计对了迁移成本非常低。2.2 和对象存储的对比做一个简单的对比帮你看清楚为什么不着急上OSS对比维度本地磁盘存储阿里云OSS等对象存储开发调试速度快无需外网和密钥慢需要申请Bucket和AccessKey是否理解原理能看清文件流转全过程黑盒调用SDK存储成本低磁盘空间即可有少量费用虽然不高访问方式需要配置虚拟路径映射直接返回公网URL部署影响服务器重启、磁盘扩容要自己管无状态适合集群部署后续演进需要做接口抽象可以直接替换实现当然如果项目一开始就明确要求上云存储那是另一回事。但作为学习复盘项目本地存储绝对是Day3最合理的选择。2.3 我的最终选型本地磁盘加可替换接口Day3我采用的方案是代码层面定义一套上传能力目前先实现本地磁盘版本后面要换云存储的时候新增一个实现类就行。具体目录结构上我在服务器本地建了一个独立的上传目录没有放项目里面。这也是经验教训把上传文件放在项目目录里重新打包发布时容易冲突而且不方便备份。单独目录的好处是删了项目图片还在备份时只需要备份这一个目录。3. 上传接口实现Controller只做三件事3.1 接收文件、类型校验、落盘分离设计上传Controller时我给自己定了三条原则Controller层只负责接收参数和返回结果不处理文件IO校验逻辑单独拆出来文件存储逻辑放到Service层。这样后面换OSS时Controller几乎不用改。苍穹外卖项目里通常走统一返回结构ResultT这个Day2已经封装好了我这里直接复用。代码大致长这样RestController RequestMapping(/admin/common) Slf4j public class UploadController { Resource private StorageService storageService; PostMapping(/upload) public ResultString upload(RequestParam(file) MultipartFile file) { if (file null || file.isEmpty()) { return Result.error(文件不能为空); } String url storageService.upload(file); return Result.success(url); } }Controller里只做三件事接参数、判断非空、交给Service。后面哪怕我把存储实现从本地换成OSS这个Controller绝对是零改动。3.2 配置项与统一返回结构上传路径这种东西不应该硬编码在Java代码里我放在application.yml中统一管理file: upload-path: D:/upload/ # 本地磁盘存储目录 access-path: /upload/ # 对外访问的虚拟路径前缀这里注意upload-path末尾一定要带斜杠不然后面拼接文件路径会多出一道莫名其妙的目录层级。这个细节我踩过一次后面也经常被朋友问到干脆写在这里。Service的实现类比较关键本地磁盘版的逻辑分成四步生成唯一文件名、拼接存储路径、写入磁盘、返回访问URL。完整实现我放在下一节。3.3 本地存储Service完整代码Service Slf4j public class LocalStorageService implements StorageService { Value(${file.upload-path}) private String uploadPath; Value(${file.access-path}) private String accessPath; Override public String upload(MultipartFile file) { // 1. 校验文件是否为真实图片 checkImage(file); // 2. 生成唯一文件名保留原始扩展名 String originalFilename file.getOriginalFilename(); String ext getExtension(originalFilename); String newFileName UUID.randomUUID().toString().replace(-, ) . ext; // 3. 按日期分子目录方便后面清理和排查 String datePath LocalDate.now().toString(); // 例如 2025-06-08 File dir new File(uploadPath datePath); if (!dir.exists()) { dir.mkdirs(); } File dest new File(dir, newFileName); try { file.transferTo(dest); log.info(图片上传成功{}, dest.getAbsolutePath()); } catch (IOException e) { log.error(图片上传失败, e); throw new RuntimeException(文件保存失败); } // 4. 返回前端可访问的URL注意这里不带主机名 return accessPath datePath / newFileName; } }几个值得说的地方用UUID做文件名基本上可以告别重名问题还顺手解决了中文文件名乱码和特殊字符隐患按日期分子目录是我强烈建议加的一个小设计。不然所有图片平铺在一个目录里上千张图片之后打开文件夹都卡排查问题时也很难定位transferTo是Spring封装好的方法内部会处理临时文件迁移比自己拿InputStream复制靠谱。StorageService接口定义如下public interface StorageService { String upload(MultipartFile file); }定义接口的好处是后续新增OSS实现时只需要再写一个OssStorageService implements StorageService然后用Primary或者ConditionalOnProperty切换实现Controller、Service调用方全部不用动。4. 本地文件怎么变成可访问URL虚拟路径映射与回显链路4.1 为什么不能直接返回file路径我第一次做上传时直接存完文件就把绝对路径返回给前端了比如D:/upload/xxx.jpg。前端拿到这个路径放到img src里图片当然死活显示不出来。原因是浏览器并不知道file://这种本地路径指向的是哪台机器。前端的运行环境在用户浏览器里后端返回一个服务器本地路径浏览器根本访问不到。正确的做法是让后端通过HTTP协议把这张图片暴露出去也就是一个以http://开头的URL。所以存储服务返回的是/upload/2025-06-08/xxx.jpg这样的虚拟路径浏览器访问时实际请求的是http://localhost:8080/upload/2025-06-08/xxx.jpg这背后需要有一个机制把/upload/**映射到磁盘目录。4.2 WebMvcConfigurer里的资源映射Spring Boot本身不会把本地目录当作静态资源暴露需要自己写一个配置类Configuration public class WebMvcConfig implements WebMvcConfigurer { Value(${file.upload-path}) private String uploadPath; Value(${file.access-path}) private String accessPath; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(accessPath **) .addResourceLocations(file: uploadPath); } }这里我踩过一个坑addResourceHandlers的路径一定要加**而addResourceLocations的本地路径必须以file:开头。如果你写的是file:D:/upload/那没问题如果Windows路径忘了反斜杠或者拼错控制台不报错但浏览器访问永远404排查起来很恼火。如果上传目录在磁盘根目录要特别注意Windows下file:D:/upload/这个写法早期版本还需要写file:/D:/upload/这种三斜杠形式我用的是当前环境已验证的写法你如果遇到404也可以试试加斜杠。4.3 返回给前端的URL到底长什么样我的存储服务返回的是相对路径/upload/2025-06-08/9f8a91aa4e1345c6a1d3b9c8a0e2f1b3.jpg。前端拿到这个相对路径之后会在请求后端接口时拼接上当前访问域名。开发环境下如果前端页面跑在http://localhost:8080图片完整地址就是http://localhost:8080/upload/2025-06-08/xxx.jpg。这里有一个经验之谈存储服务返回时尽量不要把IP和端口拼进去。如果拼死了http://localhost:8080后面把后端ip换成服务器时数据库里存的所有图片地址就全部失效了。返回相对路径前端自动基于当前域名拼接部署换域名时完全不用改数据。5. 联调当天踩过的坑404、跨域、超限5.1 图片404十有八九是资源映射配置不对联调第一件事我用Postman调用上传接口返回URL正常但把URL粘贴到浏览器一打开就是404。排查思路从外到内先看浏览器访问/upload/xxx.jpg时后端Tomcat有没有日志确认请求确实打到了SpringBoot那就说明路由处理有问题检查WebMvcConfig有没有被扫描到。我当时的包扫描没覆盖到config目录配置类压根没生效再看addResourceHandler的参数是否和返回路径一致。后来我把config包移到了启动类同级的子包下404立刻解决。这个坑非常典型Spring Boot默认只扫描启动类所在包及其子包配置类放错位置写再多都不生效。5.2 跨域问题前端连不上还是图片加载不出来要分清联调中前端同学反馈图片上传成功后页面上的图片加载不出来控制台报跨域错误。先说结论图片加载的跨域报错其实很少真是后端不允许跨域。浏览器加载img src是不受同源策略限制的报跨域通常是因为前端在后端接口里设置了crossOrigin属性或者用了Canvas之类的API去操作图片才会被拦截。真正的跨域问题往往出现在上传接口本身调用失败。开发环境下Vite前端跑在5173端口后端跑在8080端口前端去请求/admin/common/upload如果不做代理或者不加CORS配置请求根本到不了后端。我的处理方式是在后端加了个全局CORS配置Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }但这里要提醒一句这个配置适合开发环境放生产环境前要根据实际域名收紧allowedOriginPatterns不然等于把接口完全暴露给任何来源。5.3 上传文件大小超限Spring默认只让你传1MB上传过程中最经典的坑就是传一张稍微大点的图片后端直接抛异常错误信息类似The field file exceeds its maximum permitted size of 1048576 bytes.1048576字节就是1MB这是Spring Boot的默认上传大小限制。点餐系统里用户拍的照片动辄好几MB1MB根本不够用。解决方式是在application.yml里调整spring: servlet: multipart: max-file-size: 20MB max-request-size: 20MBmax-file-size限制单个文件max-request-size限制一次请求的总大小。我习惯把两者设置成一样避免出现“一个文件没超但多个文件加起来超了”的迷之错误。除了Spring这一层如果你的项目还配置了Tomcat的maxSwallowSize也要注意。默认情况下Tomcat会消耗掉这些上传数据但如果设了代理层如Nginx还要同时检查Nginx的client_max_body_size我见过很多后端调好了前端上传还是报413最后发现是Nginx卡住了。6. 上传功能的边界防护清单6.1 扩展名校验为什么不能只看后缀上传接口开放出去之后最怕的就是被人传一些奇奇怪怪的文件上来。有些人会直接传一个.jsp还有些人会做一个伪装成图片的脚本。我Day3的校验分两层第一层看扩展名白名单机制private static final SetString ALLOW_EXT Set.of(jpg, jpeg, png, gif, webp, bmp);第二层用ImageIO读取判断它到底是不是一张真实可解码的图片。这一步能挡掉大部分伪造文件try (InputStream in file.getInputStream()) { BufferedImage image ImageIO.read(in); if (image null) { throw new RuntimeException(文件不是有效图片); } } catch (IOException e) { throw new RuntimeException(文件读取失败); }逻辑很简单但效果很好。ImageIO.read如果读不出图像数据直接返回null我们就拒绝保存。这样就算别人把一个改名为.jpg的脚本传上来也无法通过真实解码校验。6.2 重名策略和磁盘清理虽然UUID基本保证了不重名但我在第3章里还加了日期子目录这就是给后续运维留的口子按天目录存放清理时可以直接按目录删排查问题时能根据图片URL里的日期快速定位文件后面做云存储时这种路径习惯迁移也毫无障碍。另外要说一个很多人忽略的问题图片上传容易清理难。我在项目里写了一个简单的清理规则每天凌晨用定时任务扫描上传根目录删除超过30天且菜品表中没有任何引用的图片。这里一定要先查引用再删除否则用户上传了一张图还没选入菜品就被定时任务删掉了前端就会变成裂图。6.3 目录穿越与文件路径注入如果文件名直接用了用户上传的原始名称就有路径注入风险。构造一个../../etc/passwd之类文件名保存时可能会写到上传目录之外的任意位置。我的处理非常简单高效新文件名完全由UUID生成扩展名从白名单校验后的原文件名中提取。用户传什么名字我们都不关心只关心扩展名从源头杜绝了路径注入。另外上传目录本身也不要有执行权限如果用的是Linux服务器给目录设置755权限就够了。这些细节平时不起眼真出安全事故时才想起来补代价往往已经很大。7. 后续演进把上传实现从磁盘换成OSS7.1 为什么要预留这一层本地存储只适合单机开发和小规模部署。一旦项目上了多台后端服务器就出现一个致命问题用户A上传图片落在了服务器1用户B访问时请求被负载均衡转发到服务器2服务器2上根本没有这张图片裂图。所以项目部署到生产环境后通常都会把图片存到OSS这类中心化存储上。这也是我Day3坚持定义StorageService接口的原因不是为了炫技是真的能省后面大量重构的时间。7.2 改造步骤将来切OSS只需要三步第一步新增OssStorageService实现StorageService在内部调用OSS SDK把MultipartFile上传到指定Bucket返回公网URL。第二步在启动类或者配置类中通过ConditionalOnProperty控制实现类。例如配置一个storage.typelocal本地开发用本地实现生产环境改成storage.typeoss无需改任何Controller代码。第三部把数据库中已经存在的旧图片地址做一次迁移把/upload/2025-06-08/xxx.jpg这种相对路径迁移成新的OSS URL。因为我在Day3返回的就是相对路径这里反而好处理只需要在Java代码里拼一个前缀即可如果当初把IP域名写死了迁移时就得逐条改数据库了。这也是我一直在项目里坚持“返回相对路径、不拼死域名”的根本原因。很多时候一个小习惯就能省掉后面一次大手术。Day3做完我再回头反思这个上传功能最大的收获反而不是会写了多少代码而是明白了软件开发里“先跑通再优化”这句话的含金量。本地存储和OSS并不对立它们只是同一个能力在不同阶段的两种实现。只要把接口设计好后面换只是时间问题。
