## 前言

在对象存储（COS）中，"文件夹"的概念与传统文件系统略有不同。COS 本质上是平铺的，没有目录层级。为了模拟文件系统的目录结构，通常采用**以 `/` 结尾的 Key** 来表示文件夹。

此外，对于存储在 COS 上的私有读写文件，如何安全地让前端用户预览或下载，也是开发中常见的问题。

本文将介绍如何在 Spring Boot 中实现：
1.  **创建文件夹**：在 COS 中创建一个逻辑上的“空文件夹”。
2.  **文件预览**：生成带有签名的临时访问 URL，供前端预览文件。

## 一、创建文件夹

### 1. 核心原理

在 COS 中创建一个文件夹，实际上就是上传一个**内容为空、大小为 0、且 Key 以 `/` 结尾**的对象。

### 2. 代码实现

为了简化代码，我们假设已经按照[Spring Boot 实战：手把手教你实现腾讯云 COS 对象存储文件上传](https://cloud.tencent.com/developer/article/2611149)配置好了 `TransferManager` 和 `COSClient`。

```java
@Slf4j
@Service
public class CosFolderService {

    @Autowired
    private COSClient cosClient;

    @Value("${tencent.cos.bucket-name}")
    private String bucketName;

    /**
     * 创建文件夹
     * 
     * @param folderPath 文件夹全路径，例如 "images/2023/"
     * @return 是否创建成功
     */
    public boolean createFolder(String folderPath) {
        // 1. 规范化路径：确保以 "/" 结尾
        if (!folderPath.endsWith("/")) {
            folderPath += "/";
        }

        // 2. 检查文件夹是否已存在（可选）
        // 注意：COS 允许覆盖上传，如果不需要严格检查，可以跳过此步
        if (doesObjectExist(folderPath)) {
            log.warn("文件夹已存在: {}", folderPath);
            return true; 
        }

        try {
            // 3. 创建一个空的 InputStream
            InputStream inputStream = new ByteArrayInputStream(new byte[0]);
            
            // 4. 设置元数据：长度为 0
            ObjectMetadata metadata = new ObjectMetadata();
            metadata.setContentLength(0);
            
            // 5. 提交上传请求
            PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, folderPath, inputStream, metadata);
            PutObjectResult result = cosClient.putObject(putObjectRequest);
            
            if (result.getRequestId() != null) {
                log.info("文件夹创建成功: {}", folderPath);
                return true;
            }
        } catch (Exception e) {
            log.error("创建文件夹失败: {}", e.getMessage(), e);
        }
        return false;
    }
    
    private boolean doesObjectExist(String key) {
        try {
            return cosClient.doesObjectExist(bucketName, key);
        } catch (Exception e) {
            return false;
        }
    }
}
```

**注意事项：**
*   **路径规范**：一定要确保 Key 以 `/` 结尾，否则 COS 会将其视为普通文件（尽管大小为 0）。
*   **数据库同步**：在实际业务（如网盘系统）中，通常还需要在本地数据库中插入一条文件夹记录，以维护目录树结构。

## 二、文件预览

### 1. 核心原理

对于**私有读写**（Private）的 Bucket，文件无法通过简单的 URL 直接访问。我们需要生成一个**预签名 URL（Presigned URL）**。

这个 URL 包含了一个临时的签名（Signature），在指定的时间段内有效。任何人只要持有这个 URL，就可以在有效期内下载或预览该文件。

### 2. 代码实现

```java
@Service
public class CosPreviewService {

    @Autowired
    private COSClient cosClient;

    @Value("${tencent.cos.bucket-name}")
    private String bucketName;

    /**
     * 获取文件预览链接 (预签名 URL)
     * 
     * @param key 文件路径 (如: images/avatar.jpg)
     * @param expirationMinutes 有效期(分钟)
     * @return 带有签名的 URL 字符串
     */
    public String getPreviewUrl(String key, int expirationMinutes) {
        // 1. 设置过期时间
        Date expirationDate = new Date(System.currentTimeMillis() + expirationMinutes * 60 * 1000);
        
        // 2. 生成预签名 URL
        // HttpMethodName.GET 表示该 URL 仅用于 GET 请求（下载/预览）
        URL url = cosClient.generatePresignedUrl(bucketName, key, expirationDate, HttpMethodName.GET);
        
        return url.toString();
    }
}
```

### 3. 高级预览：控制下载行为

有时我们希望控制浏览器是**直接预览**（如图片、PDF）还是**强制下载**。这可以通过设置 `ResponseHeaderOverrides` 来实现。

```java
    /**
     * 获取下载链接（强制浏览器下载，并指定下载文件名）
     */
    public String getDownloadUrl(String key, String downloadFileName) {
        // 设置请求参数
        GeneratePresignedUrlRequest req = new GeneratePresignedUrlRequest(bucketName, key, HttpMethodName.GET);
        
        // 设置过期时间 (例如 30 分钟)
        req.setExpiration(new Date(System.currentTimeMillis() + 30 * 60 * 1000));
        
        // 设置响应头覆盖 (Response Headers Override)
        ResponseHeaderOverrides responseHeaders = new ResponseHeaderOverrides();
        
        // 核心：设置 Content-Disposition 为 attachment，强制下载
        // 并指定 filename，解决中文乱码或自定义文件名问题
        try {
             // 防止中文文件名乱码，通常需要 URL 编码
            String encodedFileName = java.net.URLEncoder.encode(downloadFileName, "UTF-8").replace("+", "%20");
            responseHeaders.setContentDisposition("attachment; filename=\"" + encodedFileName + "\"");
        } catch (UnsupportedEncodingException e) {
            responseHeaders.setContentDisposition("attachment; filename=\"download_file\"");
        }
        
        // 设置 Content-Type (可选，例如强制为 application/octet-stream)
        // responseHeaders.setContentType("application/octet-stream");
        
        req.setResponseHeaders(responseHeaders);
        
        URL url = cosClient.generatePresignedUrl(req);
        return url.toString();
    }
```

## 三、接口设计 (Controller)

```java
@RestController
@RequestMapping("/api/cos")
public class CosController {

    @Autowired
    private CosFolderService cosFolderService;
    
    @Autowired
    private CosPreviewService cosPreviewService;

    // 创建文件夹
    @PostMapping("/folder")
    public String createFolder(@RequestParam String folderPath) {
        boolean success = cosFolderService.createFolder(folderPath);
        return success ? "文件夹创建成功" : "文件夹创建失败";
    }

    // 获取预览链接
    @GetMapping("/preview")
    public String preview(@RequestParam String fileKey) {
        // 生成 30 分钟有效的预览链接
        return cosPreviewService.getPreviewUrl(fileKey, 30);
    }
    
    // 获取下载链接
    @GetMapping("/download")
    public String download(@RequestParam String fileKey) {
        // 简单起见，下载文件名直接使用 Key 的最后一部分
        String fileName = fileKey.substring(fileKey.lastIndexOf("/") + 1);
        return cosPreviewService.getDownloadUrl(fileKey, fileName);
    }
}
```

## 四、关键点总结

1.  **文件夹本质**：COS 中没有真实的文件夹，只有 Key 以 `/` 结尾的 0 字节对象。
2.  **安全性**：对于私有 Bucket，必须使用预签名 URL 进行访问。切勿将 Bucket 设置为公有读写，除非你非常确定数据的公开性。
3.  **URL 有效期**：预签名 URL 具有时效性，生成后应尽快使用。前端不应长期缓存该 URL，而应在每次需要时重新获取（或缓存较短时间）。
4.  **强制下载**：利用 `ResponseHeaderOverrides` 可以灵活控制浏览器的行为（预览 vs 下载）以及下载时的默认文件名。

在对象存储（COS）中，"文件夹"的概念与传统文件系统略有不同。COS 本质上是平铺的，没有目录层级。为了模拟文件系统的目录结构，通常采用以 / 结尾的 Key 来表示文件夹。

Spring Boot 实战：腾讯云 COS 文件夹创建与文件预览

前端开发工程师

后端

云计算

本文详解SpringBoot实现腾讯云COS文件夹创建与文件预览方案。通过上传0字节对象模拟文件夹，使用预签名URL解决私有文件访问问题，提供30分钟有效期的安全预览链接，并支持自定义下载文件名控制浏览器行为。

对象存储

文件系统

数据库

对象存储COS新用户低至1元！


AI驱动 智领未来

tencentdb-catalog

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Spring Boot 实战：腾讯云 COS 文件夹创建与文件预览-腾讯云开发者社区-腾讯云

Spring Boot 实战：腾讯云 COS 文件夹创建与文件预览

Spring Boot 实战：腾讯云 COS 文件夹创建与文件预览

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐