Client Initialization Best Practices (Java)#

Core Rules#

• Client is thread-safe — safe to share across threads without synchronization.
• Use singleton pattern — do NOT create new client instances per request. Frequent new Client() calls waste resources and hurt performance.
• Prefer explicit endpoint over region-based endpoint resolution.
• preview version

Recommended Client Creation#

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("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 Configuration#

Priority: explicit endpoint > region-based resolution via regionId.

java

// Preferred: explicit endpoint
config.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");

// Alternative: SDK resolves endpoint from region
config.setRegionId("cn-hangzhou");

VPC Endpoints#

Use VPC endpoints when running inside Alibaba Cloud VPC (hybrid cloud, leased lines, multi-region):

java

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

File Upload APIs (Advance)#

For file upload APIs (e.g., Visual Intelligence), set both regionId and endpoint to the same region. Otherwise you may see timeouts due to cross-region OSS access:

java

config.setRegionId("cn-shanghai");
config.setEndpoint("objectdet.cn-shanghai.aliyuncs.com");
// For VPC file upload authorization:
client._openPlatformEndpoint = "openplatform-vpc.cn-shanghai.aliyuncs.com";

Synchronous vs Asynchronous#

ModeSDK ArtifactWhen to UseSynchronouscom.aliyun:{productCode}{version}Simple flows, low concurrency, easier debuggingAsynchronouscom.aliyun:alibabacloud-{productCode}{version}High concurrency/throughput, non-blocking I/O

Async example:

java

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

CompletableFuture<DescribeRegionsResponse> response = client.describeRegions(request);
response.thenAccept(resp -> System.out.println(new Gson().toJson(resp)))
    .exceptionally(throwable -> { System.out.println(throwable.getMessage()); return null; });
// Always close async client when done
client.close();