使用Java如何通过七牛云上传及下载文件？

七牛云是一家领先的云存储解决方案提供商，提供了强大的文件上传和下载功能。在 Java 开发中，通过七牛云实现文件上传和下载非常方便。本文将详细介绍如何使用 Java 通过七牛云上传和下载文件，并提供相应的代码示例。

一、前期准备

（一）注册账号与获取密钥

访问七牛云官网完成注册流程。注册成功后，进入「个人中心」，找到 AccessKey（AK）和 SecretKey（SK），这是访问七牛云服务的身份凭证，千万不能泄露给别人。

然后，在对象存储 Kodo 里创建存储空间，官方管这个存储空间叫 Bucket，专门用来放你的文件。创建的时候，记得记录下 Bucket 名称以及所属区域，比如华东、华北这些，不同区域可能在网络访问速度、费用等方面有点小区别。

（二）引入 Java SDK 依赖

这里我假设你用的是 Maven 项目，那就在项目的 pom.xml 文件里添加七牛云 Java SDK 依赖。版本建议用 7.4.0 以上的稳定版，功能更完善，bug 也少些。代码如下：

<dependency>
    <groupId>com.qiniu</groupId>
    <artifactId>qiniu-java-sdk</artifactId>
    <version>7.4.0</version>
</dependency>

这里，为了方便解析七牛云 API 返回的响应数据，还得引入 Gson 库。引入代码如下：

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.8.6</version>
</dependency>

添加完依赖后，记得让项目构建工具（Maven）正确加载这些依赖包。在命令行里执行mvn clean install命令，让 Maven 去下载并管理这些依赖，确保项目构建成功，为后续开发做好环境准备。要是用 Gradle 构建项目，引入依赖的方式稍有不同，但目的是一样的，大家可以去查下 Gradle 的依赖引入文档。

二、文件上传：从基础实现到工程化封装

（一）核心原理与基础代码实现

上传文件到七牛云，就像是你去快递站寄包裹，得先有个“通行证”，在七牛云里，这个“通行证”就是上传凭证（UpToken）。

1.生成上传凭证（UpToken）

在 Java 代码里，生成这个凭证得靠 Auth 类，结合之前获取的 AK、SK 以及 Bucket 名称来生成 UpToken。具体代码如下：

import com.qiniu.util.Auth;

// 假设已经获取到 AK、SK 和 Bucket 名称
String accessKey = "你的 AccessKey";
String secretKey = "你的 SecretKey";
String bucket = "你的 Bucket 名称";

Auth auth = Auth.create(accessKey, secretKey);
// 生成上传凭证，这里使用默认策略，有效期为 3600 秒（1 小时）
String upToken = auth.uploadToken(bucket);

这里生成的 upToken 就是后续上传文件必不可少的权限凭证。而且这个 uploadToken()方法还有不同的重载形式，比如你想实现临时授权，限制上传凭证的有效时间，或者要进行覆盖上传操作，指定要覆盖的目标文件名（Key），都可以通过这些重载方法灵活实现 。比如，设置上传凭证有效期为 600 秒（10 分钟）：

// 生成有效期为 600 秒的上传凭证
String upTokenWithExpires = auth.uploadToken(bucket, null, 600, null);

如果要进行覆盖上传，这里我假设目标文件 Key 为 “oldFile.jpg”：

String targetKey = "oldFile.jpg";
// 生成用于覆盖上传的凭证
String overrideUpToken = auth.uploadToken(bucket, targetKey);

2. 服务端上传实战

有了上传凭证，接下来就可以真正上传文件了。首先得配置上传区域，不同的区域就像是不同的快递站点，你得选对站点才能顺利寄件。七牛云提供了多个区域，比如 Region.region0()代表华东区域。同时，还得设置分片上传版本，因为这关系到文件上传的效率和稳定性。代码示例如下：

import com.qiniu.common.Zone;
import com.qiniu.storage.Configuration;
import com.qiniu.storage.UploadManager;
import com.qiniu.util.Auth;

// 配置上传区域，这里选择华东区域
Zone zone = Zone.zone0();
Configuration cfg = new Configuration(zone);
// 指定分片上传版本，这里使用 V2 版本
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;

UploadManager uploadManager = new UploadManager(cfg);

接着，调用 put()方法来上传文件，这个方法需要传入本地文件路径、目标文件名（Key）和前面生成的 UpToken 。示例代码如下：

import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.model.DefaultPutRet;
import com.google.gson.Gson;

// 本地文件路径
String localFilePath = "C:/Users/yourUsername/Desktop/test.jpg";
// 目标文件名（Key），如果为 null，七牛云会自动生成一个唯一的文件名
String key = "test.jpg";
String upToken = auth.uploadToken(bucket);

try {
    Response response = uploadManager.put(localFilePath, key, upToken);
    // 解析上传成功的结果
    DefaultPutRet putRet = new Gson().fromJson(response.bodyString(), DefaultPutRet.class);
    System.out.println("上传成功，文件 Key: " + putRet.key);
    System.out.println("文件 Hash: " + putRet.hash);
} catch (QiniuException e) {
    Response r = e.response;
    System.err.println("上传失败，状态码: " + r.statusCode);
    System.err.println("错误信息: " + r.error);
}

上面代码中，put()方法会同步执行上传操作，成功后返回的响应里包含了上传文件的 Key 和 Hash 值，这些信息在后续管理文件时非常有用。

（二）工程化封装与最佳实践

上面的基础代码虽然能实现文件上传，但在实际项目开发中，还需要进行工程化封装，让代码更具复用性和可维护性。

1. 工具类封装

我们可以创建一个 QiniuUpload 工具类，把和七牛云上传相关的操作都封装进去，要用的时候直接从里面拿方法就行。

首先，通过依赖注入的方式把 AK、SK 和 Bucket 等配置信息注入进来，然后封装获取上传凭证、普通上传、覆盖上传等方法。示例代码如下：

import com.google.gson.Gson;
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.Configuration;
import com.qiniu.storage.Region;
import com.qiniu.storage.UploadManager;
import com.qiniu.storage.model.DefaultPutRet;
import com.qiniu.util.Auth;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

@Slf4j
@Component
public class QiniuUpload {

    private final String accessKey;
    private final String secretKey;
    private final String bucket;

    public QiniuUpload(String accessKey, String secretKey, String bucket) {
        this.accessKey = accessKey;
        this.secretKey = secretKey;
        this.bucket = bucket;
    }

    /**
     * 获取上传凭证
     */
    public String getUploadToken() {
        Auth auth = Auth.create(accessKey, secretKey);
        return auth.uploadToken(bucket);
    }

    /**
     * 普通文件上传
     */
    public String uploadFile(String localFilePath, String key) throws QiniuException {
        Region region = Region.region0();
        Configuration cfg = new Configuration(region);
        cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;
        UploadManager uploadManager = new UploadManager(cfg);
        String upToken = getUploadToken();

        Response response = uploadManager.put(localFilePath, key, upToken);
        log.info("服务器上传成功！bodyString: {}, body: {}", response.bodyString(), response.body());

        DefaultPutRet putRet = new Gson().fromJson(response.bodyString(), DefaultPutRet.class);
        log.info("key: {}, hash: {}", putRet.key, putRet.hash);
        return putRet.key;
    }

    /**
     * 覆盖文件上传
     */
    public String overrideUploadFile(String localFilePath, String key) throws QiniuException {
        Region region = Region.region0();
        Configuration cfg = new Configuration(region);
        cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;
        UploadManager uploadManager = new UploadManager(cfg);

        Auth auth = Auth.create(accessKey, secretKey);
        String upToken = auth.uploadToken(bucket, key);

        Response response = uploadManager.put(localFilePath, key, upToken);
        log.info("服务器覆盖上传成功！bodyString: {}, body: {}", response.bodyString(), response.body());

        DefaultPutRet putRet = new Gson().fromJson(response.bodyString(), DefaultPutRet.class);
        log.info("覆盖上传后 key: {}, hash: {}", putRet.key, putRet.hash);
        return putRet.key;
    }
}

这里使用了 Lombok 的 Slf4j 注解来记录日志，方便追踪上传状态，出了问题也能快速定位。同时，借助 Gson 库解析七牛云返回的响应数据，把复杂的数据格式转换成 Java 对象，便于处理。

2. Spring Boot 集成方案

在 Spring Boot 项目中集成七牛云上传功能，能更好地和项目的其他模块协同工作。首先，通过ConfigurationProperties注解从application.yml配置文件中读取七牛云的相关配置，比如 AK、SK、Bucket 名称等。示例配置如下：

qiniu:
  accessKey: yourAccessKey
  secretKey: yourSecretKey
  bucket: yourBucketName
  domain: yourDomainName # 存储空间域名，用于生成文件外链

然后，创建一个配置类，把这些配置信息注入到常量类或者直接注入到 QiniuUpload 工具类中 。示例代码如下：

import com.qiniu.storage.Region;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class QiniuConfig {

    @Value("${qiniu.accessKey}")
    private String accessKey;

    @Value("${qiniu.secretKey}")
    private String secretKey;

    @Value("${qiniu.bucket}")
    private String bucket;

    @Bean
    public QiniuUpload qiniuUpload() {
        return new QiniuUpload(accessKey, secretKey, bucket);
    }

    // 如果需要，还可以配置上传区域等其他 Bean
    @Bean
    public Region qiniuRegion() {
        return Region.region0();
    }
}

在 Controller 层，我们可以实现文件类型（图片 / 文件）的差异化处理。比如，对于图片上传，可以在上传成功后返回包含图片外链的统一响应对象，方便前端展示 。示例代码如下：

import com.qiniu.common.QiniuException;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import java.io.File;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;

@RestController
@RequestMapping("/qiniu")
public class QiniuController {

    @Autowired
    private QiniuUpload qiniuUpload;

    @Value("${qiniu.domain}")
    private String domain;

    @PostMapping("/upload/image")
    public Map<String, Object> uploadImage(@RequestParam("file") MultipartFile file) {
        Map<String, Object> result = new HashMap<>();
        try {
            // 生成唯一的文件名
            String fileName = UUID.randomUUID().toString() + "." + getFileExtension(file.getOriginalFilename());
            // 临时存储文件
            File tempFile = File.createTempFile("temp", null);
            file.transferTo(tempFile);

            String key = qiniuUpload.uploadFile(tempFile.getAbsolutePath(), fileName);
            // 删除临时文件
            tempFile.delete();

            // 生成图片外链
            String imageUrl = "http://" + domain + "/" + key;
            result.put("code", 200);
            result.put("message", "图片上传成功");
            result.put("data", imageUrl);
        } catch (QiniuException | IOException e) {
            result.put("code", 500);
            result.put("message", "图片上传失败: " + e.getMessage());
        }
        return result;
    }

    // 获取文件扩展名的方法
    private String getFileExtension(String fileName) {
        int index = fileName.lastIndexOf(".");
        if (index != -1) {
            return fileName.substring(index + 1);
        }
        return "";
    }
}

这样，通过 Spring Boot 的集成，七牛云上传功能就完美融入到 Web 开发项目中，无论是处理用户上传的图片还是其他文件，都变得更加便捷高效。

三、文件下载：多场景解决方案详解

（一）Java SDK 下载单个文件

在 Java 开发中，使用七牛云 Java SDK 下载单个文件主要有以下几个关键步骤：

1. 构建下载 URL

利用七牛云文件外链规则（http://<域名>/< 文件 Key>）生成下载链接。假设你的七牛云存储空间绑定的域名为 yourDomain.com，要下载的文件 Key 为 test.jpg，那么下载链接就是 http://yourDomain.com/test.jpg。

如果是私有 Bucket，为了保证资源安全，得添加签名认证。在 Java 代码里，通过 Auth 类生成带有签名的下载链接，示例代码如下：

import com.qiniu.util.Auth;

// 假设已经获取到 AK、SK、域名和文件 Key
String accessKey = "你的 AccessKey";
String secretKey = "你的 SecretKey";
String domain = "你的存储空间域名";
String key = "test.jpg";

Auth auth = Auth.create(accessKey, secretKey);
// 生成带有签名的下载链接，有效时间为 3600 秒（1 小时）
String downloadUrl = auth.privateDownloadUrl("http://" + domain + "/" + key, 3600);

这里生成的downloadUrl就包含了访问该文件的签名认证信息，在有效时间内，通过这个链接就能安全下载文件。

2. 流处理与乱码解决

有了下载链接，接下来就得获取文件内容。我们可以使用HttpURLConnection或OkHttp来发起 HTTP 请求获取输入流。以HttpURLConnection为例，示例代码如下：

import java.io.BufferedInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class QiniuDownload {
    public static void downloadFile(String downloadUrl, String localFilePath) throws IOException {
        URL url = new URL(downloadUrl);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");

        // 设置响应头，控制文件名
        String disposition = conn.getHeaderField("Content-Disposition");
        if (disposition != null && disposition.contains("attachment;")) {
            // 从响应头中提取文件名
            String[] parts = disposition.split("filename=");
            if (parts.length == 2) {
                String fileName = parts[1].trim().replace("\"", "");
                localFilePath += fileName;
            }
        }

        try (InputStream inputStream = new BufferedInputStream(conn.getInputStream());
             FileOutputStream fileOutputStream = new FileOutputStream(localFilePath)) {
            byte[] buffer = new byte[1024];
            int bytesRead;
            while ((bytesRead = inputStream.read(buffer)) != -1) {
                fileOutputStream.write(buffer, 0, bytesRead);
            }
        }
    }
}

在处理中文文件名时，不同浏览器有不同的编码方式，容易出现乱码问题 。比如 IE 浏览器通常使用URLEncoder编码，而 Chrome 浏览器一般使用ISO8859 - 1编码 。解决这个问题，我们以根据不同浏览器的类型进行相应的编码处理 。示例代码如下：

import javax.servlet.http.HttpServletRequest;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class FileNameEncodingUtil {
    public static String encodeFileName(String fileName, HttpServletRequest request) {
        String userAgent = request.getHeader("User - Agent").toLowerCase();
        try {
            if (userAgent.contains("msie") || userAgent.contains("trident")) {
                // IE 浏览器
                return URLEncoder.encode(fileName, "UTF-8").replaceAll("\\+", "%20");
            } else if (userAgent.contains("chrome") || userAgent.contains("safari")) {
                // Chrome、Safari 浏览器
                return "=?UTF-8?B?" + Base64.getEncoder().encodeToString(fileName.getBytes(StandardCharsets.UTF_8)) + "?=";
            } else {
                // 其他浏览器
                return URLEncoder.encode(fileName, "UTF-8").replaceAll("\\+", "%20");
            }
        } catch (Exception e) {
            return fileName;
        }
    }
}

这样，在设置 Content-Disposition 响应头时，调用这个工具方法对文件名进行编码处理，就能确保在不同浏览器中都能正确显示文件名，避免乱码问题。

（二）qshell 工具批量下载

当需要从七牛云批量下载大量文件时，一个个手动下载或者使用 Java SDK 逐个下载效率就不高了。这时候，七牛云提供的 qshell 命令行工具就派上用场了。

1. 工具配置与环境搭建

首先，得从七牛开发者中心下载对应系统的 qshell 命令行工具。根据自己的电脑系统，下载对应的版本。下载完成后，创建一个独立的文件夹，比如命名为 qiniu_qshell，把下载好的 qshell 工具放到这个文件夹里，同时这个文件夹也用来存放后续的配置文件。

接着，要进行账号认证。打开命令行窗口，切换到存放 qshell 工具的文件夹路径下，执行qshell account AK SK命令，其中 AK 是你的 AccessKey，SK 是你的 SecretKey。示例命令如下：

qshell account yourAccessKey yourSecretKey

执行成功后，qshell 工具就完成了账号认证，具备了操作七牛云存储的权限。

2. 配置文件与批量下载

为了让 qshell 工具知道要下载哪些文件、下载到哪里，需要新建一个配置文件。在存放 qshell 工具的文件夹里，新建一个名为 qshell.conf 的文件，文件内容如下：

{
    "dest_dir": "D:/downloaded_files",
    "bucket": "yourBucketName",
    "cdn_domain": "http://yourCdnDomain.com",
    "prefix": "images/",
    "suffix": ".jpg"
}

• dest_dir：指定本地存储路径，也就是下载的文件要存放在本地哪个文件夹，这里设置为D:/downloaded_files。在 Windows 系统下，路径中的反斜杠要写成双反斜杠（\）。
• bucket：填写你的七牛云 Bucket 名称。
• cdn_domain：设置 CDN 域名（可选），如果你的七牛云存储空间绑定了 CDN 加速域名，并且希望通过 CDN 下载文件以享受免费流量或者加快下载速度，可以在这里填写。注意，该功能默认需要计费，如果希望享受 10G 的免费流量，请自行设置cdn_domain参数，如不设置，需支付源站流量费用。
• prefix：只同步指定前缀的文件，这里设置为images/，表示只下载 Bucket 中images/目录下的文件。
• suffix：只同步指定后缀的文件，这里设置为.jpg，表示只下载 jpg 格式的文件。

配置好文件后，就可以使用qshell qdownload命令启动批量下载了。示例命令如下：

qshell qdownload 10 qshell.conf

这里的 10 表示下载的并发线程数，也就是同时可以有 10 个线程一起下载文件。线程数并不是越多越好，要根据你的网络带宽、服务器性能等因素合理设置，一般建议控制在 1-2000 范围内，这样能优化下载速度。执行这个命令后，qshell 工具就会按照配置文件的要求，从七牛云批量下载符合条件的文件到本地指定路径。

四、进阶技巧与避坑指南

（一）性能优化与异常处理

1. 分片上传优化

在处理大文件上传时，开启分片上传（V2 版本）是提升上传效率和稳定性的关键。你可以通过设置Configuration对象中的resumableUploadAPIVersion参数来指定使用 V2 版本的分片上传。合理设置分片大小也很重要，比如将分片大小设置为 5MB（5*1024*1024），这样大文件会被拆分成多个 5MB 的小片段进行上传。如果在上传过程中遇到网络中断，下次只需从断点处继续上传未完成的分片，而不用重新上传整个文件，大大提高了上传的可靠性。示例代码如下：

Zone zone = Zone.zone0();
Configuration cfg = new Configuration(zone);
// 指定分片上传版本为 V2
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;
// 设置分片大小为 5MB
cfg.chunkSize = 5 * 1024 * 1024;

UploadManager uploadManager = new UploadManager(cfg);

2. 异常捕获与重试机制

在上传和下载方法中，一定要添加 QiniuException 捕获 。比如在上传文件时，如果网络不稳定，可能会抛出网络超时异常；如果 AK、SK 配置错误，会抛出权限错误异常 。通过捕获这些异常，我们可以根据不同的异常类型进行相应处理 。例如，对于网络超时异常，可以结合业务需求实现自动重试逻辑 。假设我们设置最多重试 3 次，每次重试间隔 2 秒，示例代码如下：

import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.UploadManager;
import com.qiniu.util.Auth;
import com.qiniu.util.StringMap;

public class QiniuUpload {

    private final String accessKey;
    private final String secretKey;
    private final String bucket;

    public QiniuUpload(String accessKey, String secretKey, String bucket) {
        this.accessKey = accessKey;
        this.secretKey = secretKey;
        this.bucket = bucket;
    }

    public String uploadFile(String localFilePath, String key) {
        Auth auth = Auth.create(accessKey, secretKey);
        String upToken = auth.uploadToken(bucket);

        UploadManager uploadManager = new UploadManager();

        int maxRetries = 3;
        int retryInterval = 2000; // 2 秒

        for (int i = 0; i < maxRetries; i++) {
            try {
                Response response = uploadManager.put(localFilePath, key, upToken);
                return response.bodyString();
            } catch (QiniuException e) {
                Response r = e.response;
                System.err.println("上传失败，状态码: " + r.statusCode);
                System.err.println("错误信息: " + r.error);

                if (i < maxRetries - 1) {
                    try {
                        Thread.sleep(retryInterval);
                    } catch (InterruptedException ex) {
                        Thread.currentThread().interrupt();
                    }
                } else {
                    throw new RuntimeException("上传文件失败，已达到最大重试次数", e);
                }
            }
        }
        return null;
    }
}

这样，在面对复杂的网络环境和各种潜在错误时，文件操作的可靠性得到了有效保障。

（二）成本控制与合规建议

1.流量优化：合理配置 CDN 域名能有效分担源站流量，降低存储和传输成本。在使用 qshell 工具批量下载文件时，可以利用 qshell.conf 配置文件中的 cdn_domain 参数启用 CDN 下载。比如你的 CDN 域名为 http://yourCdnDomain.com，在配置文件中设置cdn_domain":"http://yourCdnDomain.com。七牛云提供了一定额度的免费流量，充分利用这部分免费流量，可以为项目节省开支。同时，定期分析 CDN 流量使用情况，根据业务访问量合理调整 CDN 配置，确保流量利用的高效性。

2.文件权限管理：区分公开 Bucket 和私有 Bucket 的使用场景非常重要。对于一些公开的资源，比如公司官网展示的图片、文档等，可以存放在公开 Bucket 中，方便用户直接访问。但对于敏感文件，如用户的个人信息文件、商业机密文件等，一定要存放在私有 Bucket 中。并且，采用临时签名 URL 的方式限制访问时效，例如生成一个有效期为 10 分钟的临时签名 URL，让用户在这 10 分钟内访问文件，时间一到，URL 就失效。另外，要通过七牛云控制台定期审计密钥权限，查看 AK、SK 的使用情况，确保没有权限滥用的情况发生，保障数据安全合规。

以上关于使用Java如何通过七牛云上传及下载文件？的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。