一个面向 Spring Boot 3 的阿里云 OSS 自定义 Starter，用于简化 OSS 文件上传功能的依赖引入和 Bean 配置。

业务项目引入本 Starter 后，只需要配置 OSS 基本信息和访问凭证，即可直接注入 AliyunOSSOperator 完成文件上传。

• 基于 Spring Boot 自动配置机制创建 AliyunOSSOperator
• 通过 application.yml 统一配置 Endpoint、Bucket 和 Region
• 从环境变量读取阿里云访问凭证，避免将密钥写入代码
• 上传文件时按 yyyy/MM 自动生成存储目录
• 使用 UUID 生成文件名，降低文件重名风险
• Starter 与自动配置模块分离，业务项目只需引入一个依赖

• JDK 17 或更高版本
• Maven 3.6 或更高版本
• Spring Boot 3.x，推荐使用 Spring Boot 3.2.x
• 已创建阿里云 OSS Bucket
• 已准备具有 OSS 操作权限的 AccessKey

aliyun-oss-starter
├── pom.xml
├── aliyun-oss-spring-boot-starter
│   └── pom.xml
└── aliyun-oss-spring-boot-autoconfigure
    ├── pom.xml
    └── src/main
        ├── java/com/aliyun/oss
        │   ├── AliyunOSSAutoConfiguration.java
        │   ├── AliyunOSSOperator.java
        │   └── AliyunOSSProperties.java
        └── resources/META-INF/spring
            └── org.springframework.boot.autoconfigure.AutoConfiguration.imports

两个 Maven 模块的职责如下：

本项目目前是本地 Starter，尚未发布到公共 Maven 仓库。其他开发者首次使用时，需要先下载源码并安装到自己的 Maven 本地仓库。

使用 Git 克隆仓库：

git clone <本项目的 GitHub 仓库地址>
cd aliyun-oss-starter

也可以在 GitHub 页面选择 Code -> Download ZIP，下载并解压后进入包含最外层 pom.xml 的目录。

在项目根目录执行：

mvn clean install

出现以下信息表示安装成功：

BUILD SUCCESS

该命令会编译两个模块，并将对应的 JAR 和 POM 安装到当前用户的 Maven 本地仓库。两个源码文件夹不需要复制到业务项目中。

如果电脑没有配置 Maven 命令，也可以使用 IntelliJ IDEA 打开本项目，在 Maven 工具窗口中执行根项目的 Lifecycle -> install。

在业务项目的 pom.xml 中添加：

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-oss-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

只需要引入 aliyun-oss-spring-boot-starter。Maven 会自动传递引入 aliyun-oss-spring-boot-autoconfigure，不需要重复声明。

添加依赖后，请在 IDEA 中重新加载 Maven 项目。

在业务项目的 application.yml 中添加：

aliyun:
  oss:
    endpoint: https://oss-cn-hangzhou.aliyuncs.com
    bucket-name: your-bucket-name
    region: cn-hangzhou

请根据自己的 Bucket 所在地域修改配置。

当前实现通过阿里云 SDK 从环境变量读取访问凭证：

OSS_ACCESS_KEY_ID
OSS_ACCESS_KEY_SECRET

以 Windows 系统为例，建议直接通过“此电脑”配置环境变量：

1. 右键单击“此电脑”，选择“属性”。
2. 点击“高级系统设置”。
3. 在“高级”选项卡中点击“环境变量”。
4. 在“用户变量”区域点击“新建”，依次添加下面两个环境变量。

保存配置后，需要重新启动 IntelliJ IDEA 和正在运行的应用，使新环境变量生效。

不要将 AccessKey 写入源码、提交到 GitHub，或者直接公开在 application.yml 中。

Starter 会自动创建 AliyunOSSOperator Bean，可以使用 @Autowired 注入后直接调用：

import com.aliyun.oss.AliyunOSSOperator;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class FileStorageService {

    @Autowired
    private AliyunOSSOperator aliyunOSSOperator;

    public String upload(byte[] content, String originalFilename) throws Exception {
        return aliyunOSSOperator.upload(content, originalFilename);
    }
}

如果业务项目已经引入 spring-boot-starter-web，可以通过 MultipartFile 接收文件：

import com.aliyun.oss.AliyunOSSOperator;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

@RestController
@RequestMapping("/files")
public class FileController {

    @Autowired
    private AliyunOSSOperator aliyunOSSOperator;

    @PostMapping("/upload")
    public String upload(@RequestParam("file") MultipartFile file) throws Exception {
        return aliyunOSSOperator.upload(
                file.getBytes(),
                file.getOriginalFilename()
        );
    }
}

启动业务项目后，发送 multipart/form-data 请求：

POST /files/upload
表单参数名：file

上传流程如下：

接收文件
  -> 按 yyyy/MM 生成目录
  -> 使用 UUID 生成新文件名
  -> 上传至指定 OSS Bucket
  -> 返回文件的 OSS 地址

业务项目引入 Starter 后，Spring Boot 会读取：

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

并加载 AliyunOSSAutoConfiguration。该配置类会：

1. 将 aliyun.oss 下的配置绑定到 AliyunOSSProperties。
2. 自动创建 AliyunOSSOperator。
3. 当业务项目已经自行声明 AliyunOSSOperator Bean 时，不再重复创建。

因此，业务项目不需要手动扫描 Starter 包，也不需要编写额外的 @Bean 配置。

错误信息通常类似：

Could not find artifact com.aliyun.oss:aliyun-oss-spring-boot-starter

请检查：

1. 是否已经在 Starter 根目录执行 mvn clean install。
2. 安装过程是否显示 BUILD SUCCESS。
3. 业务项目使用的版本是否为 0.0.1-SNAPSHOT。
4. IDEA 是否已经重新加载 Maven 项目。

请检查：

1. 业务项目是否引入了 aliyun-oss-spring-boot-starter。
2. Maven 依赖中是否包含 aliyun-oss-spring-boot-autoconfigure。
3. 业务项目是否使用 Spring Boot 3.x 和 JDK 17。
4. 是否存在依赖下载或项目编译错误。

请确认：

• OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET 已设置。
• 环境变量名称完全一致，没有多余空格。
• 设置环境变量后已经重新启动应用。
• AccessKey 仍然有效，并且具有目标 Bucket 的操作权限。

如果 Bucket 是私有读权限，普通 OSS 地址不能直接匿名访问。此时需要使用签名 URL，或者根据实际安全需求调整 Bucket 访问权限。

当前实现会保留原文件扩展名，因此上传时应提供包含扩展名的文件名，例如：

avatar.png
document.pdf

建议业务项目在调用上传方法前，对空文件、空文件名、文件类型和文件大小进行校验。

• 优先使用 RAM 用户的 AccessKey，不要使用阿里云主账号 AccessKey。
• 按照最小权限原则，仅授予应用所需的 Bucket 操作权限。
• 不要在 GitHub、日志或接口响应中暴露 AccessKey。
• 生产环境建议由配置中心、密钥管理服务或部署平台管理环境变量。
• 文件上传前应校验文件类型、大小和文件名，避免上传不符合预期的内容。

当 Starter 源码或版本发生变化时，使用者需要重新拉取代码并安装：

git pull
mvn clean install

随后在业务项目中重新加载 Maven 依赖。如果发布了新的版本号，还需要同步修改业务项目中的依赖版本。

本项目不是阿里云官方组件，与阿里云官方无隶属或合作关系。

本插件仅用于方便个人开发，并用作学习交流用途。使用者应自行评估代码的适用性、安全性和稳定性，并遵守阿里云 OSS 的相关服务条款及安全规范。