若依微服务版集成阿里云oss

文章目录

前言
一、集成步骤
- [阿里云 OSS 配置属性类（AliyunOSSProperties.java）](#阿里云 OSS 配置属性类（AliyunOSSProperties.java）)
- [OSS 操作工具类（AliyunOSSOperator.java）](#OSS 操作工具类（AliyunOSSOperator.java）)
- [OSS 文件服务实现类OssSysServiceImpl.java](#OSS 文件服务实现类OssSysServiceImpl.java)
- 配置默认文件服务
- 编写文件上传控制器
- [配置 Nacos 参数](#配置 Nacos 参数)
- 依赖配置（pom.xml）
总结

前言

本文档详细介绍若依微服务版项目集成阿里云 OSS（对象存储服务）的完整流程，包括环境准备、代码实现、配置说明及功能验证。集成后，系统可通过阿里云 OSS 实现文件的上传存储，并支持生成公开访问 URL，适用于各类文件存储场景（如图片、文档等）。

（一）阿里云 OSS 资源准备

登录阿里云 OSS 控制台，创建专属 Bucket（存储空间），建议设置访问权限为 "public-read"（公开读私有写），确保文件上传后可通过 URL 直接访问。

获取访问密钥（AccessKey）：登录阿里云控制台，进入 "访问控制 RAM" 页面，创建用于 OSS 访问的 AccessKeyId 和 AccessKeySecret，需记录该密钥对用于配置文件。

确认 OSS 地域与 Endpoint：根据 Bucket 所在地域，获取对应的 OSS Endpoint（例如华东 1 地域 Endpoint 为oss-cn-hangzhou.aliyuncs.com），可在阿里云 OSS 控制台的 Bucket 概览页查询。

（二）项目环境要求

若依微服务版框架（基于 Spring Cloud/Spring Boot）

JDK 1.8 及以上

Maven 3.6 及以上

阿里云 OSS Java SDK（项目将通过依赖自动引入）

一、集成步骤

在file模块相应包创建类

阿里云 OSS 配置属性类（AliyunOSSProperties.java）

用于绑定 Nacos 配置中心的 OSS 相关配置，封装 Endpoint、BucketName、AccessKey 等核心参数

java 复制代码

package com.manage.file.utils;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * 阿里云OSS配置属性类
 * 绑定配置文件中前缀为 "aliyun.oss" 的配置项
 */
@Component
@ConfigurationProperties(prefix = "aliyun.oss")
public class AliyunOSSProperties {
    // OSS服务端点（如：oss-cn-hangzhou.aliyuncs.com）
    private String endpoint;
    // 存储空间名称
    private String bucketName;
    // 地域（可选，部分场景需指定）
    private String region;
    // 访问密钥ID
    private String accessKeyId;
    // 访问密钥Secret
    private String accessKeySecret;

    // Getter和Setter方法
    public String getEndpoint() { return endpoint; }
    public void setEndpoint(String endpoint) { this.endpoint = endpoint; }
    public String getBucketName() { return bucketName; }
    public void setBucketName(String bucketName) { this.bucketName = bucketName; }
    public String getRegion() { return region; }
    public void setRegion(String region) { this.region = region; }
    public String getAccessKeyId() { return accessKeyId; }
    public void setAccessKeyId(String accessKeyId) { this.accessKeyId = accessKeyId; }
    public String getAccessKeySecret() { return accessKeySecret; }
    public void setAccessKeySecret(String accessKeySecret) { this.accessKeySecret = accessKeySecret; }
}

OSS 操作工具类（AliyunOSSOperator.java）

封装 OSS 文件上传核心逻辑，提供字节数组形式的文件上传方法，支持按日期分目录存储和 UUID 生成唯一文件名。

java 复制代码

package com.manage.file.utils;

import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClient;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import java.io.ByteArrayInputStream;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.util.UUID;

/**
 * 阿里云OSS操作工具类
 * 提供文件上传等核心操作方法
 */
@Component
public class AliyunOSSOperator {
    @Autowired
    private AliyunOSSProperties aliyunOSSProperties;

    /**
     * 上传字节数组内容到OSS
     * @param content 文件字节数组
     * @param originalFilename 原始文件名（用于获取文件后缀）
     * @return 上传后的文件公开访问URL
     * @throws Exception 上传过程中抛出的异常
     */
    public String upload(byte[] content, String originalFilename) throws Exception {
        // 获取OSS配置参数
        String endpoint = aliyunOSSProperties.getEndpoint();
        String bucketName = aliyunOSSProperties.getBucketName();
        String accessKeyId = aliyunOSSProperties.getAccessKeyId();
        String accessKeySecret = aliyunOSSProperties.getAccessKeySecret();

        // 构建凭证提供者
        DefaultCredentialProvider credentialProvider = new DefaultCredentialProvider(accessKeyId, accessKeySecret);
        // 创建OSS客户端（传统方式）
        OSS ossClient = new OSSClient(endpoint, credentialProvider, null);

        try {
            // 设置签名版本为V4（适配部分地域要求）
            System.setProperty("oss.signature.version", "v4");
            // 按日期分目录（格式：yyyy/MM）
            String dir = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM"));
            // 获取文件后缀（如：.jpg、.pdf）
            String ext = originalFilename.substring(originalFilename.lastIndexOf("."));
            // 生成唯一文件名（UUID+后缀，避免文件名重复）
            String newFileName = UUID.randomUUID() + ext;
            // 构建OSS中的文件路径（目录+文件名）
            String objectName = dir + "/" + newFileName;

            // 上传文件到OSS
            ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content));

            // 构建公开访问URL（格式：https://bucketName.endpoint/objectName）
            return String.format("https://%s.%s/%s", bucketName, endpoint.replace("https://", ""), objectName);
        } finally {
            // 关闭OSS客户端，释放资源
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

OSS 文件服务实现类OssSysServiceImpl.java

实现 ISysFileService 接口，适配 MultipartFile 类型文件上传，调用 AliyunOSSProperties 获取配置，完成文件上传逻辑。

java 复制代码

package com.manage.file.service;

import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.manage.file.utils.AliyunOSSProperties;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.web.multipart.MultipartFile;

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.util.UUID;

/**
 * 阿里云OSS文件上传服务实现类
 */
@Service
public class OssSysServiceImpl implements ISysFileService {
    @Autowired
    private AliyunOSSProperties aliyunOSSProperties;

    @Override
    public String uploadFile(MultipartFile file) throws Exception {
        // 校验文件是否为空
        if (file == null || file.isEmpty()) {
            throw new IllegalArgumentException("上传文件不能为空");
        }

        // 1. 获取OSS配置参数
        String endpoint = aliyunOSSProperties.getEndpoint();
        String bucketName = aliyunOSSProperties.getBucketName();
        String accessKeyId = aliyunOSSProperties.getAccessKeyId();
        String accessKeySecret = aliyunOSSProperties.getAccessKeySecret();

        // 2. 构建OSS客户端（使用OSSClientBuilder）
        OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

        try {
            // 3. 处理文件名与存储路径
            String originalFilename = file.getOriginalFilename();
            String ext = "";
            // 获取文件后缀
            if (originalFilename != null && originalFilename.contains(".")) {
                ext = originalFilename.substring(originalFilename.lastIndexOf("."));
            }
            // 生成唯一文件名（UUID去除横杠）
            String fileName = UUID.randomUUID().toString().replace("-", "") + ext;
            // 按日期分目录存储
            String dir = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM"));
            String objectName = dir + "/" + fileName;

            // 4. 上传文件到OSS（通过文件输入流上传）
            ossClient.putObject(bucketName, objectName, file.getInputStream());

            // 5. 构建并返回公开访问URL
            String host = endpoint.startsWith("https://") ? endpoint.substring(8) :
                          endpoint.startsWith("http://") ? endpoint.substring(7) : endpoint;
            return "https://" + bucketName + "." + host + "/" + objectName;
        } finally {
            // 关闭客户端，释放资源
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

配置默认文件服务

java 复制代码

package com.manage.file.config;

import com.manage.file.service.ISysFileService;
import com.manage.file.service.OssSysServiceImpl;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;

/**
 * 默认文件服务配置
 * 指定OSS作为系统默认文件上传服务
 */
@Configuration
public class DefaultFileServiceConfig {
    @Bean
    @Primary
    public ISysFileService defaultFileService(OssSysServiceImpl ossSysService) {
        return ossSysService;
    }
}

编写文件上传控制器

修改 SysFileController.java，提供文件上传接口，接收前端 MultipartFile 类型文件，调用 OSS 服务完成上传并返回结果。

java 复制代码

package com.manage.file.controller;

import com.manage.common.core.domain.R;
import com.manage.common.core.utils.file.FileUtils;
import com.manage.file.service.ISysFileService;
import com.manage.file.service.OssSysServiceImpl;
import com.manage.system.api.domain.SysFile;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

/**
 * 文件上传控制器
 * 提供文件上传接口，对接前端上传请求
 */
@RestController
public class SysFileController {
    private static final Logger log = LoggerFactory.getLogger(SysFileController.class);

    @Autowired
    private OssSysServiceImpl ossSysService;

    /**
     * 文件上传接口
     * @param file 前端上传的文件
     * @return R<SysFile> 响应结果（包含文件名称和访问URL）
     */
    @PostMapping("upload")
    public R<SysFile> ossupload(MultipartFile file) {
        try {
            // 调用OSS服务上传文件，获取访问URL
            String url = ossSysService.uploadFile(file);
            // 构建返回结果
            SysFile sysFile = new SysFile();
            sysFile.setName(FileUtils.getName(url)); // 从URL中提取文件名
            sysFile.setUrl(url); // 设置文件访问URL
            return R.ok(sysFile); // 返回成功响应
        } catch (Exception e) {
            // 打印异常日志，返回失败响应
            log.error("文件上传失败", e);
            return R.fail(e.getMessage());
        }
    }
}

配置 Nacos 参数

在ry-file-dev.yml

复制代码

aliyun:
  oss:
    endpoint: oss-cn-hangzhou.aliyuncs.com # 替换为你的OSS Endpoint
    bucketName: your-bucket-name # 替换为你的Bucket名称
    region: cn-hangzhou # 替换为你的Bucket地域
    accessKeyId: your-access-key-id # 替换为你的AccessKeyId
    accessKeySecret: your-access-key-secret # 替换为你的AccessKeySecret

依赖配置（pom.xml）

复制代码

        <dependency>
            <groupId>com.aliyun.oss</groupId>
            <artifactId>aliyun-sdk-oss</artifactId>
            <version>3.17.4</version>
        </dependency>

总结

本文详细梳理了若依微服务版集成阿里云 OSS 的全流程，从前期资源准备到最终代码落地、配置验证，核心是通过封装 OSS 配置、实现文件服务接口、指定默认服务这三步，让若依框架无缝对接阿里云对象存储，实现文件的安全上传和公开访问。现将核心要点和落地关键总结如下：

核心流程复盘

前期准备是基础：需完成阿里云 OSS Bucket 创建、AccessKey 获取、Endpoint 确认，同时确保项目环境满足 JDK 1.8+、Maven 3.6 + 的要求，避免后续集成出现环境兼容问题。

代码实现是核心：通过AliyunOSSProperties绑定 Nacos 配置，OssSysServiceImpl实现若依默认ISysFileService接口，DefaultFileServiceConfig指定 OSS 为默认文件服务，最终通过SysFileController对外提供上传接口，形成完整的文件上传链路。

配置与验证是关键：在 Nacos 中配置 OSS 相关敏感参数（避免硬编码），引入阿里云 OSS SDK 依赖，最后通过 Postman 调用上传接口并验证文件访问 URL，确保整个集成流程落地生效。

关键注意事项提炼

安全优先：AccessKeyId/AccessKeySecret 是敏感信息，必须通过 Nacos 配置中心管理，生产环境建议使用 RAM 子账号并最小化授权（仅开放 OSS 相关操作权限），降低密钥泄露风险。

资源不泄漏：OSS 客户端使用完毕后必须调用shutdown()方法关闭，避免长期占用连接资源导致服务异常。

避免文件覆盖：通过「UUID + 日期目录」的方式构建文件存储路径，既保证了文件名唯一性，也方便后续对 OSS 中的文件进行分类管理和排查。

依赖版本兼容：本文使用3.17.4版本的阿里云 OSS SDK，落地时可根据项目 Spring Boot/Spring Cloud 版本选择兼容的 SDK 稳定版，避免版本冲突。