客户端初始化最佳实践（Java）

核心规则

• 客户端是线程安全的 — 可在多线程间共享使用，无需额外同步。
• 采用单例模式 — 切勿为每次请求创建新的 Client 实例。频繁调用 new Client() 会浪费资源并降低性能。
• 优先使用 显式 endpoint，而非基于 region 的 endpoint 自动解析。
• 预览版本

推荐的客户端创建方式

public class ClientFactory {
    private static volatile com.aliyun.ecs20140526.Client instance;

    public static com.aliyun.ecs20140526.Client getInstance() throws Exception {
        if (instance == null) {
            synchronized (ClientFactory.class) {
                if (instance == null) {
                    com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                        .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                        .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
                    config.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
                    instance = new com.aliyun.ecs20140526.Client(config);
                }
            }
        }
        return instance;
    }
}

Endpoint 配置

配置优先级：显式指定 endpoint > 通过 regionId 自动解析 endpoint。

// 推荐：显式指定 endpoint
config.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");

// 备选：由 SDK 根据 regionId 自动解析 endpoint
config.setRegionId("cn-hangzhou");

VPC Endpoint

当运行在阿里云 VPC 内（混合云、专线、多地域场景）时，请使用 VPC Endpoint：

config.setEndpoint("ecs-vpc.cn-hangzhou.aliyuncs.com");

文件上传类 API（进阶）

对于文件上传类 API（例如 Visual Intelligence），需同时设置 regionId 和 endpoint 为同一地域。否则可能因跨地域访问 OSS 导致超时：

config.setRegionId("cn-shanghai");
config.setEndpoint("objectdet.cn-shanghai.aliyuncs.com");
// VPC 环境下文件上传授权使用的 endpoint：
client._openPlatformEndpoint = "openplatform-vpc.cn-shanghai.aliyuncs.com";

同步 vs 异步

异步调用示例：

AsyncClient client = AsyncClient.builder()
    .region("cn-hangzhou")
    .credentialsProvider(provider)
    .overrideConfiguration(ClientOverrideConfiguration.create()
        .setEndpointOverride("ecs.cn-chengdu.aliyuncs.com"))
    .build();

CompletableFuture response = client.describeRegions(request);
response.thenAccept(resp -> System.out.println(new Gson().toJson(resp)))
    .exceptionally(throwable -> { System.out.println(throwable.getMessage()); return null; });
// 使用完毕后务必关闭异步客户端
client.close();