使用 Spring Boot 集成七牛云实现图片/文件上传

在 Web 开发中，文件上传是一个常见需求，比如用户头像、商品图片等。传统做法是把文件直接存储在本地服务器，但这种方式存在磁盘容量有限、备份不便、访问速度不稳定等问题。

为了更好地处理文件存储，我们可以使用云存储 。今天我们以七牛云对象存储为例，讲解如何在 Spring Boot 项目中集成，实现图片/文件上传。

---

一、准备工作

1. 注册七牛云账号

   前往 七牛云官网 注册并完成实名认证。

2. 创建存储空间（Bucket）

   • 登录控制台 → 对象存储 → 新建空间

   • 选择存储区域（如华东、华北等）

   • 设置空间访问权限（公开 / 私有）

3. 获取 AccessKey 和 SecretKey

   • 个人中心 → 密钥管理 → 复制 AccessKey 和 SecretKey
     （注意不要泄露，最好使用 .yml 配置文件管理）

4. 绑定自定义域名（可选）

   • 用七牛云默认的测试域名也可以，但正式项目建议绑定自己的 CDN 域名，提升稳定性和品牌感。

---

二、Spring Boot 集成七牛云

1. 添加依赖

在 pom.xml 中添加七牛云 SDK：

<dependency>
    <groupId>com.qiniu</groupId>
    <artifactId>qiniu-java-sdk</artifactId>
    <version>7.13.0</version>
</dependency>
<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.50</version>
</dependency>

---

2. 配置文件（application.yml）

qiniu:
  accessKey: agsfbiyawhegfhobalkjsfhiuagiflujqaes
  accessSecretKey: CM4-6tyofviuahfiuhawg-
  bucketName: 1111
  region: huadong

---

3. 工具类 QiniuUtils

package warren.myblog.utils;

import com.alibaba.fastjson2.JSON;
import com.qiniu.http.Response;
import com.qiniu.storage.Region;
import com.qiniu.storage.UploadManager;
import com.qiniu.storage.model.DefaultPutRet;
import com.qiniu.util.Auth;
import org.springframework.stereotype.Component;
import org.springframework.web.multipart.MultipartFile;
import com.qiniu.storage.Configuration;
import org.springframework.beans.factory.annotation.Value;

@Component
public class QiniuUtils {

    // 七牛云存储访问域名（替换成自己的）
    public static final String url = "http://afhuioasnm.ef-sdghi.clouddn.com/";

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

    /**
     * 上传文件到七牛云
     */
    public boolean upload(MultipartFile file, String fileName) {
        try {
            // 配置存储区域
            Configuration cfg = new Configuration(Region.autoRegion());
            UploadManager uploadManager = new UploadManager(cfg);

            // 获取上传凭证
            Auth auth = Auth.create(accessKey, accessSecretKey);
            String upToken = auth.uploadToken(bucket);

            // 上传文件
            byte[] uploadBytes = file.getBytes();
            Response response = uploadManager.put(uploadBytes, fileName, upToken);

            // 解析上传结果
            DefaultPutRet putRet = JSON.parseObject(response.bodyString(), DefaultPutRet.class);
            return true;
        } catch (Exception ex) {
            ex.printStackTrace();
        }
        return false;
    }
}

---

4. 控制器 UploadController

package warren.myblog.controller;

import io.swagger.v3.oas.annotations.Operation;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import warren.myblog.common.Result;
import warren.myblog.utils.QiniuUtils;

import java.util.UUID;

import static warren.myblog.Params.ErrorCode.FILE_UPLOAD_ERROR;

@RestController
@RequestMapping
public class UploadController {

    @Autowired
    private QiniuUtils qiniuUtils;

    @Operation(tags = "上传图片")
    @PostMapping("/user/upload")
    public Result upload(@RequestParam("file") MultipartFile file) {
        String fileName = UUID.randomUUID() + "." + StringUtils.substringAfterLast(file.getOriginalFilename(), ".");
        boolean upload = qiniuUtils.upload(file, fileName);
        if (upload) {
            return Result.success(QiniuUtils.url + fileName);
        }
        return Result.fail(FILE_UPLOAD_ERROR.getCode(), FILE_UPLOAD_ERROR.getMsg());
    }
}

---

三、与其他存储方案对比

• 七牛云：适合个人博客、小型项目，性价比高

• 阿里云 OSS：适合企业生产环境，需要高 SLA、全球加速

• MinIO：适合有自建需求、私有化部署的场景，比如公司内部文件管理