MinIO Java 对接试用从连接、上传到下载的完整示例适用场景Spring Boot 服务接入自建 MinIO用于文件上传、下载、预览和删除。本文示例不包含真实地址、账号或密钥生产环境请使用环境变量或密钥管理服务。一、先明确 MinIO 的对象模型MinIO 兼容 S3核心对象是Endpoint服务地址、Bucket桶、Object对象键和凭证。对象键不是本地文件路径例如2026/08/report.pdf只是一个字符串前缀。二、准备试用环境MinIO Endpoint: http://127.0.0.1:9000 控制台地址: http://127.0.0.1:9001 Bucket: demo-files Access Key: 通过环境变量注入 Secret Key: 通过环境变量注入首次试用建议创建独立测试桶和最小权限账号不要直接使用管理员账号连接业务系统。三、引入 Java SDK在 Maven 中加入依赖版本由项目统一管理不要在多个模块写不同版本。dependencygroupIdio.minio/groupIdartifactIdminio/artifactIdversion${minio.version}/version/dependency四、Spring Boot 配置minio:endpoint:${MINIO_ENDPOINT:http://127.0.0.1:9000}access-key:${MINIO_ACCESS_KEY:}secret-key:${MINIO_SECRET_KEY:}bucket:${MINIO_BUCKET:demo-files}不要把secret-key提交到 Git。开发机可以用 PowerShell 临时变量$env:MINIO_ENDPOINThttp://127.0.0.1:9000$env:MINIO_ACCESS_KEY测试账号$env:MINIO_SECRET_KEY测试密钥$env:MINIO_BUCKETdemo-files五、创建 MinioClient BeanConfigurationpublicclassMinioConfig{BeanMinioClientminioClient(Value(${minio.endpoint})Stringendpoint,Value(${minio.access-key})StringaccessKey,Value(${minio.secret-key})StringsecretKey){returnMinioClient.builder().endpoint(endpoint).credentials(accessKey,secretKey).build();}}六、封装常用操作ServicepublicclassObjectStorageService{privatefinalMinioClientclient;privatefinalStringbucket;publicObjectStorageService(MinioClientclient,Value(${minio.bucket})Stringbucket){this.clientclient;this.bucketbucket;}publicvoidensureBucket()throwsException{booleanexistsclient.bucketExists(BucketExistsArgs.builder().bucket(bucket).build());if(!exists){client.makeBucket(MakeBucketArgs.builder().bucket(bucket).build());}}publicvoidupload(StringobjectName,InputStreaminput,longsize,StringcontentType)throwsException{client.putObject(PutObjectArgs.builder().bucket(bucket).object(objectName).stream(input,size,-1).contentType(contentType).build());}publicInputStreamdownload(StringobjectName)throwsException{returnclient.getObject(GetObjectArgs.builder().bucket(bucket).object(objectName).build());}publicStringpresignedGetUrl(StringobjectName,intminutes)throwsException{returnclient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder().method(Method.GET).bucket(bucket).object(objectName).expiry(minutes,TimeUnit.MINUTES).build());}publicvoiddelete(StringobjectName)throwsException{client.removeObject(RemoveObjectArgs.builder().bucket(bucket).object(objectName).build());}}InputStream用完必须关闭大文件不要先读入byte[]。size已知时传实际长度未知时传-1并设置合理的分片大小。七、提供一个联调接口RestControllerRequestMapping(/api/files)publicclassFileController{privatefinalObjectStorageServicestorage;PostMapping(consumesMediaType.MULTIPART_FORM_DATA_VALUE)publicMapString,Stringupload(RequestPartMultipartFilefile)throwsException{StringobjectNameUUID.randomUUID()-StringUtils.cleanPath(file.getOriginalFilename());storage.upload(objectName,file.getInputStream(),file.getSize(),Optional.ofNullable(file.getContentType()).orElse(MediaType.APPLICATION_OCTET_STREAM_VALUE));returnMap.of(objectName,objectName);}}测试curl-Ffile./demo.txthttp://localhost:8080/api/files八、试用验收清单启动服务后能自动创建测试桶或检测到已有桶。上传后在 MinIO Console 中能看到对象大小和 Content-Type 正确。下载内容与原文件校验和一致。预签名 URL 在有效期内可访问过期后失效。删除对象后再次下载返回不存在。错误日志不打印 Secret Key、完整预签名 URL 或用户隐私。九、生产化注意事项桶默认保持私有下载使用后端鉴权后生成短时预签名 URL。对象键使用业务 ID 加随机值避免用户原文件名造成覆盖和路径穿越。上传前校验扩展名、MIME、大小和病毒扫描结果。大文件使用分片上传失败时记录 uploadId 并提供清理策略。需要审计时保存对象键、业务单号、上传人、大小、哈希和时间不保存密钥。跨服务器迁移前先确认版本控制、对象锁、生命周期和元数据是否需要保留。本文示例适合首次验证 SDK 与 MinIO 连通性。真正上线前应补充统一异常、权限模型、断点续传、限流和监控。
