Java—阿里云对象存储服务OSS

ClancyLv

已于 2024-08-22 14:02:49 修改

阅读量345

点赞数 6

文章标签： java 阿里云数据库

于 2024-08-21 09:40:31 首次发布

本文链接：https://blog.csdn.net/ClancyLv/article/details/141379364

版权

简介

阿里云对象存储 OSS（Object Storage Service）是一款海量、安全、低成本、高可靠的云存储服务，提供最高可达 99.995 % 的服务可用性。多种存储类型供选择，全面优化存储成本。

背景

积累知识。

教程

使用阿里云的OSS服务需至阿里云官网开通OSS服务，并在AccessKey管理中创建AccessKey ID 和 AccessKey Secret（开发需使用的参数），接着创建Bucket并进入Bucket概览查看Endpoint地域节点（开发需使用的参数）
文档参考：

1、版本信息

Java 8
Maven 3.6.1
SpringBoot 2.2.2.RELEASE

2、pom依赖

<!--这个依赖适用于Java 8，如果使用的是Java 9及以上的版本，则需要添加JAXB相关依赖。参考文档：https://help.aliyun.com/zh/oss/developer-reference/java-installation?spm=a2c4g.11186623.0.0.74ff97f0ekdjKz-->
<!--阿里云OSS-->
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.17.4</version>
</dependency>
<!--代码简化工具-->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.24</version>
    <scope>provided</scope>
</dependency>

3、Yaml配置

aliyun:
  oss:
  	# 注意Endpoint（地域节点）这里需要加前缀https://
    endpoint: https://Endpoint（地域节点）
    accessKeyId: 创建的accessKeyId
    accessKeySecret: 创建的accessKeySecret
    bucketName: 需使用的存储空间

4、阿里云OSS属性类

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

/**
 * @Author ClancyLv
 * @Date 2024/8/20 10:01
 * @Description 属性类--阿里云OSS配置
 */
@Data
@Component
@ConfigurationProperties(prefix = "aliyun.oss")
public class AliyunOssProperties {
    /**
     * 地域节点
     */
    private String endpoint;

    /**
     * 访问密钥id
     */
    private String accessKeyId;

    /**
     * 访问密钥
     */
    private String accessKeySecret;

    /**
     * 桶名
     */
    private String bucketName;
}

5、阿里云OSS工具类

import com.aliyun.oss.*;
import com.aliyun.oss.model.*;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Configuration;

import java.io.*;
import java.util.ArrayList;
import java.util.Date;
import java.util.LinkedList;
import java.util.List;
import java.util.stream.Collectors;

/**
 * @Author ClancyLv
 * @Date 2024/8/20 9:57
 * @Description 工具类--阿里云对象存储服务OSS
 * 问题排查路径：https://help.aliyun.com/zh/oss/developer-reference/error-handling-1?spm=a2c4g.11186623.0.0.738d38e0zPG3h9
 */
@Slf4j
@Configuration
public class AliyunOssUtil {
    // 查询文件个数默认值
    private static final int DEFAULT_OBJECT_MAX_KEYS = 100;
    // 查询文件个数最大值
    private static final int MAX_RETURNED_KEYS_LIMIT = 1000;
    // 删除文件个数默认值
    public static final int DELETE_OBJECTS_ONETIME_LIMIT = 1000;

    // 阿里云对象存储客户端
    private final OSS ossClient;
    // 存储空间名称
    private final String bucketName;

    public AliyunOssUtil(AliyunOssProperties aliyunOssProperties) {
        // 创建OSSClient实例。
        this.ossClient = new OSSClientBuilder().build(aliyunOssProperties.getEndpoint(), aliyunOssProperties.getAccessKeyId(), aliyunOssProperties.getAccessKeySecret());
        this.bucketName = aliyunOssProperties.getBucketName();
        // 判断存储空间是否存在
        if (this.doesBucketExist(this.bucketName)) {
            log.info("存储空间[{}]已存在，无需创建", this.bucketName);
            return;
        }
        // 创建存储空间
        this.createBucket(this.bucketName);
    }

    /**
     * 创建存储空间
     * @param bucketName 存储空间名称
     * 存储空间Bucket命名规范：1)只能包括小写字母，数字和短横线（-）；2)必须以小写字母或者数字开头；3)长度必须在 3-63 字节之间。
     */
    public void createBucket(String bucketName) {
        try {
            // 创建CreateBucketRequest对象。
            CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucketName);

            // 如果创建存储空间的同时需要指定存储类型、存储空间的读写权限、数据容灾类型, 请参考如下代码。
            // 此处以设置存储空间的存储类型为标准存储为例介绍。
            //createBucketRequest.setStorageClass(StorageClass.Standard);
            // 数据容灾类型默认为本地冗余存储，即DataRedundancyType.LRS。如果需要设置数据容灾类型为同城冗余存储，请设置为DataRedundancyType.ZRS。
            //createBucketRequest.setDataRedundancyType(DataRedundancyType.ZRS);
            // 设置存储空间读写权限为公共读，默认为私有。
            //createBucketRequest.setCannedACL(CannedAccessControlList.PublicRead);

            // 在支持资源组的地域创建Bucket时，您可以为Bucket配置资源组。
            //createBucketRequest.setResourceGroupId(rsId);
            this.ossClient.createBucket(createBucketRequest);
        } catch (OSSException e) {
            log.error("创建存储空间-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("创建存储空间-客户端异常：{}", e.getMessage());
            throw e;
        }
    }

    /**
     * 查看当前账户下的存储空间名称列表
     * @return 存储空间名称列表
     */
    public List<String> listBuckets() {
        List<String> bucketNameList = new LinkedList<>();
        try {
            // 返回当前帐户的所有 Bucket 实例
            List<Bucket> buckets = this.ossClient.listBuckets();
            for (Bucket bucket : buckets) {
                bucketNameList.add(bucket.getName());
            }
        } catch (OSSException e) {
            log.error("查看当前账户下的存储空间名称列表-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("查看当前账户下的存储空间名称列表-客户端异常：{}", e.getMessage());
            throw e;
        }
        return bucketNameList;
    }

    /**
     * 检查存储空间是否存在
     * @return 是否存在
     */
    public boolean doesBucketExist(String bucketName) {
        try {
            return this.ossClient.doesBucketExist(bucketName);
        } catch (OSSException e) {
            log.error("检查存储空间是否存在-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("检查存储空间是否存在-客户端异常：{}", e.getMessage());
            throw e;
        }
    }

    /**
     * 删除存储空间（需确保存储空间为空）
     * 删除不是自己的存储空间会报错：AccessDenied
     * 删除不存在的存储空间会报错：NoSuchBucket
     */
    public void deleteBucket(String bucketName) {
        try {
            this.ossClient.deleteBucket(bucketName);
        } catch (OSSException e) {
            log.error("删除存储空间-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("删除存储空间-客户端异常：{}", e.getMessage());
            throw e;
        }
    }

    /**
     * 上传文件（默认覆盖已存在的文件）
     * @param file 文件
     */
    public void putObject(File file) {
        this.putObject(file.getName(), file);
    }

    /**
     * 上传文件（默认覆盖已存在的文件）
     * @param objectName 文件名
     * @param file 文件
     */
    public void putObject(String objectName, File file) {
        this.putObject(objectName, file, true);
    }

    /**
     * 上传文件
     * @param file 文件
     * @param isCover 文件存在时是否覆盖
     */
    public void putObject(File file, boolean isCover) {
        this.putObject(file.getName(), file, isCover);
    }

    /**
     * 上传文件
     * @param objectName 文件名
     * @param file 文件
     * @param isCover 文件存在时是否覆盖
     */
    public void putObject(String objectName, File file, boolean isCover) {
        FileInputStream inputStream = null;
        try {
            inputStream = new FileInputStream(file);
        } catch (FileNotFoundException e) {
//            throw e;
        }
        this.putObject(objectName, inputStream, isCover);
    }

    /**
     * 上传文件（默认覆盖已存在的文件）
     * @param objectName 文件名
     * @param inputStream 文件流
     */
    public void putObject(String objectName, InputStream inputStream) {
        this.putObject(objectName, inputStream, true);
    }

    /**
     * 上传文件
     * @param objectName 文件名
     * @param inputStream 文件流
     * @param isCover 文件存在时是否覆盖
     */
    public void putObject(String objectName, InputStream inputStream, boolean isCover) {
        // 判断是否覆盖已存在的文件
        if (!isCover && this.doesObjectExist(objectName)) {
            log.warn("文件[{}]已存在，无需上传", objectName);
            return;
        }
        // 创建PutObjectRequest对象。
        PutObjectRequest putObjectRequest = new PutObjectRequest(this.bucketName, objectName, inputStream);

        // 如果需要上传时设置存储类型和访问权限，请参考以下示例代码。
        // ObjectMetadata metadata = new ObjectMetadata();
        // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
        // metadata.setObjectAcl(CannedAccessControlList.Private);
        // putObjectRequest.setMetadata(metadata);
        try {
            // 上传
            this.ossClient.putObject(putObjectRequest);
        } catch (OSSException e) {
            log.error("上传文件-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("上传文件-客户端异常：{}", e.getMessage());
            throw e;
        }
    }

    /**
     * 下载文件
     * @param objectName 文件名
     * @return 文件流
     */
    public InputStream getObject(String objectName) {
        // 判断文件是否存在
        if (!this.doesObjectExist(objectName)) {
            throw new IllegalArgumentException(String.format("文件[%s]不存在", objectName));
        }
        try {
            // ossObject包含文件所在的存储空间名称、文件名称、文件元数据以及一个输入流。
            OSSObject ossObject = this.ossClient.getObject(this.bucketName, objectName);
            return ossObject.getObjectContent();
        } catch (OSSException e) {
            log.error("下载文件-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("下载文件-客户端异常：{}", e.getMessage());
            throw e;
        }
    }

    /**
     * 检查文件是否存在
     * @param objectName 文件名
     * @return 文件是否存在
     */
    public boolean doesObjectExist(String objectName) {
        try {
            // 判断文件是否存在。如果返回值为true，则文件存在，否则存储空间或者文件不存在。
            return this.ossClient.doesObjectExist(this.bucketName, objectName);
        } catch (OSSException e) {
            log.error("检查文件是否存在-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("检查文件是否存在-客户端异常：{}", e.getMessage());
            throw e;
        }
    }

    /**
     * 获取文件元数据
     * @param objectName 文件名
     * @return 文件元数据
     */
    public ObjectMetadata getObjectMetadata(String objectName) {
        // 判断文件是否存在
        if (!this.doesObjectExist(objectName)) {
            throw new IllegalArgumentException(String.format("文件[%s]不存在", objectName));
        }
        try {
            // 获取文件的全部元数据。
            return this.ossClient.getObjectMetadata(this.bucketName, objectName);
        } catch (OSSException e) {
            log.error("获取文件元数据-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("获取文件元数据-客户端异常：{}", e.getMessage());
            throw e;
        }
    }

    /**
     * 列举指定存储空间下的文件名（默认列举100个）
     * @return 文件名列表
     */
    public List<String> listObjects() {
        return this.listObjects("", "", DEFAULT_OBJECT_MAX_KEYS);
    }

    /**
     * 根据文件前缀列举指定存储空间下的所有文件名（默认列举100个）
     * @param objectPrefix 文件前缀
     * @return 文件名列表
     */
    public List<String> listObjects(String objectPrefix) {
        return this.listObjects(objectPrefix, "", DEFAULT_OBJECT_MAX_KEYS);
    }

    /**
     * 列举存储空间下指定个数文件名
     * @param objectCount 文件个数
     * @return 文件名列表
     */
    public List<String> listObjects(int objectCount) {
        return this.listObjects("", "", objectCount);
    }

    /**
     * 根据文件前缀列举指定存储空间下的所有文件名（默认列举100个）
     * @param objectPrefix 文件前缀
     * @param objectDelimiter 文件名分隔符
     * @return 文件名列表
     */
    public List<String> listObjects(String objectPrefix, String objectDelimiter) {
        return this.listObjects(objectPrefix, objectDelimiter, DEFAULT_OBJECT_MAX_KEYS);
    }

    /**
     * 根据文件名前缀列举指定存储空间下的指定个数文件名
     * @param objectPrefix 文件名前缀
     * @param objectDelimiter 文件名分隔符
     * @param objectCount 文件个数
     * @return 文件名列表
     */
    public List<String> listObjects(String objectPrefix, String objectDelimiter, int objectCount) {
        List<String> objectNameList;
        if (objectCount < 1 || objectCount > MAX_RETURNED_KEYS_LIMIT) {
            throw new IllegalArgumentException("文件个数超出范围，默认值：100，取值范围：(0, 1000]");
        }
        try {
            ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
            listObjectsRequest.setPrefix(objectPrefix);
            listObjectsRequest.setMaxKeys(objectCount);
            listObjectsRequest.setDelimiter(objectDelimiter);
            ObjectListing objectListing = this.ossClient.listObjects(listObjectsRequest);
            List<OSSObjectSummary> objectSummaries = objectListing.getObjectSummaries();
            objectNameList = objectSummaries.stream().map(OSSObjectSummary::getKey).collect(Collectors.toList());
        } catch (OSSException e) {
            log.error("根据文件前缀列举指定存储空间下的指定个数文件名-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("根据文件前缀列举指定存储空间下的指定个数文件名-客户端异常：{}", e.getMessage());
            throw e;
        }
        return objectNameList;
    }

    /**
     * 复制文件（同存储空间复制）
     * @param sourceObjectName 源文件名
     * @param targetObjectName 目标文件名
     * @return 成功标志
     */
    public boolean copyObject(String sourceObjectName, String targetObjectName) {
        return this.copyObject(sourceObjectName, this.bucketName, targetObjectName);
    }

    /**
     * 复制文件
     * @param sourceObjectName 源文件名
     * @param targetBucketName 目标存储空间
     * @param targetObjectName 目标文件名
     * @return 成功标志
     */
    public boolean copyObject(String sourceObjectName, String targetBucketName, String targetObjectName) {
        // 判断文件是否存在
        if (!this.doesObjectExist(sourceObjectName)) {
            throw new IllegalArgumentException(String.format("文件[%s]不存在", sourceObjectName));
        }
        // 重命名名称相同
        if (sourceObjectName.equals(targetObjectName)) {
            log.warn("复制后名称相同[{}]", sourceObjectName);
            return true;
        }
        try {
            // 复制文件并重新命名
            this.ossClient.copyObject(this.bucketName, sourceObjectName, targetBucketName, targetObjectName);
            return this.doesObjectExist(targetObjectName);
        } catch (OSSException e) {
            log.error("复制文件-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("复制文件-客户端异常：{}", e.getMessage());
            throw e;
        }
    }

    /**
     * 重命名文件
     * @param sourceObjectName 源文件名
     * @param targetObjectName 目标文件名
     * @return 成功标志
     */
    public boolean renameObject(String sourceObjectName, String targetObjectName) {
        // 重命名名称相同
        if (sourceObjectName.equals(targetObjectName)) {
            log.warn("重命名名称相同[{}]", sourceObjectName);
            return true;
        }
        return this.moveObject(sourceObjectName, this.bucketName, targetObjectName);
    }

    /**
     * 移动文件
     * @param sourceObjectName 源文件名
     * @param targetBucketName 目标存储空间
     * @param targetObjectName 目标文件名
     * @return 成功标志
     */
    public boolean moveObject(String sourceObjectName, String targetBucketName, String targetObjectName) {
        // 复制文件
        boolean copyFlag = this.copyObject(sourceObjectName, targetBucketName, targetObjectName);
        if (copyFlag) {
            // 删除源文件
            return this.deleteObject(sourceObjectName);
        }
        return false;
    }

    /**
     * 删除的单个文件（如果是目录，需确保目录下为空）
     * @param objectName 文件名
     * @return 成功标志
     */
    public boolean deleteObject(String objectName) {
        // 判断文件是否存在
        if (!this.doesObjectExist(objectName)) {
            throw new IllegalArgumentException(String.format("文件[%s]不存在", objectName));
        }
        try {
            this.ossClient.deleteObject(this.bucketName, objectName);
            return this.doesObjectExist(objectName);
        } catch (OSSException e) {
            log.error("删除的单个文件-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("删除的单个文件-客户端异常：{}", e.getMessage());
            throw e;
        }
    }

    /**
     * 删除指定前缀或目录下的多个文件（默认删除1000个）
     * @param objectPrefix 文件名前缀
     * @return 已删除的文件名列表
     */
    public List<String> deleteObjectByPrefix(String objectPrefix) {
        List<String> objectNames = this.listObjects(objectPrefix, "", DELETE_OBJECTS_ONETIME_LIMIT);
        return this.deleteObjects(objectNames);
    }

    /**
     * 根据文件名称列表删除文件（每次最多删除1000个）
     * @param objectNames 要删除的文件名列表
     * @return 已删除的文件名列表
     */
    public List<String> deleteObjects(List<String> objectNames) {
        // 已删除文件名列表
        List<String> deletedObjectList = new ArrayList<>();
        if (objectNames == null || objectNames.isEmpty()) {
            log.warn("没有查询到要删除的文件");
            return deletedObjectList;
        }

        DeleteObjectsRequest deleteObjectsRequest = new DeleteObjectsRequest(bucketName);
        deleteObjectsRequest.withKeys(objectNames);
        deleteObjectsRequest.withEncodingType("url");
        try {
            DeleteObjectsResult deleteObjectsResult = this.ossClient.deleteObjects(deleteObjectsRequest);
            deletedObjectList = deleteObjectsResult.getDeletedObjects();
        } catch (OSSException e) {
            log.error("根据文件名称列表删除文件-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("根据文件名称列表删除文件-客户端异常：{}", e.getMessage());
            throw e;
        }
        return deletedObjectList;
    }

    /**
     * 生成文件预签名url（默认有效10分钟）
     * @param objectName 文件名
     * @return url
     */
    public String generatePresignedUrl(String objectName) {
        return this.generatePresignedUrl(objectName, 1000 * 60 * 10);
    }

    /**
     * 生成文件预签名url
     * @param objectName 文件名
     * @param expiration 有效时长（毫秒）
     * @return url
     */
    public String generatePresignedUrl(String objectName, long expiration) {
        // 判断文件是否存在
        if (!this.doesObjectExist(objectName)) {
            throw new IllegalArgumentException(String.format("文件[%s]不存在", objectName));
        }
        GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(this.bucketName, objectName, HttpMethod.GET);
        request.setExpiration(new Date(System.currentTimeMillis() + expiration));
        try {
            return this.ossClient.generatePresignedUrl(request).toString();
        } catch (OSSException e) {
            log.error("生成文件预签名url-服务端异常：{}", e.getMessage());
            throw e;
        } catch (ClientException e) {
            log.error("生成文件预签名url-客户端异常：{}", e.getMessage());
            throw e;
        }
    }
}