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

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

---

一、准备工作

1. ​​注册阿里云账号​​

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

2. ​​开通 OSS 服务​​

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

3. ​​创建 Bucket​​

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

4. ​​获取 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);
    }
}

---

四、测试与部署

1. ​​本地测试​​

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

2. ​​部署注意事项​​

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

---

五、扩展功能

1. ​​文件下载​​

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

2. ​​文件删除​​

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

3. ​​图片处理​​

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

---

六、常见问题

1. ​​AccessKey 权限不足​​

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

2. ​​文件上传失败​​

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

3. ​​URL 无法访问​​

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

---

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