OSS Kotlin SDK V2（预览版）

环境准备

• Kotlin：2.1.0 及以上版本

• Java：运行时需要 Java 8+（从源码构建需要 Java 11+）

• 支持平台：JVM（Desktop / Server）、Android、JavaScript（Node.js、Browser）、WebAssembly（wasmJs：Node.js、Browser）、iOS（iosArm64、iosSimulatorArm64）和 macOS（macosArm64）

通过项目的 build.gradle.kts 文件查看 Kotlin 版本。如果当前环境没有 Kotlin 或版本过低，请升级您的 Kotlin 版本。

安装SDK

建议使用 Gradle 方式安装 OSS Kotlin SDK V2。

方式一：Gradle 依赖（推荐）

在 build.gradle.kts 添加依赖：

dependencies {
    implementation("com.aliyun:kotlin-oss-v2:<latest-version>")

    // 如需扩展功能（如跨域资源共享接口）
    // implementation("com.aliyun:kotlin-oss-v2-extension:0.1.0-dev")
}

包说明：

• kotlin-oss-v2：提供 Bucket 基础接口、对象类接口和高级接口（分页器、预签名）

• kotlin-oss-v2-extension：包含存储空间配置类接口，例如跨域资源共享、日志转存、存储空间清单和图片样式

方式二：从源码构建

从 Github获取最新版本的 OSS Kotlin SDK V2，并通过 Gradle 构建和安装：

# clone工程
$ git clone https://github.com/aliyun/alibabacloud-oss-kotlin-sdk-v2.git

# 进入目录
$ cd alibabacloud-oss-kotlin-sdk-v2/

# 发布到 MavenLocal
$ ./gradlew clean publishToMavenLocal

添加 mavenLocal 到仓库配置：

repositories {
    ...
    mavenLocal()
}

添加依赖到你的项目中

implementation("com.aliyun:kotlin-oss-v2:<latest-version>")
// implementation("com.aliyun:kotlin-oss-v2-extension:<latest-version>")

方式三：手动引入依赖包

# clone工程
$ git clone https://github.com/aliyun/alibabacloud-oss-kotlin-sdk-v2.git

# 进入目录
$ cd aliyun-oss-kotlin-sdk-v2/

# 执行打包脚本
$ ./gradlew :oss-sdk:assemble
# ./gradlew :oss-sdk-extension:assemble

# 以aar为例
# 进入打包生成目录，包生成在该目录下
$ cd oss-sdk/build/outputs/aar && ls
# cd oss-sdk-extension/build/outputs/aar && ls

配置访问凭证

将 RAM 用户的 AccessKey 写入环境变量作为凭证。

在 RAM 控制台，创建 使用永久 AccessKey 访问 的 RAM 用户，保存 AccessKey，然后为该用户授予 AliyunOSSFullAccess 权限。

初始化客户端

使用地域和Endpoint初始化 OSSClient。

• OSSClient 实现了 Closeable 接口，使用 use 扩展函数时会自动释放资源，无需手动调用 close。

• OSSClient 创建和销毁是耗时的，可采用单例模式复用 OSSClient，但应用终止前必须手动调用 close，否则资源会泄漏。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider
import com.aliyun.kotlin.sdk.service.oss2.models.ListBucketsRequest
import com.aliyun.kotlin.sdk.service.oss2.paginator.listBucketsPaginator

suspend fun main() {
    val region = "cn-hangzhou"

    // 使用SDK默认配置
    // 从环境变量中加载凭证信息
    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // 使用分页器列举所有Bucket
        client.listBucketsPaginator(ListBucketsRequest {}).collect { result ->
            result.buckets?.forEach { bucket ->
                println("bucket: name:${bucket.name}, region:${bucket.region}, storageClass:${bucket.storageClass}")
            }
        }
    }
}

运行后将会看到当前账号在所有地域下的 Bucket：

bucket: name: examplebucket01, region: cn-hangzhou, storageClass: Standard
bucket: name: examplebucket02, region: cn-hangzhou, storageClass: Standard

使用自定义域名

使用 OSS 默认域名访问时，可能会出现文件禁止访问、文件无法预览等问题；通过自定义域名访问 OSS，不仅支持浏览器直接预览文件，还可结合 CDN 加速分发。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 填写 Bucket 所在地域。以华东1（杭州）为例，Region 填写为 cn-hangzhou
    val region = "cn-hangzhou"
    
    // 请填写您的自定义域名。例如 www.example-***.com
    val endpoint = "https://www.example-***.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        this.endpoint = endpoint
        // 请注意，设置 true 开启 CNAME 选项，否则无法使用自定义域名
        this.useCName = true
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

超时控制

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider
import kotlin.time.Duration.Companion.seconds

suspend fun main() {
    val region = "cn-hangzhou"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        // 设置建立连接的超时时间, 默认值 10 秒
        connectTimeout = 30.seconds
        // 设置应用读写数据的超时时间, 默认值 20 秒
        readWriteTimeout = 30.seconds
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

重试策略

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider
import com.aliyun.kotlin.sdk.service.oss2.retry.StandardRetryer
import com.aliyun.kotlin.sdk.service.oss2.retry.FullJitterBackoff
import com.aliyun.kotlin.sdk.service.oss2.retry.FixedDelayBackoff
import com.aliyun.kotlin.sdk.service.oss2.retry.NopRetryer
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds

suspend fun main() {
    /*
     * SDK 重试策略配置说明：
     *
     * 默认重试策略：
     * 当没有配置重试策略时，SDK 使用 StandardRetryer 作为客户端的默认实现，其默认配置如下：
     * - maxAttempts：设置最大尝试次数。默认为 3 次
     * - maxBackoff：设置最大退避时间。默认为 20 秒
     * - baseDelay：设置基础延迟时间。默认为 200 毫秒
     * - backoffDelayer：设置退避算法。默认使用 FullJitter 退避算法
     *   计算公式为：[0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff)
     * - errorRetryable：可重试的错误类型，包括 HTTP 状态码、服务错误码、客户端错误等
     *
     * 当发生可重试错误时，将使用其提供的配置来延迟并随后重试该请求。
     * 请求的总体延迟会随着重试次数而增加，如果默认配置不满足您的场景需求时，
     * 可配置重试参数或者修改重试实现。
     */

    val region = "cn-hangzhou"

    // 配置重试策略示例：

    // 1. 自定义最大重试次数（默认为 3 次，这里设置为 5 次）
    val customRetryer = StandardRetryer.newBuilder()
        .setMaxAttempts(5)
        .build()

    // 2. 自定义退避延迟时间
    // 调整基础延迟时间 baseDelay 为 500 毫秒（默认 200 毫秒），最大退避时间 maxBackoff 为 25 秒（默认 20 秒）
    // val customRetryer = StandardRetryer.newBuilder()
    //     .setBackoffDelayer(FullJitterBackoff(500.milliseconds, 25.seconds))
    //     .build()

    // 3. 自定义退避算法
    // 使用固定时间退避算法替代默认的 FullJitter 算法，每次延迟 2 秒
    // val customRetryer = StandardRetryer.newBuilder()
    //     .setBackoffDelayer(FixedDelayBackoff(2.seconds))
    //     .build()

    // 4. 禁用重试策略
    // 如需禁用所有重试尝试时，可以使用 NopRetryer 实现
    // val customRetryer = NopRetryer()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        retryer = customRetryer
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

HTTP/HTTPS 协议

使用 disableSsl = true 设置不使用 HTTPS 协议。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    val region = "cn-hangzhou"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        // 设置不使用 https 请求
        disableSsl = true
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

使用内网域名

使用内网域名访问同地域的 OSS 资源，可以降低流量成本并提高访问速度。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 方式一：填写 Region 并设置 useInternalEndpoint 为 true
    val region = "cn-hangzhou"

    // 方式二：直接填写 Region 和 Endpoint
    // val region = "cn-hangzhou"
    // val endpoint = "oss-cn-hangzhou-internal.aliyuncs.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        useInternalEndpoint = true
        // 如果使用方式二，取消注释下一行并注释上一行
        // this.endpoint = endpoint
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

使用传输加速域名

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 方式一：填写 Region 并设置 useAccelerateEndpoint 为 true
    val region = "cn-hangzhou"

    // 方式二：直接填写 Region 和传输加速 Endpoint
    // val region = "cn-hangzhou"
    // val endpoint = "https://oss-accelerate.aliyuncs.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        useAccelerateEndpoint = true
        // 如果使用方式二，取消注释下一行并注释上一行
        // this.endpoint = endpoint
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

使用专有域

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    val region = "cn-hangzhou"
    
    // 请填写您的专有域。例如：https://service.corp.example.com
    val endpoint = "https://service.corp.example.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        this.endpoint = endpoint
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

使用金融云域名

以下是使用金融云域名配置 OSSClient 的示例代码。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 填写 Bucket 所在地域。以华东1 金融云为例，Region 填写为 cn-hangzhou-finance
    val region = "cn-hangzhou-finance"
    
    // 填写 Bucket 所在地域对应的内网 Endpoint。以华东1 金融云为例
    // 如需指定为 http 协议，请在指定域名时填写为 'http://oss-cn-hzjbp-a-internal.aliyuncs.com'
    val endpoint = "https://oss-cn-hzjbp-a-internal.aliyuncs.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        this.endpoint = endpoint
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

使用政务云域名

以下是使用政务云域名配置 OSSClient 的示例代码。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 填写 Bucket 所在地域。以华北2 阿里政务云1为例，Region 填写为 cn-north-2-gov-1
    val region = "cn-north-2-gov-1"
    
    // 填写 Bucket 所在地域对应的内网 Endpoint。以华北2 阿里政务云1为例
    // 如需指定为 http 协议，请在指定域名时填写为 'http://oss-cn-north-2-gov-1-internal.aliyuncs.com'
    val endpoint = "https://oss-cn-north-2-gov-1-internal.aliyuncs.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        this.endpoint = endpoint
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

使用RAM用户的AK

如果您的应用程序部署运行在安全、稳定且不易受外部攻击的环境中，需要长期访问您的 OSS，且不能频繁轮转凭证时，您可以使用阿里云主账号或 RAM 用户的 AK（Access Key ID、Access Key Secret）初始化凭证提供者。需要注意的是，该方式需要您手动维护一个 AK，存在安全性风险和维护复杂度增加的风险。

环境变量配置

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

代码示例

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 从环境变量中加载凭证信息，用于身份验证
    val credentialsProvider = EnvironmentVariableCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填写 Bucket 所在地域
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

静态凭证配置

以下示例代码展示了如何对访问凭据直接进行硬编码，显式设置要使用的访问密钥。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.StaticCredentialsProvider

suspend fun main() {
    // 创建静态凭证提供者，显式设置访问密钥
    // 请替换为您的 RAM 用户的 AccessKey ID 和 AccessKey Secret
    val credentialsProvider = StaticCredentialsProvider(
        accessKeyId = "YOUR_ACCESS_KEY_ID",
        accessKeySecret = "YOUR_ACCESS_KEY_SECRET"
    )

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填写 Bucket 所在地域
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

使用STS临时访问凭证

如果您的应用程序需要临时访问 OSS，您可以使用通过 STS 服务获取的临时身份凭证（Access Key ID、Access Key Secret 和 Security Token）初始化凭证提供者。需要注意的是，该方式需要您手动维护一个 STS Token，存在安全性风险和维护复杂度增加的风险。此外，如果您需要多次临时访问 OSS，您需要手动刷新 STS Token。

• 请注意，STS Token 在生成的时候需要指定过期时间，过期后自动失效不能再使用。

环境变量配置

export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

代码示例

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 从环境变量中加载访问 OSS 所需的认证信息，用于身份验证
    val credentialsProvider = EnvironmentVariableCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填写 Bucket 所在地域
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

静态凭证配置

以下示例代码展示了如何对访问凭据直接进行硬编码，显式设置要使用的临时访问密钥。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.StaticCredentialsProvider

suspend fun main() {
    // 填写获取的临时访问密钥 AccessKey ID 和 AccessKey Secret
    // 请注意区分 STS 服务获取的 Access Key ID 是以 STS 开头
    val stsAccessKeyId = "STS.****************"
    val stsAccessKeySecret = "yourAccessKeySecret"
    val stsSecurityToken = "yourSecurityToken"

    // 创建静态凭证提供者，显式设置临时访问密钥和 STS 安全令牌
    val credentialsProvider = StaticCredentialsProvider(
        accessKeyId = stsAccessKeyId,
        accessKeySecret = stsAccessKeySecret,
        securityToken = stsSecurityToken
    )

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填写 Bucket 所在地域
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

使用自定义访问凭证

当以上凭证配置方式不满足要求时，您可以自定义获取凭证的方式。Kotlin SDK 支持通过实现 CredentialsProvider 接口来自定义凭证提供者。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.Credentials
import com.aliyun.kotlin.sdk.service.oss2.credentials.CredentialsProvider

class CustomCredentialsProvider : CredentialsProvider {
    
    override suspend fun getCredentials(): Credentials {
        // TODO: 实现您的自定义凭证获取逻辑
        
        // 返回长期凭证
        return Credentials("access_key_id", "access_key_secret")
        
        // 返回 STS 临时凭证（如果需要）
        // 对于临时凭证，需要根据过期时间刷新凭证
        // return Credentials("sts_access_key_id", "sts_access_key_secret", "security_token")
    }
}

suspend fun main() {
    // 创建自定义凭证提供者
    val credentialsProvider = CustomCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填写 Bucket 所在地域
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.CredentialsProvider
import com.aliyun.kotlin.sdk.service.oss2.credentials.RefreshCredentialsProvider
import kotlin.time.Duration.Companion.seconds

suspend fun main() {
    // 您的原始凭证提供者
    val baseProvider: CredentialsProvider = CustomCredentialsProvider()
    
    // 使用 RefreshCredentialsProvider 包装，自动刷新凭证
    // 默认刷新间隔为 300 秒
    val credentialsProvider = RefreshCredentialsProvider(
        provider = baseProvider,
        refreshInterval = 300.seconds
    )

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
    }
}

匿名访问

如果您只需要访问公共读取权限的 OSS 资源，可以使用匿名访问方式，无需提供任何凭证。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.AnonymousCredentialsProvider

suspend fun main() {
    // 创建匿名凭证提供者
    val credentialsProvider = AnonymousCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填写 Bucket 所在地域
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用创建好的 client 执行后续操作...
        // 注意：匿名访问只能访问具有公共读取权限的资源
    }
}

运行 CLI 示例

# 编译项目 
./gradlew :sample:cli:build

# 进入示例程序目录 
cd sample/cli/build/libs/

# 通过环境变量，配置访问凭证
export OSS_ACCESS_KEY_ID="your access key id"
export OSS_ACCESS_KEY_SECRET="your access key secret"

# 以 ListBuckets 为例
java -jar cli-jvm.jar ListBuckets --region cn-hangzhou

运行 UI 示例

> - 运行 `sample.composeApp` 或 `sample[jvm]`
> - 填写 `AccessKeyId`, `AccessKeySecret` 及 `Region`
> - 点击 `Set Client` 完成 client 初始化
> - 以 ListObjects 为例，填写 bucket 名称，点击 `ListObjects`