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

核心规则

• - 客户端是线程安全的 — 可在多个线程间共享，无需同步。
• 使用单例模式 — 不要为每个请求创建新的客户端实例。频繁调用 new Client() 会浪费资源并影响性能。
• 优先使用 显式端点 而非基于区域解析端点。
• 预览版本

推荐的客户端创建方式

java
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(ALIBABACLOUDACCESSKEYID))
.setAccessKeySecret(System.getenv(ALIBABACLOUDACCESSKEYSECRET));
config.setEndpoint(ecs.cn-hangzhou.aliyuncs.com);
instance = new com.aliyun.ecs20140526.Client(config);
}
}
}
return instance;
}
}

端点配置

优先级：显式 endpoint > 通过 regionId 进行区域解析。

java
// 推荐：显式端点
config.setEndpoint(ecs.cn-hangzhou.aliyuncs.com);

// 备选：SDK 从区域解析端点
config.setRegionId(cn-hangzhou);

VPC 端点

在阿里云 VPC 内部运行时（混合云、专线、多区域），使用 VPC 端点：

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

文件上传 API（高级）

对于文件上传 API（例如视觉智能），将 regionId 和 endpoint 设置为同一区域。否则可能因跨区域 OSS 访问而出现超时：

java
config.setRegionId(cn-shanghai);
config.setEndpoint(objectdet.cn-shanghai.aliyuncs.com);
// 对于 VPC 文件上传授权：
client._openPlatformEndpoint = openplatform-vpc.cn-shanghai.aliyuncs.com;

同步 vs 异步

异步示例：

java
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();