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

核心规则

• Client 是 goroutine 安全的 — 可在多个 goroutine 间安全共享，无需额外同步机制。
• 使用单例模式 — 切勿为每次请求创建新的 client 实例。频繁创建 client 会浪费资源。
• 优先使用 显式 endpoint，而非基于 region 的 endpoint 自动解析。

推荐的 Client 创建方式

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 配置

优先级：显式指定 Endpoint > 通过 RegionId 自动解析 endpoint。

// 推荐：显式指定 endpoint
config.Endpoint = tea.String("ecs.cn-hangzhou.aliyuncs.com")

// 备选：由 SDK 基于 region 自动解析 endpoint
config.RegionId = tea.String("cn-hangzhou")

VPC Endpoint

当运行在阿里云 VPC 内时，请使用 VPC endpoint：

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

文件上传类 API（进阶）

对于文件上传类 API，需 同时设置 RegionId 和 Endpoint 为同一地域：

config.RegionId = tea.String("cn-shanghai")
config.Endpoint = tea.String("objectdet.cn-shanghai.aliyuncs.com")
// VPC 文件上传授权配置：
client.OpenPlatformEndpoint = tea.String("openplatform-vpc.cn-shanghai.aliyuncs.com")
client.EndpointType = tea.String("internal")

SDK 组件说明

调试

通过环境变量启用 debug 模式，可输出所有请求日志：

export DEBUG=tea