本文档旨在指导开发者如何在 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 对象。
使用方法：
- 将上述代码添加到 Spring Boot 项目中。
- 确保已正确配置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。
- 启动 Spring Boot 应用。
- 使用浏览器或 HTTP 客户端访问 /download/{bucketName}/{fileName} 接口，替换 {bucketName} 和 {fileName} 为实际的 Bucket 名称和文件名。
总结
本教程详细介绍了如何在 Spring Boot 应用中从 GCP Bucket 下载文件。通过创建服务账号、设置环境变量以及编写简单的代码，可以轻松实现文件下载功能。请务必注意安全，妥善保管服务账号密钥，并根据实际需求调整权限设置。
