Spring Boot 从 GCP 下载文件教程

本文档旨在指导开发者如何在 Spring Boot 应用中集成 Google Cloud Storage (GCS)，并提供一个 API 来下载 GCS Bucket 中的文件。内容涵盖必要的环境配置，包括创建服务账号、设置环境变量，以及编写下载文件的代码。通过本文，你将能够安全高效地实现 Spring Boot 应用与 GCS 的交互，轻松完成文件下载功能。

前期准备

在开始编写下载文件的代码之前，需要进行一些必要的配置，以确保 Spring Boot 应用能够成功连接并访问 GCS Bucket。

1. 创建服务账号

首先，需要在 Google Cloud Platform (GCP) 的 IAM (Identity and Access Management) 页面创建一个服务账号。服务账号是一种特殊类型的 Google 账号，用于代表非人类用户（例如应用程序）进行身份验证和授权。

• 登录 GCP 控制台，导航至 "IAM & Admin" -> "Service Accounts"。
• 点击 "CREATE SERVICE ACCOUNT" 按钮。
• 为服务账号指定一个名称和描述。
• 授予服务账号适当的权限。为了下载 GCS Bucket 中的文件，至少需要授予 Storage Object Viewer 角色。 如果需要写入，则授予Storage Object Admin角色。
• 点击 "DONE" 完成服务账号的创建。

2. 下载服务账号密钥

创建服务账号后，需要下载一个 JSON 格式的密钥文件。该密钥文件包含服务账号的凭据，Spring Boot 应用将使用它来向 GCP 进行身份验证。

• 在 IAM 页面中，找到刚刚创建的服务账号。
• 点击服务账号名称进入详情页面。
• 导航至 "KEYS" 选项卡。
• 点击 "ADD KEY" -> "Create new key"。
• 选择 JSON 格式，然后点击 "CREATE" 下载密钥文件。
• 妥善保管此密钥文件，不要将其泄露给他人。

3. 设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量

在 Spring Boot 应用启动之前，需要设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量，将其指向刚刚下载的 JSON 密钥文件的路径。Spring Boot 应用将通过此环境变量找到服务账号的凭据，并自动进行身份验证。

• 在操作系统中设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。
  • Linux/macOS: export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"
  • Windows: set GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\service-account-key.json"

注意事项：

• 确保密钥文件路径正确。
• 建议将环境变量设置为系统级别，以便所有应用都能访问。
• 在某些集成开发环境 (IDE) 中，可能需要在 IDE 的配置中设置环境变量。

Spring Boot 代码示例

完成以上配置后，就可以在 Spring Boot 应用中编写下载文件的代码了。以下是一个简单的示例，展示如何使用 Google Cloud Storage Java 客户端库下载文件：

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

import java.io.IOException;

@RestController
public class FileDownloadController {

    @GetMapping("/download/{bucketName}/{fileName}")
    public ResponseEntity downloadFile(@PathVariable String bucketName, @PathVariable String fileName) throws IOException {

        Storage storage = StorageOptions.getDefaultInstance().getService();
        BlobId blobId = BlobId.of(bucketName, fileName);
        Blob blob = storage.get(blobId);

        if (blob == null) {
            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
        }

        byte[] content = blob.getContent();

        HttpHeaders headers = new HttpHeaders();
        headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + fileName + "\"");
        headers.add("Cache-Control", "no-cache, no-store, must-revalidate");
        headers.add("Pragma", "no-cache");
        headers.add("Expires", "0");

        return new ResponseEntity<>(content, headers, HttpStatus.OK);
    }
}

代码解释：

• StorageOptions.getDefaultInstance().getService(): 使用默认的凭据（即通过 GOOGLE_APPLICATION_CREDENTIALS 环境变量指定的凭据）创建 Storage 对象。
• BlobId.of(bucketName, fileName): 创建 BlobId 对象，指定要下载的文件所在的 Bucket 名称和文件名。
• storage.get(blobId): 从 GCS 获取 Blob 对象，代表要下载的文件。
• blob.getContent(): 获取文件的内容。
• HttpHeaders: 设置 HTTP 响应头，包括 Content-Disposition (指定下载的文件名) 和缓存控制。
• ResponseEntity: 返回包含文件内容和 HTTP 响应头的 ResponseEntity 对象。

使用方法：

1. 将上述代码添加到 Spring Boot 项目中。
2. 确保已正确配置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。
3. 启动 Spring Boot 应用。
4. 使用浏览器或 HTTP 客户端访问 /download/{bucketName}/{fileName} 接口，替换 {bucketName} 和 {fileName} 为实际的 Bucket 名称和文件名。

总结

本教程详细介绍了如何在 Spring Boot 应用中从 GCP Bucket 下载文件。通过创建服务账号、设置环境变量以及编写简单的代码，可以轻松实现文件下载功能。请务必注意安全，妥善保管服务账号密钥，并根据实际需求调整权限设置。