一个典型的崩溃现场订单模块用MultipartFile直接写本地磁盘用户模块自己封装了一套临时文件工具支付模块干脆把文件存进了数据库。三个系统三种风格代码互相复制又互相修改每次加存储需求都像拆雷。更刺激的是某天凌晨磁盘突然满了查日志发现是上传接口没做大小限制生产环境直接被一张“自拍”撑爆。文件上传从来不是“一个接口存文件”这么简单它是横跨IO、安全、异常、异步、配置的复合工程。要设计可复用的文件上传模块画清接口边界是起点。Controller只负责解析请求、调用服务、返回结果核心业务逻辑全部下沉到UploadService。这个服务接收MultipartFile、业务类型、自定义存储路径返回一个包含访问URL、文件大小、存储引擎标识的UploadResult。接口越窄复用越深。那些把HttpServletRequest直接传到Service层的方法注定无法跨项目共用也会让单元测试变得痛苦不堪。记住Controller的职责永远是“翻译HTTP”而不是“代管文件”。别小看MultipartFile它就是那个最容易泄漏细节的源头。Spring绑定的MultipartFile确实提供了getBytes和getInputStream但直接把Servlet的MultipartFile传到存储层会让下层依赖Web框架将来你想把存储逻辑单独抽成jar包都会遇到障碍。我在模块内部定义了一个FileDescriptor只保留原始文件名、ContentType、输入流和大小所有存储实现只认这个DTO。同时凡是打开过的流必须关闭最好用try-with-resources否则你在Linux上迟早会遇到“too many open files”的惊魂时刻。这个错误通常不会在测试环境出现因为你的本地机器文件句柄限制和服务器差了好几个数量级。存储层抽象是护城河。定义一个StorageService接口方法只有两个put(FileDescriptor, String path) 和 delete(String fileKey)。本地磁盘、阿里云OSS、腾讯云COS、MinIO各写一个实现类业务代码只依赖StorageService用ConditionalOnProperty按配置切换。但这里有个关键差异OSS返回完整URL本地返回相对路径所以接口的返回值必须是一个统一对象比如StoredFile字段包括fileKey、url、size、storageType。如果直接返回String你迟早会因为拼接URL而陷入一团乱麻。而且每个存储实现应该自行处理内部细节本地存储要负责创建多级目录OSS要处理分片上传MinIO要配置匿名桶。写本地存储实现时最容易被忽视的是路径拼接。我见过有人直接用 号拼字符串结果传入了 ../ 就能把文件写到根目录外。永远不要相信外部传入的相对路径哪怕是业务方给的。正确的做法是在配置对象里固定一个根目录然后用Path.resolve(fileKey) 来生成最终路径同时检查生成的绝对路径是否以根目录开头。另外存储目录最好按业务类型/年月来分层比如upload/avatar/202401/xxxxxxxx.jpg这样既能分散单目录文件数量也方便做生命周期管理。一个好的文件路径设计能让你省掉后续无数个“清理脚本”。文件名处理是安全的第一道防线。很多漏洞都是靠恶意文件名触发的比如../../etc/passwd 或者带NULL字节的名字。最稳妥的做法是用UUID或时间戳生成新的存储名后缀名从白名单中取原文件名仅仅用于展示。永远不要使用用户上传的原始文件名去拼拼接路径。不过UUID会丢失原文件的可读性所以可以在名称里嵌入业务含义比如用了user-upload-{userId}作为目录。另外如果要做下载中文文件名需要做RFC 5987编码否则浏览器会给你一串乱码。还要注意文件名长度UUID加后缀通常没问题但有时别的系统会生成超长文件名你必须截断到255字节以内。文件类型校验不能只看后缀。HTTP头里的content-type和文件扩展名都可以伪造真正可靠的校验是读文件头的魔数。我用Tika或jMimeMagic读取前几个字节JPEG是FFD8FFPNG是89504E47。对图片文件再用ImageIO二次解码确认能被识别。这能拦住大多数“假图片真木马”但要注意魔数校验会多读一次IO千万别在内存里把整个文件都加载进来。做法是先读取前8个字节封装成ByteArrayInputStream然后在原始输入流中标记(reset)后继续传递。校验与存储分离是保持模块清晰的关键。异常处理不是简单的try-catch。上传过程会有文件过大、格式不支持、存储服务不可用、磁盘写满等状况。我习惯定义几个具体的运行时异常——UploadException、FileTypeNotAllowedException、StorageConnectException再写一个RestControllerAdvice统一映射到错误响应对象。这样做的好处是前端只需要一套错误解析逻辑后端挖坑也不会炸到用户面前。底层异常不出模块门这是可复用模块的基本底线。同时不要忘了在异常处理时清理已经产生的临时文件上传失败后的垃圾文件比正常文件更恶心因为它不占业务量却在悄悄侵蚀磁盘。异步上传是性能优化的一把利器但用不好会变成磁盘杀手。大文件同步上传会让Tomcat线程长时间挂起所以可以把文件先落临时目录立刻返回一个任务ID后台用CompletableFuture搬移到最终路径再更新状态。但临时目录必须配一个守护任务每隔几分钟清一次否则你会亲自体验磁盘被占满的后果。异步不是银弹适合大文件和远程存储小文件同步反而更快。如果你要做秒传可以在上传前先计算文件的MD5查询元数据表是否已有相同哈希如果存在直接返回已有URL省去整个上传流程。MD5可以在流式写入时顺便计算不要额外读一遍文件。分片上传是另一个实战高频需求但它不该直接躺进文件上传模块的核心。大文件的分片、合并、进度上报往往和存储供应商强相关。比如本地存储可以直接用RandomAccessFileOSS有multipartUpload API它们的进度和缓存逻辑迥异。我建议把分片流程做成独立接口放在上传模块的扩展包中默认提供基于FileChannel的本地分片实现。合并时需要同时校验每个分片的MD5防止传输过程中数据损坏。分片上传的复杂度是业务复杂度不是模块复杂度不要把简单需求拖进重型设计。测试才算可复用的试金石。一个模块的可复用性可以从它的测试代码优雅程度看出来。我习惯用JUnit的TempDir来模拟临时目录用MockMultipartFile构造请求体再给StorageService写一个内存实现专门跑Service层的测试。重点验证上传成功、覆盖、删除、非法后缀、超大文件、异常路径映射这些场景。如果你发现测试代码比业务代码还难写八成是模块的接口设计已经烂了。另外在CI流水线里要单独跑存储相关测试因为本地环境可能没有OSS或MinIO你可以用MockWebServer模拟HTTP接口但不要真的去连云服务否则一次故障演练就能打垮整个测试集。给模块留好扩展点而不是把功能写死在核心流程里。上传成功后可能需要缩略图、异步清理旧文件、通知下游系统这些需求不适合改UploadService。我选择用Spring的ApplicationEvent发布FileUploadEvent让其他模块通过EventListener监听并做后续动作。听起来只是多了一行代码但让核心模块保持了边界。别把功能写在别人的肩膀上而是把钩子放在自己的骨架上。发布事件时把FileDescriptor和相关业务上下文塞进去监听器只读不写这样即使某个监听器崩溃也不会影响上传主链路。如果需要完全解耦就引入消息中间件。配置是模块的门面。在我的实战项目里前缀是file.upload属性包括storageType、local-root、max-size、allowed-extensions、generate-random-name。用ConfigurationProperties绑定为UploadProperties存储实现只认这个配置对象。一个模块如果连配置都写不进application.yml它就不配叫可复用。另外切换存储引擎通常需要重启生效如果一定要热切换可以用动态代理加缓存但那样复杂度会陡增普通项目不建议碰。配置文件里的最大上传值要和Spring Boot的spring.servlet.multipart.max-file-size保持一致否则会出现“配置写好了实际依然报错”的经典困惑。上传模块的监控指标同样值得设计。上传成功率、平均耗时、文件大小分布、存储引擎错误率这些数据能帮你提前发现磁盘问题或云服务异常。我习惯通过Micrometer注解或手动上报把指标命名成upload.success、upload.failure、upload.size等。最重要的是记录当前临时目录的剩余空间低于阈值时立刻告警。一个没有监控的上传模块就像没有仪表盘的航班你只能靠乘客尖叫来判断是否出了事故。关于可复用的边界还有一个容易被忽略的讨论。不要为了抽象而抽象简单场景下一个UploadController加一个FileService就够用了。但如果你手头已经有两个以上业务模块需要存储文件或者产品经理反复想换存储供应商那就是时候投入重构。更彻底的做法是把上面这些抽象打成一个spring-boot-starter内部通过autoconfiguration装配外部只需一行依赖和少量配置。这就是SpringBoot生态的极致——把基建沉淀成内部产品让业务开发只关心业务。事实上很多公司的技术中台就是这么诞生的从一个被反复复制粘贴的上传模块逐渐演变成一个标准化的starter。你可以把版本号发到内部仓库让所有项目共享这才是实战意义上的“可复用”。