阿里云OSS文件上传实现笔记

1. 概述

本文档详细介绍了在Spring Boot项目中集成阿里云对象存储服务(OSS)实现文件上传功能的完整实现。阿里云OSS提供了安全、稳定、高可用的云存储服务，适合存储各类文件，如图片、音视频等。

1.1 依赖

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.17.4</version>
</dependency>
<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.1</version>
</dependency>
<dependency>
    <groupId>javax.activation</groupId>
    <artifactId>activation</artifactId>
    <version>1.1.1</version>
</dependency>
<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>2.3.3</version>
</dependency>

2. 核心组件

2.1 配置属性类 (AliOssProperties.java)

package com.yixueji.properties;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * 阿里云OSS配置属性类
 * 通过@ConfigurationProperties注解绑定application.yml中的配置
 */
@Component
@ConfigurationProperties(prefix = "yixueji.alioss")
@Data
public class AliOssProperties {
    // OSS访问域名
    private String endpoint;
    // 访问身份ID
    private String accessKeyId;
    // 访问密钥
    private String accessKeySecret;
    // 存储空间名称
    private String bucketName;
}

2.2 OSS工具类 (AliOssUtil.java)

package com.yixueji.utils;

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import java.io.ByteArrayInputStream;

/**
 * 阿里云OSS工具类
 * 提供文件上传功能
 */
@Data
@AllArgsConstructor
@Slf4j
public class AliOssUtil {
    // OSS访问域名
    private String endpoint;
    // 访问身份ID
    private String accessKeyId;
    // 访问密钥
    private String accessKeySecret;
    // 存储空间名称
    private String bucketName;

    /**
     * 文件上传方法
     *
     * @param bytes 文件字节数组
     * @param objectName 对象名称，即文件在OSS中的存储路径
     * @return 文件访问URL
     */
    public String upload(byte[] bytes, String objectName) {
        // 创建OSSClient实例
        OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

        try {
            // 上传文件到OSS
            ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(bytes));
        } catch (OSSException oe) {
            // 处理OSS服务端异常
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            // 处理客户端异常
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            // 关闭OSSClient
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }

        // 构建文件访问路径: https://BucketName.Endpoint/ObjectName
        StringBuilder stringBuilder = new StringBuilder("https://");
        stringBuilder
                .append(bucketName)
                .append(".")
                .append(endpoint)
                .append("/")
                .append(objectName);

        log.info("文件上传到:{}", stringBuilder.toString());
        
        return stringBuilder.toString();
    }
}

2.3 配置类 (OssConfiguration.java)

package com.yixueji.config;

import com.yixueji.properties.AliOssProperties;
import com.yixueji.utils.AliOssUtil;
import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * 配置类，用于创建AliOssUtil对象
 */
@Configuration
@Slf4j
public class OssConfiguration {

    /**
     * 创建AliOssUtil对象并注入Spring容器
     * 
     * @param aliOssProperties OSS配置属性
     * @return AliOssUtil实例
     */
    @Bean
    @ConditionalOnMissingBean
    public AliOssUtil aliOssUtil(AliOssProperties aliOssProperties){
        log.info("开始创建阿里云文件上传工具类对象：{}", aliOssProperties);
        return new AliOssUtil(aliOssProperties.getEndpoint(),
                aliOssProperties.getAccessKeyId(),
                aliOssProperties.getAccessKeySecret(),
                aliOssProperties.getBucketName());
    }
}

2.4 控制器 (CommonController.java)

package com.yixueji.controller.user;

import com.yixueji.constant.MessageConstant;
import com.yixueji.result.Result;
import com.yixueji.utils.AliOssUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
import java.io.IOException;
import java.util.UUID;

/**
 * 通用接口
 */
@RestController
@RequestMapping("/common")
@Api(tags = "通用接口")
@Slf4j
public class CommonController {

    @Autowired
    private AliOssUtil aliOssUtil;

    /**
     * 文件上传接口
     * 
     * @param file 上传的文件
     * @return 文件访问URL
     */
    @PostMapping("/upload")
    @ApiOperation("文件上传")
    public Result<String> upload(@RequestParam("image") MultipartFile file){
        log.info("文件上传：{}", file);

        try {
            // 获取原始文件名
            String originalFilename = file.getOriginalFilename();
            
            // 安全处理文件后缀
            String extension = "";
            if (originalFilename != null) {
                int dotIndex = originalFilename.lastIndexOf(".");
                if (dotIndex > 0) {  // 确保找到了点号且不是第一个字符
                    extension = originalFilename.substring(dotIndex);
                }
            }
            
            // 构造新文件名（UUID + 原始后缀）
            String objectName = UUID.randomUUID().toString() + extension;

            // 上传文件并获取访问路径
            String filePath = aliOssUtil.upload(file.getBytes(), objectName);
            return Result.success(filePath);
        } catch (IOException e) {
            log.error("文件上传失败：{}", e);
        }

        return Result.error(MessageConstant.UPLOAD_FAILED);
    }
}

3. 配置文件

3.1 application.yml

yixueji:
  alioss:
    endpoint: ${yixueji.alioss.endpoint}
    access-key-id: ${yixueji.alioss.access-key-id}
    access-key-secret: ${yixueji.alioss.access-key-secret}
    bucket-name: ${yixueji.alioss.bucket-name}

3.2 application-dev.yml (开发环境配置)

yixueji:
  alioss:
    endpoint: oss-cn-beijing.aliyuncs.com
    access-key-id: 
    access-key-secret: 
    bucket-name: 

4. 工作流程

1. 配置加载：

   • 应用启动时，Spring Boot读取application.yml和对应环境的配置文件
   • AliOssProperties通过@ConfigurationProperties自动绑定配置项

2. Bean创建：

   • OssConfiguration创建AliOssUtil实例并注入Spring容器
   • AliOssUtil被初始化，包含所有OSS连接参数

3. 文件上传流程：

   • 客户端发送文件到/common/upload接口
   • CommonController接收文件并处理文件名（生成UUID防止重名）
   • 调用AliOssUtil.upload()方法上传文件到阿里云OSS
   • 返回文件的访问URL给客户端

5. 关键技术点

1. 配置外部化：

   • 使用@ConfigurationProperties实现配置外部化
   • 不同环境使用不同配置文件，便于环境切换

2. 依赖注入：

   • 使用@Bean和@Autowired实现依赖注入
   • @ConditionalOnMissingBean确保只创建一个实例

3. 文件处理：

   • 使用UUID生成唯一文件名，避免文件覆盖
   • 安全处理文件后缀，防止恶意文件上传

4. 异常处理：

   • 捕获并记录上传过程中的异常
   • 返回统一的错误响应

5. 日志记录：

   • 使用@Slf4j记录关键操作日志
   • 记录文件上传成功和失败信息

6. 使用示例

6.1 前端上传文件示例

<form id="uploadForm" enctype="multipart/form-data">
    <input type="file" name="image" id="fileInput">
    <button type="button" onclick="uploadFile()">上传</button>
</form>

<script>
function uploadFile() {
    const formData = new FormData();
    const fileInput = document.getElementById('fileInput');
    formData.append('image', fileInput.files[0]);
    
    fetch('/common/upload', {
        method: 'POST',
        body: formData
    })
    .then(response => response.json())
    .then(result => {
        if(result.code === 1) {
            console.log('上传成功，文件URL:', result.data);
            // 处理上传成功后的逻辑
        } else {
            console.error('上传失败:', result.msg);
        }
    })
    .catch(error => {
        console.error('上传出错:', error);
    });
}
</script>

6.2 后端调用示例

@RestController
@RequestMapping("/user")
public class UserController {

    @Autowired
    private AliOssUtil aliOssUtil;
    
    @PostMapping("/updateAvatar")
    public Result<String> updateAvatar(@RequestParam("avatar") MultipartFile file) {
        try {
            // 获取文件后缀
            String originalFilename = file.getOriginalFilename();
            String extension = originalFilename.substring(originalFilename.lastIndexOf("."));
            
            // 构造文件名
            String fileName = "avatars/" + UUID.randomUUID().toString() + extension;
            
            // 上传到OSS
            String avatarUrl = aliOssUtil.upload(file.getBytes(), fileName);
            
            // 更新用户头像URL
            // userService.updateAvatar(userId, avatarUrl);
            
            return Result.success(avatarUrl);
        } catch (IOException e) {
            return Result.error("头像上传失败");
        }
    }
}

7. 安全注意事项

1. AccessKey安全：

   • 不要在代码中硬编码AccessKey
   • 使用配置文件和环境变量存储敏感信息
   • 生产环境考虑使用阿里云RAM角色或STS临时凭证

2. 文件类型限制：

   • 实际应用中应限制允许上传的文件类型
   • 验证文件内容而不仅仅是扩展名

3. 文件大小限制：

   • 在Spring配置中设置最大文件大小
   • 在控制器中验证文件大小

4. 防盗链设置：

   • 在OSS控制台设置防盗链规则
   • 限制特定域名访问OSS资源

8. 性能优化建议

1. 异步上传：

   • 考虑使用异步方式处理大文件上传
   • 使用Spring的@Async或线程池

2. 分片上传：

   • 对于大文件，使用OSS的分片上传功能
   • 实现断点续传

3. 图片处理：

   • 使用OSS的图片处理功能进行压缩、裁剪等
   • 通过URL参数实现动态图片处理

4. CDN加速：

   • 结合阿里云CDN加速文件访问
   • 配置适当的缓存策略

9. 总结

本文档详细介绍了在Spring Boot项目中集成阿里云OSS实现文件上传功能的完整实现。通过合理的架构设计和配置管理，实现了灵活、安全、高效的文件上传功能。该实现适用于各类需要文件存储的Web应用，如社交媒体、电商平台、内容管理系统等。