上传文件到阿里云 OSS

本文介绍通过 AliyunOssUtils 将字节数组或本地文件上传到阿里云 OSS。工具类位于 nexus.io.tio.boot.admin.utils.storage，封装 OSS SDK 的客户端创建和上传操作。

应用的统一上传接口、文件信息落库及下载接口见 tio-boot-admin：文件上传。

1. 添加 SDK 依赖

在已经依赖 tio-boot-admin 的应用中显式加入 OSS SDK，确保运行时可以加载 SDK 类型。

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

2. 配置阿里云 OSS

OSS_ACCESS_KEY_ID=your_access_key_id
OSS_ACCESS_KEY_SECRET=your_access_key_secret
OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
OSS_REGION_NAME=cn-hangzhou
OSS_BUCKET_NAME=your_bucket_name

Endpoint 和 Region 必须与 Bucket 对应，凭据需要具备该 Bucket 的对象写入权限。密钥放在应用加载的本地 .env 或部署环境变量中，不提交版本库。先加载配置，再调用工具类；修改配置后重启应用。

AliyunOssUtils 根据这些参数创建共享 OSS 客户端，使用 V4 签名。

3. 上传字节数组

import java.nio.charset.StandardCharsets;
import com.aliyun.oss.model.PutObjectResult;
import nexus.io.tio.boot.admin.utils.storage.AliyunOssUtils;

byte[] content = "Hello OSS".getBytes(StandardCharsets.UTF_8);
String objectKey = "uploads/example.txt";
String suffix = "txt";

PutObjectResult result = AliyunOssUtils.upload(objectKey, content, suffix);
String etag = result.getETag();

objectKey 是 Bucket 内的完整对象路径，uploads/ 是对象名称前缀，不需要提前创建目录。suffix 不含点，工具类用它设置 Content-Type，并根据字节数组长度设置 Content-Length。

以上方法使用配置中的 Bucket；也可以显式指定 Bucket：

PutObjectResult result = AliyunOssUtils.upload("your_bucket_name", objectKey, content, suffix);

显式指定的 Bucket 应与当前客户端的 Endpoint、Region 和凭据权限匹配。

4. 上传本地文件

import java.io.File;
import com.aliyun.oss.model.PutObjectResult;
import nexus.io.tio.boot.admin.utils.storage.AliyunOssUtils;

File file = new File("example.txt");
String objectKey = "uploads/example.txt";
PutObjectResult result = AliyunOssUtils.upload(objectKey, file);
String etag = result.getETag();

本地路径相对于应用工作目录，也可以使用绝对路径。工具类根据本地文件名后缀设置 Content-Type，根据文件长度设置 Content-Length。文件需要存在并且可读。

显式指定 Bucket 的重载为：

PutObjectResult result = AliyunOssUtils.upload("your_bucket_name", objectKey, file);

5. 上传结果与客户端生命周期

上传成功返回 PutObjectResult，可取得 ETag。ETag 是 OSS 返回的对象标识，不能在所有上传模式下都当作文件 MD5 使用。上传失败会抛出异常，应交给应用统一异常处理。

使用唯一的 objectKey 可以避免覆盖同名对象。上传后可以在 OSS 控制台对应 Bucket 中按对象路径核对内容长度和 Content-Type。

AliyunOssUtils 的上传方法复用共享客户端，不要在每次上传之后调用 shutdown()。在应用退出时注册关闭操作：

import nexus.io.hook.HookCan;
import nexus.io.tio.boot.admin.utils.storage.AliyunOssUtils;

HookCan.me().addDestroyMethod(AliyunOssUtils::shutdown);

该关闭钩子在应用配置阶段注册一次即可。