你好我是fengxin_rou这是我的个人主页fengxin_rou的主页❄️欢迎查看我的专栏我的专栏《Java后端学习》、《JAVASE基础》、《JUC并发》、《redis》、《JVM虚拟机》、《MYSQL》、《黑马点评》、《rabbitmq》、《JavaWebAI的talis学习系统》、《苍穹外卖》目录前言一、预签名直传核心原理与优势1.1 传统上传 vs 预签名直传1.2 核心优势1.3 整体流程二、请求实体设计标准化上传参数字段说明三、OSS 存储服务核心工具类实现3.1 头像上传普通上传示例3.2 生成公开访问 URL3.3 生成预签名 PUT URL核心四、Controller 接口实现权限校验与业务封装4.1 权限校验关键点4.2 返回体结构五、前端直传执行流程前端请求示例结语前言在内容社区、自媒体平台等场景中图片、文件上传是高频需求。 传统后端中转上传会占用大量带宽与内存高并发下极易成为性能瓶颈。 本文基于 SpringBoot 阿里云 OSS实现预签名 URL 客户端直传方案彻底解放后端服务兼顾安全、高效与易用。一、预签名直传核心原理与优势预签名 URL是对象存储提供的临时授权机制。 后端用密钥生成带时效、带权限的签名 URL前端直接用此 URL 上传 / 下载文件无需透传密钥。1.1 传统上传 vs 预签名直传传统上传客户端→后端→OSS后端中转流量压力大、速度慢。预签名直传客户端请求签名→后端返回 URL→客户端直传 OSS→通知后端入库。1.2 核心优势服务无压力后端不处理文件流仅做授权与记录。上传速度快客户端直连 OSS带宽不受后端限制。安全可控URL 有时效、有路径、有权限防止越权与盗传。成本更低减少服务器出口带宽消耗。1.3 整体流程前端请求获取预签名上传 URL。后端校验权限、生成路径、返回带签名 URL 与访问 URL。前端直接 PUT 上传到 OSS。上传完成后通知后端保存文件 URL 到业务库。二、请求实体设计标准化上传参数统一请求体明确场景、文件标识、类型便于权限校验与路径生成。/** * 预签名直传请求实体 */ public record StoragePresignRequest( NotBlank String scene, // 上传场景文章内容/图片 NotBlank String postId, // 帖子ID字符串避免精度丢失 NotBlank String contentType,// 文件类型image/jpeg、video/mp4 String ext // 文件扩展名 ) {}字段说明scene区分业务场景便于权限控制与目录隔离。postId关联业务 ID用于校验归属、防止越权。contentType必须与前端上传时一致否则 OSS 验签失败。ext扩展名用于生成规范文件路径。三、OSS 存储服务核心工具类实现封装 OSS 基础操作包括普通上传、生成公开 URL、生成预签名 URL。3.1 头像上传普通上传示例适用于小文件、后端可承接的简单上传场景。/** * 头像上传到 OSS */ public String uploadAvatar(long userId, MultipartFile file) { // 1.校验 OSS 配置 ensureConfigured(); // 2.提取文件扩展名 String original file.getOriginalFilename(); String ext ; if (original ! null original.contains(.)) { ext original.substring(original.lastIndexOf(.)); } // 3.生成唯一文件路径 String objectKey props.getFolder() / userId - System.currentTimeMillis() ext; // 4.创建 OSS 客户端 OSS client new OSSClientBuilder().build( props.getEndpoint(), props.getAccessKeyId(), props.getAccessKeySecret() ); try { // 5.流式上传 PutObjectRequest request new PutObjectRequest( props.getBucket(), objectKey, file.getInputStream() ); client.putObject(request); } catch (IOException e) { throw new BusinessException(ErrorCode.BAD_REQUEST, 文件读取失败); } finally { client.shutdown(); } // 6.返回可访问 URL return publicUrl(objectKey); }3.2 生成公开访问 URL拼接 CDN 域名规范路径避免双斜杠问题。/** * 生成公开访问 URL */ private String publicUrl(String objectKey) { if (props.getPublicDomain() ! null !props.getPublicDomain().isBlank()) { return props.getPublicDomain().replaceAll(/$, ) / objectKey; } return https:// props.getBucket() . props.getEndpoint() / objectKey; }3.3 生成预签名 PUT URL核心生成前端可直接 PUT 上传的临时 URL必须指定 ContentType。/** * 生成预签名 PUT 上传 URL */ public String generatePresignedPutUrl( String objectKey, String contentType, int expiresInSeconds ) { ensureConfigured(); OSS client new OSSClientBuilder().build( props.getEndpoint(), props.getAccessKeyId(), props.getAccessKeySecret() ); try { // 设置过期时间 Date expiration new Date(System.currentTimeMillis() expiresInSeconds * 1000L); GeneratePresignedUrlRequest request new GeneratePresignedUrlRequest( props.getBucket(), objectKey, HttpMethod.PUT ); request.setExpiration(expiration); // 必须设置 ContentType否则前端上传会验签失败 if (contentType ! null !contentType.isBlank()) { request.setContentType(contentType); } URL url client.generatePresignedUrl(request); return url.toString(); } finally { client.shutdown(); } }四、Controller 接口实现权限校验与业务封装提供对外接口完成用户认证、权限校验、路径生成、签名返回。/** * 预签名直传接口 */ PostMapping(/presign) public StoragePresignResponse presign( Valid RequestBody StoragePresignRequest request, AuthenticationPrincipal Jwt jwt ) { // 1.获取当前登录用户ID long userId jwtService.extractUserId(jwt); // 2.postId 字符串转数字防止前端精度丢失 long postId; try { postId Long.parseLong(request.postId()); } catch (NumberFormatException e) { throw new BusinessException(ErrorCode.BAD_REQUEST, postId 格式非法); } // 3.校验帖子归属防止越权上传 KnowPost post knowPostMapper.findById(postId); if (post null || !userId.equals(post.getCreatorId())) { throw new BusinessException(ErrorCode.BAD_REQUEST, 无权限操作该草稿); } // 4.按场景生成文件存储路径 String scene request.scene(); String ext normalizeExt(request.ext(), request.contentType(), scene); String objectKey; if (knowpost_content.equals(scene)) { objectKey posts/ postId /content ext; } else if (knowpost_image.equals(scene)) { String date DateTimeFormatter.ofPattern(yyyyMMdd) .withZone(ZoneId.of(UTC)).format(Instant.now()); String rand UUID.randomUUID().toString().replace(-, ).substring(0, 8); objectKey posts/ postId /images/ date / rand ext; } else { throw new BusinessException(ErrorCode.BAD_REQUEST, 不支持的上传场景); } // 5.生成10分钟有效期的预签名 URL int expiresIn 600; String uploadUrl ossStorageService.generatePresignedPutUrl( objectKey, request.contentType(), expiresIn ); MapString, String headers Map.of(Content-Type, request.contentType()); // 6.返回上传URL、文件URL、请求头、过期时间 return new StoragePresignResponse(objectKey, uploadUrl, headers, expiresIn); }4.1 权限校验关键点必须校验postId 对应用户是否为当前登录用户。无校验会导致越权覆盖、恶意上传、数据污染。这是系统安全的核心防线。4.2 返回体结构{ objectKey: posts/123/images/20260524/xxxx.jpg, uploadUrl: https://xxx.oss-cn-beijing.aliyuncs.com/...?X-Oss-Signaturexxx, headers: { Content-Type: image/jpeg }, expireSeconds: 600 }五、前端直传执行流程调用/api/v1/storage/presign获取上传 URL。使用PUT方法携带指定 Content-Type 上传文件。上传成功后将 fileUrl 提交给后端业务接口保存。前端请求示例// 获取预签名 const { uploadUrl, headers } await api.post(/storage/presign, { scene: knowpost_image, postId: 123, contentType: image/jpeg, ext: jpg }); // 直传 OSS await axios.put(uploadUrl, file, { headers });结语本文完整实现 SpringBoot OSS预签名 URL 直传方案覆盖请求设计、服务封装、权限校验、接口开放全流程。 该方案大幅降低服务负载提升上传速度与系统吞吐量适合文章、图片、视频等大文件上传场景。实际使用建议预签名有效期控制在5–10 分钟。按业务场景做目录隔离。接入 CDN 加速文件访问。增加文件大小、类型、数量限流防护。