Client Initialization Best Practices (Go)#

Core Rules#

• Client is goroutine-safe — safe to share across goroutines without additional synchronization.
• Use singleton pattern — do NOT create new client instances per request. Frequent client creation wastes resources.
• Prefer explicit endpoint over region-based endpoint resolution.

Recommended Client Creation#

go

import (
    "os"
    "sync"

    openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
    ecs "github.com/alibabacloud-go/ecs-20140526/v3/client"
    "github.com/alibabacloud-go/tea/tea"
)

var (
    ecsClient     *ecs.Client
    ecsClientOnce sync.Once
)

func GetEcsClient() *ecs.Client {
    ecsClientOnce.Do(func() {
        config := &openapi.Config{
            AccessKeyId:     tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")),
            AccessKeySecret: tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")),
            Endpoint:        tea.String("ecs.cn-hangzhou.aliyuncs.com"),
        }
        var err error
        ecsClient, err = ecs.NewClient(config)
        if err != nil {
            panic(err)
        }
    })
    return ecsClient
}

Endpoint Configuration#

Priority: explicit Endpoint > region-based resolution via RegionId.

go

// Preferred: explicit endpoint
config.Endpoint = tea.String("ecs.cn-hangzhou.aliyuncs.com")

// Alternative: SDK resolves endpoint from region
config.RegionId = tea.String("cn-hangzhou")

VPC Endpoints#

Use VPC endpoints when running inside Alibaba Cloud VPC:

go

config.Endpoint = tea.String("ecs-vpc.cn-hangzhou.aliyuncs.com")

File Upload APIs (Advance)#

Set both RegionId and Endpoint to the same region for file upload APIs:

go

config.RegionId = tea.String("cn-shanghai")
config.Endpoint = tea.String("objectdet.cn-shanghai.aliyuncs.com")
// VPC file upload authorization:
client.OpenPlatformEndpoint = tea.String("openplatform-vpc.cn-shanghai.aliyuncs.com")
client.EndpointType = tea.String("internal")

SDK Components#

ComponentDescriptionCore SDK ( darabonba-openapi)Generic calls, no product dependencyProduct SDK (e.g., ecs-20140526)Typed client, models, convenience methods

Debugging#

Enable debug mode via environment variable to log all requests:

bash

export DEBUG=tea