首页 > 软件编程 > java > SpringBoot对接阿里云OSS

SpringBoot对接阿里云OSS的详细步骤和流程

2025-08-04 09:42:40 作者：奇妙智能

阿里云对象存储服务（Object Storage Service,简称OSS）是一种海量、安全、低成本、高可靠的云存储服务,它适合存储任意类型的文件,适用于海量数据存储、图片/视频存储、静态网站托管等场景,本文给大家介绍了SpringBoot对接阿里云OSS的详细步骤和流程

以下是 Spring Boot 对接阿里云 OSS 的详细步骤和流程，结合官方网页和最佳实践整理而成：

一、准备工作

注册阿里云账号

访问阿里云官网完成注册和实名认证。

开通 OSS 服务

登录阿里云控制台 → 进入 OSS 服务 → 开通对象存储 OSS。

创建 Bucket

进入 OSS 控制台 → 点击「创建 Bucket」→ 填写名称（如 my-bucket）、地域（如华北2北京）→ 存储类型选择「标准存储」→ 权限选择「私有」。

获取 AccessKey

进入「AccessKey 管理」→ 创建 RAM 子用户（推荐）→ 保存 AccessKey ID 和 AccessKey Secret。

二、Spring Boot 项目配置

1. 添加依赖

在 pom.xml 中添加 OSS SDK 和 Web 依赖：

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.17.0</version> <!-- 使用最新稳定版本 -->
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

注意：若使用 Java 11+，需添加 JAXB 依赖：

<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>3.0.2</version>
</dependency>

2. 配置 OSS 参数

在 application.yml 中配置：

aliyun:
  oss:
    endpoint: oss-cn-beijing.aliyuncs.com  # Bucket 所在地域的 Endpoint
    access-key-id: your-access-key-id
    access-key-secret: your-access-key-secret
    bucket-name: your-bucket-name
    max-file-size: 10MB  # 最大文件限制（可选）
    allowed-extensions: jpg,jpeg,png,pdf  # 允许的文件类型（可选）

3. 创建配置类

通过 @ConfigurationProperties 读取配置并初始化 OSSClient：

@Configuration
@ConfigurationProperties(prefix = "aliyun.oss")
@Data
public class OssConfig {
    private String endpoint;
    private String accessKeyId;
    private String accessKeySecret;
    private String bucketName;
}

@Component
public class OssClientFactory {
    @Autowired
    private OssConfig ossConfig;

    private OSS ossClient;

    @PostConstruct
    public void init() {
        ossClient = new OSSClientBuilder().build(
            ossConfig.getEndpoint(),
            ossConfig.getAccessKeyId(),
            ossConfig.getAccessKeySecret()
        );
    }

    @PreDestroy
    public void shutdown() {
        if (ossClient != null) {
            ossClient.shutdown();
        }
    }
}

三、实现文件上传功能

1. 文件上传服务类

@Service
@RequiredArgsConstructor
public class OssService {
    private final OssConfig ossConfig;
    private final OssClientFactory ossClientFactory;

    public String uploadFile(MultipartFile file) {
        // 校验文件
        validateFile(file);

        // 生成唯一文件名（避免重复）
        String fileName = UUID.randomUUID().toString() + "_" + file.getOriginalFilename();

        try (InputStream inputStream = file.getInputStream()) {
            // 上传到 OSS
            ossClientFactory.getOssClient().putObject(
                ossConfig.getBucketName(),
                fileName,
                inputStream
            );
            // 生成访问 URL
            return generateAccessUrl(fileName);
        } catch (IOException e) {
            throw new RuntimeException("文件上传失败", e);
        }
    }

    private String generateAccessUrl(String fileName) {
        Date expiration = new Date(System.currentTimeMillis() + 3600 * 1000); // URL 有效期 1 小时
        return ossClientFactory.getOssClient().generatePresignedUrl(
            ossConfig.getBucketName(),
            fileName,
            expiration
        ).toString();
    }

    private void validateFile(MultipartFile file) {
        // 校验文件大小
        if (file.getSize() > parseSize(ossConfig.getMaxFileSize())) {
            throw new RuntimeException("文件大小超过限制");
        }
        // 校验文件类型
        String extension = FilenameUtils.getExtension(file.getOriginalFilename()).toLowerCase();
        if (!Arrays.asList(ossConfig.getAllowedExtensions().split(",")).contains(extension)) {
            throw new RuntimeException("不支持的文件类型");
        }
    }

    private long parseSize(String size) {
        // 解析如 "10MB" 为字节单位
        // 实现略...
    }
}

2. 控制器层

@RestController
@RequestMapping("/api/oss")
@RequiredArgsConstructor
public class OssController {
    private final OssService ossService;

    @PostMapping("/upload")
    public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file) {
        String url = ossService.uploadFile(file);
        return ResponseEntity.ok(url);
    }
}

四、测试与部署

本地测试

使用 Postman 发送 POST 请求到 /api/oss/upload，选择文件上传。
返回的 URL 即为 OSS 中文件的访问地址。

部署注意事项

安全建议：避免硬编码 AccessKey，推荐使用 RAM 子用户和 STS 临时凭证。
性能优化：大文件建议使用分片上传（MultipartUpload）。
存储类型：根据访问频率选择标准存储、低频存储或归档存储。

五、扩展功能

文件下载

public void downloadFile(String fileName, String localPath) {
    ossClientFactory.getOssClient().getObject(
        new GetObjectRequest(ossConfig.getBucketName(), fileName),
        new File(localPath)
    );
}

文件删除

public void deleteFile(String fileName) {
    ossClientFactory.getOssClient().deleteObject(
        ossConfig.getBucketName(),
        fileName
    );
}

图片处理

// 添加水印
GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(bucketName, fileName);
request.addResponseHeader("x-oss-process", "image/watermark,image_aHR0cDovL3Npb2FsQ0hJTmV3UzIwMjMxMDA1,size_20,text_QDUxQ1RPQ0hJTmV3UzIwMjMxMDA1001");
URL url = ossClient.generatePresignedUrl(request);

六、常见问题

AccessKey 权限不足

检查 RAM 子用户是否已授权 OSS 的 oss:PutObject 等权限。

文件上传失败

检查 Bucket 是否存在、网络是否连通、文件大小是否超出限制。

URL 无法访问

确认 Bucket 的读写权限是否为「私有」时需使用签名 URL。

通过以上步骤，即可实现 Spring Boot 与阿里云 OSS 的完整对接。如需进一步优化，可参考阿里云 OSS 官方网页。

以上就是SpringBoot对接阿里云OSS的详细步骤和流程的详细内容，更多关于SpringBoot对接阿里云OSS的资料请关注脚本之家其它相关文章！