SpringBoot整合阿里云OSS全流程指南

一、环境准备阶段

1.1 阿里云账号配置

graph TD
    A[注册阿里云账号] --> B[开通OSS服务]
    B --> C[创建AccessKey]
    C --> D[创建Bucket]
    style D fill:#bbf,stroke:#333

​关键配置项​：

配置项	示例值	说明
Endpoint	oss-cn-hangzhou.aliyuncs.com	根据地域选择
Bucket名称	myapp-prod	全局唯一
AccessKey ID	LTAI5t​**​​**​	子账号更安全
AccessKey Secret	KZo67b​**​​**​	定期轮换

1.2 依赖引入

<!-- pom.xml 添加 -->
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.15.1</version>
</dependency>

二、基础配置实现

2.1 配置文件

# application.yml
aliyun:
  oss:
    endpoint: https://oss-cn-hangzhou.aliyuncs.com
    access-key-id: LTAI5t******
    access-key-secret: KZo67b******
    bucket-name: myapp-prod
    max-connections: 50  # 连接池配置

2.2 配置类封装

@Configuration
public class OssConfig {
    
    @Value("${aliyun.oss.endpoint}")
    private String endpoint;
    
    @Value("${aliyun.oss.access-key-id}")
    private String accessKeyId;
    
    @Value("${aliyun.oss.access-key-secret}")
    private String accessKeySecret;
    
    @Bean
    public OSS ossClient() {
        return new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    }
}

三、核心功能实现

3.1 文件上传服务

@Service
public class OssService {
    
    @Autowired
    private OSS ossClient;
    
    @Value("${aliyun.oss.bucket-name}")
    private String bucketName;
    
    public String upload(InputStream inputStream, String fileName) {
        // 生成带时间戳的唯一文件名
        String objectName = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd")) 
                          + "/" + UUID.randomUUID() + getFileExtension(fileName);
        
        ossClient.putObject(bucketName, objectName, inputStream);
        return generateUrl(objectName);
    }
    
    private String getFileExtension(String fileName) {
        return fileName.substring(fileName.lastIndexOf("."));
    }
    
    private String generateUrl(String objectName) {
        // 生成有效期1小时的URL
        Date expiration = new Date(System.currentTimeMillis() + 3600 * 1000);
        return ossClient.generatePresignedUrl(bucketName, objectName, expiration).toString();
    }
}

3.2 文件下载服务

public byte[] download(String objectName) {
    OSSObject ossObject = ossClient.getObject(bucketName, objectName);
    try (InputStream inputStream = ossObject.getObjectContent()) {
        return IOUtils.toByteArray(inputStream);
    } catch (IOException e) {
        throw new RuntimeException("文件下载失败", e);
    }
}

四、高级功能扩展

4.1 断点续传实现

public String resumableUpload(File file, String fileName) {
    // 创建上传请求
    UploadFileRequest request = new UploadFileRequest(bucketName, fileName);
    request.setUploadFile(file.getPath());
    request.setTaskNum(5); // 分片并发数
    request.setPartSize(1024 * 1024); // 分片大小1MB
    
    // 设置回调
    request.setCallback(new Callback() {
        public void onSuccess() {
            log.info("上传成功");
        }
        public void onFailure() {
            log.error("上传失败");
        }
    });
    
    UploadFileResult result = ossClient.uploadFile(request);
    return result.getResponse().getUri();
}

4.2 图片处理

public String processImage(String objectName) {
    // 图片缩放+水印
    String style = "image/resize,m_fill,w_400,h_300/watermark,text_SGVsbG8gV29ybGQ";
    String processedUrl = ossClient.generatePresignedUrl(
        bucketName, 
        objectName, 
        new Date(System.currentTimeMillis() + 3600 * 1000),
        HttpMethod.GET,
        new ResponseHeaderOverrides(),
        new GenericRequest().setProcess(style)
    ).toString();
    
    return processedUrl;
}

五、安全防护方案

5.1 临时访问令牌

public STS assumeRole(String roleArn) {
    DefaultProfile profile = DefaultProfile.getProfile("cn-hangzhou", accessKeyId, accessKeySecret);
    IAcsClient client = new DefaultAcsClient(profile);
    
    AssumeRoleRequest request = new AssumeRoleRequest();
    request.setRoleArn(roleArn);
    request.setRoleSessionName("oss-upload-session");
    request.setDurationSeconds(900L); // 15分钟有效期
    
    try {
        AssumeRoleResponse response = client.getAcsResponse(request);
        return new STS(
            response.getCredentials().getAccessKeyId(),
            response.getCredentials().getAccessKeySecret(),
            response.getCredentials().getSecurityToken()
        );
    } catch (ClientException e) {
        throw new RuntimeException("STS获取失败", e);
    }
}

5.2 权限策略配置

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:PutObject",
        "oss:GetObject"
      ],
      "Resource": [
        "acs:oss:*:*:myapp-prod/temp/*"
      ],
      "Condition": {
        "IpAddress": {
          "acs:SourceIp": ["192.168.1.0/24"]
        }
      }
    }
  ]
}

六、性能优化策略

6.1 连接池配置

@Bean
public OSS ossClient() {
    ClientConfiguration config = new ClientConfiguration();
    config.setMaxConnections(100);          // 最大连接数
    config.setConnectionTimeout(5000);      // 连接超时5秒
    config.setSocketTimeout(30000);         // 读写超时30秒
    
    return new OSSClientBuilder()
        .build(endpoint, accessKeyId, accessKeySecret, config);
}

6.2 批量操作示例

public void batchDelete(List<String> objectNames) {
    DeleteObjectsRequest request = new DeleteObjectsRequest(bucketName);
    request.setKeys(objectNames);
    request.setQuiet(true); // 静默模式不返回删除结果
    
    ossClient.deleteObjects(request);
}

七、异常处理机制

7.1 自定义异常类

public class OssOperationException extends RuntimeException {
    private String requestId;
    private String errorCode;
    
    public OssOperationException(OSSException ex) {
        super(ex.getMessage());
        this.requestId = ex.getRequestId();
        this.errorCode = ex.getErrorCode();
    }
}

7.2 全局异常处理器

@ControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(OSSException.class)
    public ResponseEntity<ErrorResponse> handleOssException(OSSException ex) {
        ErrorResponse error = new ErrorResponse(
            "OSS_OPERATION_FAILED",
            ex.getMessage(),
            ex.getRequestId()
        );
        return ResponseEntity.status(500).body(error);
    }
}

八、监控与日志

8.1 操作日志记录

@Aspect
@Component
public class OssLogAspect {
    
    @Autowired
    private LogService logService;
    
    @Around("execution(* com.example.service.OssService.*(..))")
    public Object logOssOperation(ProceedingJoinPoint joinPoint) throws Throwable {
        String method = joinPoint.getSignature().getName();
        long start = System.currentTimeMillis();
        
        try {
            Object result = joinPoint.proceed();
            long duration = System.currentTimeMillis() - start;
            
            logService.recordOssLog(
                method, 
                "SUCCESS", 
                duration,
                joinPoint.getArgs()
            );
            return result;
        } catch (Exception e) {
            logService.recordOssLog(
                method, 
                "FAILED: " + e.getMessage(), 
                System.currentTimeMillis() - start,
                joinPoint.getArgs()
            );
            throw e;
        }
    }
}

8.2 监控指标埋点

@Bean
public OSS ossClient(MeterRegistry registry) {
    OSS client = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 监控上传下载耗时
    registry.gauge("oss.operation.time", client, c -> {
        // 实现实际监控逻辑
        return getOperationTime();
    });
    
    return client;
}

九、测试方案

9.1 单元测试模拟

@SpringBootTest
public class OssServiceTest {
    
    @MockBean
    private OSS ossClient;
    
    @Autowired
    private OssService ossService;
    
    @Test
    public void testUpload() throws Exception {
        // 模拟OSS返回
        when(ossClient.putObject(any(), any(), any()))
            .thenReturn(new PutObjectResult());
            
        String url = ossService.upload(
            new ByteArrayInputStream("test".getBytes()),
            "test.txt"
        );
        
        assertNotNull(url);
    }
}

9.2 集成测试要点

graph LR
    A[测试用例] --> B[上传测试]
    A --> C[下载测试]
    A --> D[删除测试]
    B --> E[验证返回URL]
    C --> F[验证文件内容]
    D --> G[验证删除结果]

十、部署最佳实践

10.1 多环境配置

# application-prod.yml
aliyun:
  oss:
    bucket-name: myapp-prod
    endpoint: https://oss-cn-hangzhou-internal.aliyuncs.com  # 内网地址

# application-dev.yml  
aliyun:
  oss:
    bucket-name: myapp-dev
    endpoint: https://oss-cn-hangzhou.aliyuncs.com

10.2 灰度发布方案

@Primary
@Bean
@Profile("!gray")
public OSS productionOssClient() {
    return new OSSClientBuilder().build(prodEndpoint, prodKey, prodSecret);
}

@Bean
@Profile("gray")
public OSS grayOssClient() {
    return new OSSClientBuilder().build(grayEndpoint, grayKey, graySecret);
}

关键问题解决方案

跨域访问配置

public void setCorsRules() {
    ArrayList<String> allowMethods = new ArrayList<>();
    allowMethods.add("GET");
    allowMethods.add("POST");
    
    ArrayList<String> allowOrigin = new ArrayList<>();
    allowOrigin.add("https://www.example.com");
    
    CORSRule rule = new CORSRule();
    rule.setAllowedMethods(allowMethods);
    rule.setAllowedOrigins(allowOrigin);
    rule.setMaxAgeSeconds(3600L);
    
    SetBucketCORSRequest request = new SetBucketCORSRequest(bucketName);
    request.setCorsRules(Collections.singletonList(rule));
    
    ossClient.setBucketCORS(request);
}

大文件分片上传

public String multipartUpload(InputStream inputStream, long fileSize, String fileName) {
    InitiateMultipartUploadRequest initRequest = new InitiateMultipartUploadRequest(bucketName, fileName);
    InitiateMultipartUploadResult initResult = ossClient.initiateMultipartUpload(initRequest);
    
    // 每片5MB
    int partSize = 5 * 1024 * 1024;
    int partCount = (int) (fileSize / partSize) + 1;
    
    List<PartETag> partETags = new ArrayList<>();
    for (int i = 0; i < partCount; i++) {
        long startPos = i * partSize;
        long curPartSize = Math.min(partSize, fileSize - startPos);
        
        UploadPartRequest uploadRequest = new UploadPartRequest();
        uploadRequest.setBucketName(bucketName);
        uploadRequest.setKey(fileName);
        uploadRequest.setUploadId(initResult.getUploadId());
        uploadRequest.setInputStream(inputStream);
        uploadRequest.setPartSize(curPartSize);
        uploadRequest.setPartNumber(i + 1);
        
        UploadPartResult uploadResult = ossClient.uploadPart(uploadRequest);
        partETags.add(uploadResult.getPartETag());
    }
    
    CompleteMultipartUploadRequest completeRequest = new CompleteMultipartUploadRequest(
        bucketName, fileName, initResult.getUploadId(), partETags);
    ossClient.completeMultipartUpload(completeRequest);
    
    return generateUrl(fileName);
}

通过本指南，您已掌握SpringBoot集成阿里云OSS的完整技术方案。关键实施建议：

1. ​生产环境务必使用STS临时凭证
2. ​大文件处理优先采用分片上传
3. ​敏感操作做好日志审计
4. ​性能敏感场景调整连接池参数
5. ​跨域访问严格限制来源域名

附：架构图

graph LR
    Client -->|HTTP| App[SpringBoot]
    App -->|SDK| OSS[阿里云OSS]
    OSS -->|回调| App
    App -->|日志| ELK
    App -->|监控| Prometheus

遵循此方案，可实现日均百万级文件的安全高效存取，同时满足企业级安全合规要求。