Java SDK V1到V2迁移指南

确定 region 与 endpoint

region 在所有场景下均为必选，取值为 Bucket 所在地域；endpoint 是否保留取决于访问场景。默认路径是仅设置 region、不传 endpoint，由 region 推导访问域名。

替换客户端创建代码

V1 需要构造凭证提供者与客户端配置对象，并显式声明 V4 签名。以下 V1 示例采用 OSSClientBuilder.create() 链式写法，使用 new OSSClientBuilder().build(endpoint, ak, sk) 的存量代码迁移后同样收敛为下面的 V2 写法。示例代码中的 <region-id> 替换为 Bucket 归属的地域，如cn-hangzhou；<endpoint> 替换为该 Bucket 的访问域名，V1 要求该参数必填。

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;

String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
String region = "<region-id>";
String endpoint = "<endpoint>";

DefaultCredentialProvider provider = new DefaultCredentialProvider(accessKeyId, accessKeySecret);

ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
// V1 需要显式声明使用 V4 签名算法
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);

OSS ossClient = OSSClientBuilder.create()
        .credentialsProvider(provider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)
        .endpoint(endpoint)
        .build();

// 执行 OSS 操作...

ossClient.shutdown();

V2 通过静态工厂创建客户端，region 必选、默认使用 V4 签名，endpoint 仅在上表列出的场景下才需要指定。OSSClient 实现了 AutoCloseable，使用 try-with-resources 可自动释放资源：

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;

CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

try (OSSClient client = OSSClient.newBuilder()
        .credentialsProvider(provider)
        .region("<region-id>")
        .build()) {

    // 执行 OSS 操作...

}

凭证提供者的类型名称按第二步的映射关系替换。上面的 V2 示例使用 EnvironmentVariableCredentialsProvider 直接从环境变量读取凭证，凭证来源与 V1 示例先读取环境变量再包装为 DefaultCredentialProvider 一致；如需由代码显式传入 AccessKey，改用 StaticCredentialsProvider。

客户端的创建和销毁开销较大，高频调用场景下应复用同一实例。

迁移客户端配置项与重试策略

V1 通过 ClientConfiguration／ClientBuilderConfiguration 对象设置超时、重试、代理等参数；V2 将这些参数上移为 OSSClient.newBuilder() 的链式方法，如 connectTimeout、readWriteTimeout、retryMaxAttempts、retryer、proxyHost、useCName、useInternalEndpoint、useAccelerateEndpoint、disableSsl、usePathStyle。完整配置项参见 V2 SDK 文档的客户端配置章节。

重试属于可选调优项：V2 默认使用 StandardRetryer，最大尝试次数为 3 次，最大退避时间 20 秒，基础延迟 0.2 秒，采用 FullJitter 退避算法。需要调整时通过 StandardRetryer.newBuilder() 构造自定义 Retryer 并传入 retryer(...)；需要关闭重试时传入 NopRetryer。

可选：改用异步客户端

如果业务需要并发执行多个互不依赖的操作，可改用异步客户端，操作返回 CompletableFuture：

import com.aliyun.sdk.service.oss2.OSSAsyncClient;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

import java.util.concurrent.CompletableFuture;

try (OSSAsyncClient client = OSSAsyncClient.newBuilder()
        .credentialsProvider(new EnvironmentVariableCredentialsProvider())
        .region("<region-id>")
        .build()) {

    CompletableFuture<ListBucketsResult> future = client.listBucketsAsync(
            ListBucketsRequest.newBuilder().build());

    future.thenAccept(result -> {
        for (BucketSummary info : result.buckets()) {
            System.out.printf("bucket: name:%s, region:%s%n", info.name(), info.region());
        }
    });

    future.join();
}