1. 整合的核心价值与整体设计思路1.1 为什么 Spring Boot 3 MinIO 是这个组合最近做后台管理系统又遇到文件存储的老问题本地磁盘扛不住大文件单机目录挂了文件全没扩展起来还得手动折腾。翻来覆去最终还是选了 MinIO 配合 Spring Boot 3.5.8 这套组合。MinIO 的部署足够轻量一个二进制文件就能跑起来兼容 Amazon S3 协议将来万一嫌弃它了切换到云厂商的对象存储几乎不用改业务代码。而 Spring Boot 3.5.8 正式把 Jakarta EE 作为基础内置的依赖管理和自动配置比 2.x 时代更干净配合新版 Java 的虚拟线程等特性做起 IO 密集型的文件上传下载服务体验确实不一样。很多人一上来就追问哪个版本配哪个版本这个问题其实没有绝对答案但当前这个搭配Spring Boot 3.5.8 MinIO Java SDK 8.5.9是我实测过最稳的一组组合。Spring Boot 3.x 要求 JDK 17 起步MinIO Java SDK 8.5.x 同样基于 JDK 8 设计但内部的 okhttp、okio 依赖版本和 Spring Boot 3.x 的依赖管理刚好没有硬冲突。这意味着你可以少写一堆exclusions直接引入就能跑。1.2 版本兼容性分析与方案选型先说结论Spring Boot 3.5.8 是好动的版本号MinIO SDK 8.5.9 是对接 S3 协议最常用的客户端版本之一。两个版本都正好处于生态中比较成熟的阶段尤其 MinIO 8.5.x 修复了此前若干上传临时凭证和流式读取相关的边缘 bug整合到 Spring Boot 3.x 中踩坑的概率比早期版本低不少。这里有个关键背景要交代MinIO 官方其实提供过一个minio-io的 spring boot starter但那个 starter 更新节奏慢很多 Spring Boot 3.x 的自动配置特性没有跟上。所以我的建议是不要用那个官方 starter直接引入io.minio:minio:8.5.9这个纯粹的 Java SDK然后自己写一个配置类注入容器。原因有三自制配置类可以精确控制MinioClient的创建参数比如连接超时、读写超时、自定义 HTTP 客户端等。starter 自动配置的灵活性有限一旦业务需要连接多个 MinIO 服务比如跨机房数据迁移自写配置类更从容。排查依赖冲突时少一个中间层出了问题定位也就是自己的代码 SDK 两处。2. 环境准备与依赖配置2.1 基础设施准备在动代码之前先把 MinIO 服务端跑起来。如果你是第一次接触我建议别直接上 Docker先在本地用二进制方式跑通全流程方便观察路径和行为。下载 minio 服务端可执行文件后命令行开启# 指定 MinIO 的数据目录和控制台端口 ./minio server D:/minio/data --console-address :9001默认 API 端口是9000控制台端口是9001启动日志里会打印默认的 Access Key 和 Secret Key默认都是minioadmin浏览器打开http://localhost:9001就可以登录后台。如果是测试环境这个默认账号足够用如果是生产必须第一时间改掉并且建议为每个业务模块创建独立的 key 和独立 bucket避免一把钥匙开所有锁。启动稳定后我习惯先用控制台手动创建一个 bucket 来验证连通性。当然代码里也可以在MinioClient初始化完成后自动创建 bucket这个后面会给出具体实现。测试阶段手动创建能让问题定位时少一个变量。2.2 Maven 依赖引入与冲突规避Spring Boot 3.5.8 项目通常用 Maven 管理依赖。核心依赖就两个dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdio.minio/groupId artifactIdminio/artifactId version8.5.9/version /dependency如果你还需要做文件类型校验、生成缩略图之类的操作可以再补spring-boot-starter-validation和net.coobird:thumbnailator但核心整合不需要额外东西。这里特别提一下okhttp的问题。MinIO SDK 内部通过 okhttp 做 HTTP 通信8.5.9 版本依赖的是 okhttp 4.x 系列。Spring Boot 3.5.8 的依赖管理并没有强制覆盖 okhttp 版本所以一般情况下两者和谐共存。但如果你项目里另外引入了别的 SDK比如某些云服务的 Java SDK它可能把 okhttp 3.x 或更老的版本传递进来这时候就会报类似NoSuchMethodError的运行时错误。解决办法很简单统一用 Maven 的dependencyManagement把 okhttp 版本提升到 MinIO 内置的 4.x 版本或者排除掉旧传递依赖。dependencyManagement dependencies dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.12.0/version /dependency /dependencies /dependencyManagement2.3 配置文件与参数设计接下来是配置文件。application.yml里我习惯把 MinIO 相关的参数独立出来不要混在其他业务配置里方便后续按模块拆分。minio: endpoint: http://127.0.0.1:9000 access-key: minioadmin secret-key: minioadmin bucket: techblog-bucket # 连接超时时间毫秒默认 30000 connect-timeout: 30000 # 读取超时时间毫秒默认 60000 read-timeout: 60000 # 写超时时间毫秒默认 60000 write-timeout: 60000几个容易被忽略的细节endpoint最后不要带斜杠/否则后续拼 URL 时可能出现双斜杠问题。bucket名称在 MinIO 中只能是小写字母、数字和中划线不能有大写字母和下划线这也是 S3 协议的通用限制。生产环境中 access-key 和 secret-key 不建议直接写在 yml 里至少用环境变量或配置中心动态注入。3. 配置类与 SDK 初始化3.1 属性绑定类从 Spring Boot 3 开始ConfigurationProperties的用法发生了一点变化。在 2.x 时代你可以在配置类上直接加上EnableConfigurationProperties或者用Component让 Spring 自动扫描。在 Spring Boot 3.x 中最稳妥的做法是单独写一个属性类然后在配置类上手动启用。package com.example.minio.config; import org.springframework.boot.context.properties.ConfigurationProperties; /** * MinIO 配置属性绑定类 */ ConfigurationProperties(prefix minio) public class MinioProperties { private String endpoint; private String accessKey; private String secretKey; private String bucket; private long connectTimeout 30000L; private long readTimeout 60000L; private long writeTimeout 60000L; // getter / setter 省略可以选择用 Lombok Data }这里有个 Spring Boot 3.x 特有的坑如果你在SpringBootApplication启动类上只用了ConfigurationPropertiesScan那没问题属性类会被自动扫到如果没加一定要在配置类上用EnableConfigurationProperties(MinioProperties.class)显式注册否则属性类不会生效所有参数都是默认值然后你会莫名奇妙地连不上 MinIO 服务。3.2 MinioClient 配置类MinioClient的构建在 8.x SDK 中需要走builder模式。我把超时时间一并设置进去提升大文件上传时的稳定性package com.example.minio.config; import io.minio.MinioClient; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration EnableConfigurationProperties(MinioProperties.class) public class MinioConfig { Bean public MinioClient minioClient(MinioProperties properties) { return MinioClient.builder() .endpoint(properties.getEndpoint()) .credentials(properties.getAccessKey(), properties.getSecretKey()) .connectTimeout(properties.getConnectTimeout()) .readTimeout(properties.getReadTimeout()) .writeTimeout(properties.getWriteTimeout()) .build(); } }构建MinioClient本身不发起任何网络请求所以这里不会因为配置错误立即报错。错误会在第一次真正读写时暴露后面我们会专门讨论排查方法。3.3 连接测试与健康检查每次整合完我习惯先写一个极简的连通性检查列出所有 bucket。不要小看这一步它能排查 80% 的配置问题。Component public class MinioHealthChecker { private final MinioClient minioClient; public MinioHealthChecker(MinioClient minioClient) { this.minioClient minioClient; } public ListString listBucketNames() throws Exception { return minioClient.listBuckets().stream() .map(bucket - bucket.name()) .toList(); } }如果是 Spring Boot 3 项目想做得更优雅可以直接把这段逻辑嵌到ApplicationRunner里项目启动时自动检查一次并打日志或者申请一个/actuator/health的HealthIndicator让运维可以通过端口探活判断 MinIO 连接是否正常。具体方式可以根据团队习惯选但检查动作必须有。4. 文件操作核心封装4.1 上传核心逻辑MinIO 8.x SDK 的上传 API 和旧版本有较大差异。旧版的putObject(String bucketName, String objectName, InputStream inputStream, long size, String contentType)那套方法已被移除现在强制使用PutObjectArgs构建参数。这也让调用方式更规范能逼着业务方仔细考虑文件大小和内容类型。package com.example.minio.service; import io.minio.MinioClient; import io.minio.PutObjectArgs; import org.springframework.stereotype.Service; import org.springframework.web.multipart.MultipartFile; import java.io.InputStream; import java.util.UUID; Service public class MinioStorageService { private final MinioClient minioClient; private final MinioProperties minioProperties; public MinioStorageService(MinioClient minioClient, MinioProperties minioProperties) { this.minioClient minioClient; this.minioProperties minioProperties; } public String upload(MultipartFile file) throws Exception { String originalFilename file.getOriginalFilename(); String objectName generateObjectName(originalFilename); String contentType file.getContentType(); long size file.getSize(); try (InputStream inputStream file.getInputStream()) { minioClient.putObject( PutObjectArgs.builder() .bucket(minioProperties.getBucket()) .object(objectName) .contentType(contentType) .stream(inputStream, size, -1) .build() ); } return objectName; } private String generateObjectName(String originalFilename) { String suffix ; if (originalFilename ! null originalFilename.contains(.)) { suffix originalFilename.substring(originalFilename.lastIndexOf(.)); } return UUID.randomUUID().toString().replaceAll(-, ) suffix; } }注意stream(inputStream, size, -1)三个参数的含义第一个是输入流第二个是已知文件大小第三是分片大小传-1表示 SDK 自动决定分片大小。如果你的size传的和实际流长度不一致上传可能失败或者数据损坏。所以MultipartFile在这里特别方便因为它直接暴露getSize()。如果你自己构造InputStream而不是从MultipartFile来一定提前确认流的长度必要时先将流读入字节数组再计算 size避免之后踩坑。另外contentType务必设置。如果不设置某些文件下载时浏览器可能会直接当成二进制流而不是内嵌预览比如png图片没设置contentType访问地址时浏览器会直接下载而不是打开显示图片。4.2 下载与流式处理下载是另一个必须熟练掌握的操作。对象存储不像普通文件系统那样有路径寻址的概念获取内容必须通过GetObjectArgs拉流。public InputStream download(String objectName) throws Exception { return minioClient.getObject( GetObjectArgs.builder() .bucket(minioProperties.getBucket()) .object(objectName) .build() ); }这段代码看起来简单却有一个隐藏的坑拿到InputStream之后你必须负责finally里关闭它否则会一直占用底层 HTTP 连接。底层 okhttp 连接不释放时间一长连接池耗尽后续请求全部卡住。我见过团队线上故障排查到最后发现就是下载接口忘了关流最终表现为无明显规律的 503/504 错误。更稳妥的写法是不要在 Service 层返回InputStream而是直接返回ResponseEntity利用 try-with-resources 让请求响应完成后自动关闭GetMapping(/download/{objectName}) public ResponseEntityResource downloadFile(PathVariable String objectName) throws Exception { // 从 MinIO 获取文件元信息比如大小和类型。部分场景不需要可以先省略 MinioStorageInfo fileInfo storageService.getFileInfo(objectName); InputStream stream storageService.download(objectName); byte[] data stream.readAllBytes(); stream.close(); return ResponseEntity.ok() .contentType(MediaType.parseMediaType(fileInfo.getContentType())) .header(HttpHeaders.CONTENT_DISPOSITION, attachment; filename\ objectName \) .body(new ByteArrayResource(data)); }这里直接readAllBytes()简单粗暴适合中小文件。大文件推荐用StreamingResponseBody或设置Content-Length后分段写出不然会有一大块字节数组堆在内存里并发场景下分分钟 OOM。说回 MinIO 本身SDK 返回的InputStream是实现了AutoCloseable的所以最推荐的做法是业务代码里统一用 try-with-resourcestry (InputStream stream storageService.download(objectName)) { // 业务处理 }始终记住原则谁打开谁关闭。4.3 删除与桶管理删除操作在 8.x SDK 里同样走参数对象public void delete(String objectName) throws Exception { minioClient.removeObject( RemoveObjectArgs.builder() .bucket(minioProperties.getBucket()) .object(objectName) .build() ); }如果说上面这些操作还算常规那桶管理的价值就体现在动态化和自动化上了。实际项目中经常遇到这种需求一个企业客户开通账号后系统需要给它分配一个独立的 bucket让文件在逻辑上隔离。这时在代码里动态建桶就很方便public void ensureBucketExists(String bucketName) throws Exception { boolean exists minioClient.bucketExists( BucketExistsArgs.builder() .bucket(bucketName) .build() ); if (!exists) { minioClient.makeBucket( MakeBucketArgs.builder() .bucket(bucketName) .build() ); } }调用bucketExists会发起一次真实的 HTTP 请求如果你有大量桶需要检查尽量批量处理不要一次业务请求里循环检查几十次性能会很难看。关于 bucket 的读写权限MinIO 默认是 private所有操作都需要签名认证。如果某个 bucket 里的文件要公开访问比如产品图片、用户头像可以在控制台给 bucket 设置匿名下载策略。我不推荐对所有 bucket 一律公开尽量只对需要 CDN 加速或网页直接展示的目录做最小限度的公开策略。5. 实战一个可直接落地的文件服务接口5.1 Controller 实现有了上面的 Service 封装Controller 就是简单的拼装组合。这里给一个可直接落地的例子包含文件上传、下载、删除三个核心接口package com.example.minio.controller; import com.example.minio.dto.UploadResult; import com.example.minio.service.MinioStorageService; import org.springframework.http.HttpHeaders; import org.springframework.http.MediaType; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import org.springframework.web.multipart.MultipartFile; RestController RequestMapping(/api/v1/files) public class FileController { private final MinioStorageService storageService; public FileController(MinioStorageService storageService) { this.storageService storageService; } PostMapping(/upload) public UploadResult upload(RequestParam(file) MultipartFile file) throws Exception { String objectName storageService.upload(file); // 假设 MinIO 可被公网或内网以访问方式 fetch 到这里拼一个临时访问地址 String url storageService.getPresignedUrl(objectName); return new UploadResult(objectName, url); } GetMapping(/download/{objectName}) public ResponseEntitybyte[] download(PathVariable String objectName) throws Exception { var info storageService.getFileInfo(objectName); byte[] content storageService.downloadBytes(objectName); return ResponseEntity.ok() .contentType(MediaType.parseMediaType(info.getContentType())) .header(HttpHeaders.CONTENT_DISPOSITION, attachment; filename\ objectName \) .body(content); } DeleteMapping(/{objectName}) public ResponseEntityVoid delete(PathVariable String objectName) throws Exception { storageService.delete(objectName); return ResponseEntity.noContent().build(); } }这里getPresignedUrl是另一个高频接口。MinIO SDK 支持生成临时签名 URL即给客户端一个带有效期的直传或直读链接避免所有流量都经过应用服务器。比如用户提交表单后前端拿着这个临时 URL 直接把文件 POST 到 MinIO应用只负责生成 URL 和管理元数据极大减轻了后端带宽压力。public String getPresignedUrl(String objectName) throws Exception { return minioClient.getPresignedObjectUrl( GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(minioProperties.getBucket()) .object(objectName) .expiry(60 * 60) .build() ); }expiry的单位是秒最大值是 7 天604800 秒。如果你配了个大于 7 天的值SDK 不会报错但生成的 URL 实际上不生效排查时容易忽略。所以项目里如果要长期预览别直接上临时链接建议换成绑定自定义域名并配置 bucket 内文件的公开读取策略。5.2 大小限制与参数调优文件上传接口和普通 JSON 接口不同Spring MVC默认单次请求大小限制是 1MBTomcat默认最大请求体是 2MB。如果没改配置传稍大一点的文件直接报 413 或 500。改配置如下spring: servlet: multipart: max-file-size: 100MB max-request-size: 100MB这里特别提醒max-file-size单文件上限max-request-size是整个请求的总和。如果你支持一次传多个文件后者必须大于所有文件之和否则多文件上传时前端明明没超上限后端却报错。另外Spring Boot 3.x 中如果设置了server.tomcat.max-swallow-size等参数注意和 multipart 配置之间的协作。有些场景下请求体超过限制后异常处理不够优雅建议给 Controller 加一个ExceptionHandler(MaxUploadSizeExceededException.class)返回结构化 JSON 错误而不是默认的错误页。说到大文件不得不提分片上传。MinIO Java SDK 8.5.9 本身对超过 128MB 的文件会自动采用分片上传这个阈值是服务端的默认行为。但从客户端整体体验看我更推荐实现自己的分片流程前端把文件切成 5~10MB 的小块后端逐个调用putObject最后通过composeObject合并。这套方案的好处是可以做断点续传和并行上传坏处是代码复杂度明显增加。对于大部分内部系统单文件 100MB 以内直接让 SDK 自动处理就足够了。6. 排查实录与避坑清单6.1 依赖冲突老问题的新表现我在 3.x 项目中遇到最多的报错是这类java.lang.NoSuchMethodError: okhttp3.Request$Builder okhttp3.Request$Builder.tag(java.lang.Class, java.lang.Object)出现这个错误几乎可以肯定是项目里存在多个不同大版本的 okhttp。MinIO SDK 8.5.9 默认需要 okhttp 4.x但某些其他第三方库塞进来一个 okhttp 3.x。排查时先执行mvn dependency:tree -Dincludescom.squareup.okhttp3看看传递依赖的版本树然后对冲突源头做exclusions。由于 okhttp 3.x 到 4.x 的包名没变只是类方法变了所以报错都是 NoSuchMethodError不会在编译期暴露只能在运行时炸出来。这类问题最好在项目初期就查清楚别等到上线。另外MinIO 8.5.x 还依赖com.squareup.okio如果 okio 版本过低会出现okio.BufferedSource相关的方法找不到。同样用排除传递依赖并把okio版本拉高到 3.x 系列。一般来说以 Maven 传递依赖的顶格版本为准很难出问题。6.2 兼容性错误从 javax 到 jakarta 的迁移很多 2.x 老项目升级到 Spring Boot 3.x 后会发现javax.servlet.*相关的类全都报红。MinIO SDK 里并没有直接依赖javax.servlet但如果你在 Controller 里用HttpServletRequest或者MultipartFile注意导入包名都换成了jakarta.servlet.*和jakarta.annotation.*。这一条属于基础适配不算 MinIO 特有坑但整合时容易一起出现。还有一个和 Spring Boot 3.x 自动配置相关的坑在 Spring Boot 3.2 之前MultipartAutoConfiguration的判定条件相对宽松3.5.x 中如果项目里引入了spring-boot-starter-webflux或者手动添加了冲突的 servlet 依赖文件上传接口可能直接 404 或者 415。排查思路是先把 webflux 排除确认只用 servlet 栈。6.3 常见问题速查表这里整理一下我实测过程中高频踩中的问题按症状、原因、解决方案列出来方便大家直接检索。症状常见原因解决方案启动时没有任何报错但第一次上传报 connection refusedMinIO 服务端没启动或者 endpoint 端口写错先 telnet 确认 9000 端口通不通再检查 yml 配置上传报 InvalidBucketNamebucket 名含大写字母、下划线或长度不合法统一改成小写字母 中划线长度 3 到 63 位上传报 Stream length mismatch传入的 size 和实际流长度不一致确保 size 是真实已知值不要随便传 0 或动态估算值文件下载后浏览器当附件下载而不是预览contentType没有设置或设置成了application/octet-streamputObject时显式传content-type字段并发上传较多时出现超时连接数不够或 HTTP 连接池耗尽调大connectTimeout/readTimeout并复用同一个MinioClient实例通过临时 URL 拿文件时 403签名过期、系统时间不一致、secret key 配置错误检查服务器时间是否偏差过大检查 expiry 是否超过 7 天上传 100MB 以上的文件报 413Spring 的 multipart 限制调大max-file-size和max-request-size并确认网关层没有限制6.4 你可能会忽略的连接池问题MinioClient内部基于 okhttp 实现每次new MinioClient都会创建一个新的连接池。最错误示范就是在每次上传时都MinioClient.builder().build()一个新实例这等于让每个请求都创建新连接池短连接建立成本很高最终表现为连接总数不可控Socket 描述符耗尽。正确做法是像第 3 节那样把MinioClient声明为 Spring Bean 单例全局复用同一个连接池。如果确实有多套 MinIO 环境那就按环境创建多个 bean每个 bean 内部都有自己的连接池不要在一个 bean 里动态切换连接地址。6.5 流关闭与异常处理的教训这部分是我真正吃过亏的地方。当时一个内部文件中心download接口频繁调用发现服务运行几天后 JVM 老年代占用持续爬升HTTP 连接数一直在涨。后来追查发现是 Service 层返回InputStream让 Controller 使用但使用方拿到流之后代码写在 if 分支里该分支抛异常后没有关流导致连接长期不释放。这个问题的本质不是 MinIO 的问题而是你在整合时必须对流的生命周期有明确契约。所以我在团队里定的规矩很朴素Service 层不直接返回InputStream给 Controller。要么返回byte[]小文件要么返回Resource或StreamingResponseBody。如果非要返回原始InputStream必须在 Javadoc 里标注调用方必须负责关闭同时在代码审查时重点盯这一类方法。这个规矩看着不过是一句话但实际执行下来文件服务相关的线上事故至少少了一半。另一个常见错误是异常处理太粗糙。MinIO 的异常体系里有ErrorResponseException、InsufficientDataException、InternalException等。不要一律 catchException然后吞掉至少区分一下错误类型文件不存在时应返回 404。bucket 不存在时应返回 500 并告警。网络异常时应该考虑重试还是快速失败。一个可复用的模式是写一个全局异常处理器把不同错误映射到合理的 HTTP 状态码这样前端拿到的错误信息才准确联调效率也能提上来。7. 还能怎么扩展到这里一个基本的 Spring Boot 3.5.8 整合 MinIO 8.5.9 的文件服务已经能跑了。但很多项目不会止步于简单的上传下载我再分享几个常见的扩展方向可以根据团队业务按需接入。一是结合消息队列做异步文件处理。文件上传到 MinIO 后向消息队列发送一个包含 objectName 的事件消费者负责生成缩略图、执行病毒扫描、解析文件内容、同步到其他存储等。这样上传接口响应速度更快用户不需要等后续处理链路全部完成。二是给对象名加业务前缀或目录结构。对象存储虽然叫对象但通过/分隔符可以把 key 组织成类似目录的层级。比如用户头像可以放avatar/{userId}/{timestamp}.jpg订单文件可以放order/{orderNo}/{fileId}.pdf。这不仅方便在控制台里按前缀检索也方便后续做生命周期管理比如定期归档前缀为log/的旧对象。三是结合定时任务做冷数据生命周期管理。MinIO 桶策略可以配置过期删除规则比如日志类文件保留 30 天自动清理。如果配置了多个 bucket 或使用了多版本管理建议在控制台上实际检验一下策略行为避免误删生产数据。四是多租户隔离方案。为每个租户分配独立 bucket 或同 bucket 不同前缀两种模式各有优劣。独立 bucket 隔离更彻底但 bucket 数量多的时候管理成本高同 bucket 不同前缀则适合对象数量可控、需要跨租户聚合统计的场景。我一般建议默认走前缀隔离等确实出现安全审计等硬性需求时再切换独立 bucket。五是监控与告警。MinIO 服务端本身暴露了 Prometheus 指标可以把/minio/v2/metrics/cluster接入 Grafana。客户端这边建议给上传下载方法做一个简单的耗时统计和错误计数指标打到应用监控系统中后续在容量评估时很有参考价值。不要等用户反馈传大文件很慢才去调日志。8. 最后还是想叮嘱几点这套整合方案不属于那种高不可攀的架构设计但它组合起来后涉及的细节确实多。配置项、依赖版本、异常处理、流关闭、超时设置任何一环没做好都可能在前端表现成文件传不上去文件下载失败之类让人头疼的问题。我在实际项目中踩过几次坑之后比较深的体会是先跑通最小闭环再做封装扩展。按照第 2 节到第 5 节的顺序走一遍把所有细节都跑顺再考虑打磨架构。别一上来就设计五个抽象层和六个扩展接口对于大多数内部系统来说上面这套代码量已经足够清晰可靠了。最后送上一个实用小技巧上传成功后建议把 objectName 的生成逻辑留一个可注入的接口而不是把 UUID 生成规则写死在 Service 里。这样后续如果产品要求文件名保持原始可读性、或者要求按日期归档只需要替换策略实现不需要动 Controller 和 SDK 调用逻辑。至于推荐做法能用简单方案就绝不引入复杂框架这一直是我做技术选型的底线。
