Go迁移指南_对象存储(OSS)-阿里云帮助中心

本文介绍如何从Go SDK V1版本迁移到Go SDK V2 版本。

最低Go版本

请注意，V2版本要求Go版本最低为1.18。

导入路径

V2版本使用新的代码仓库，同时也对代码结构进行了调整，按照功能模块组织，以下是这些模块路径和说明：

模块路径	说明
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss	SDK核心，基础接口和高级接口实现
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials	访问凭证相关
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/retry	重试相关
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/signer	签名相关
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/transport	HTTP客户端相关
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/crypto	客户端加密相关

V1版示例

import (
  "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

V2版示例

import (
  "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
  "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
  // 根据需要，导入 retry，transport 或者 signer
  //"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/xxxx"
)

配置加载

V2版本简化了配置设置方式，全部迁移到config下，并提供了以With为前缀的辅助函数，方便以编程方式覆盖缺省配置。
V2版本默认使用V4签名，所以必须配置区域（Region）。
V2版本支持从区域（Region）信息构造访问域名（Endpoint），当访问的是公有云时，可以不设置Endpoint。

V1版示例

import (
  "github.com/aliyun/aliyun-oss-go-sdk/oss"
)
...

// 环境变量中获取访问凭证
provider, err := oss.NewEnvironmentVariableCredentialsProvider()

// 设置HTTP连接超时时间为20秒，HTTP读取或写入超时时间为60秒。
time := oss.Timeout(20,60)

// 不校验SSL证书校验
verifySsl := oss.InsecureSkipVerify(true)

// 设置日志
logLevel := oss.SetLogLevel(oss.LogInfo)

// Endpoint
endpoint := "oss-cn-hangzhou.aliyuncs.com"

client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), time, verifySsl, logLevel)

V2版示例

import (
  "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
  "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

...

// 环境变量中获取访问凭证
provider := credentials.NewEnvironmentVariableCredentialsProvider()

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(provider).
  // 设置HTTP连接超时时间为20秒
  WithConnectTimeout(20 * time.Second).
  // HTTP读取或写入超时时间为60秒
  ReadWriteTimeout(60 * time.Second).
  // 不校验SSL证书校验
  WithInsecureSkipVerify(true).
  // 设置日志
  WithLogLevel(oss.LogInfo).
  // 设置区域
  WithRegion("cn-hangzhou")

client := oss.NewClient(cfg)

创建Client

V2版本把Client的创建函数从New修改为NewClient，同时创建函数不再支持传入Endpoint以及access key id和access key secret参数。

V1版示例

client, err := oss.New(endpoint, "ak", "sk")

V2版示例

client := oss.NewClient(cfg)

调用API操作

基础API接口都合并为单一操作方法'<OperationName>'，操作的请求参数为'<OperationName>Request'，操作的返回值为'<OperationName>Result'。这些操作方法都迁移到Client下，同时需要设置context.Context。如下格式：

func (c *Client) <OperationName>(ctx context.Context, request *<OperationName>Request, optFns ...func(*Options)) (*<OperationName>Result，, error)

关于API接口的详细使用说明，请参考基础接口。

V1版示例

import "github.com/aliyun/aliyun-oss-go-sdk/oss"

...

provider, err := oss.NewEnvironmentVariableCredentialsProvider()

client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))  

bucket, err := client.Bucket("examplebucket")

err = bucket.PutObject("exampleobject.txt", bytes.NewReader([]byte("example data")))

V2版示例

import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"

...

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
  WithRegion("your region")

client := oss.NewClient(cfg)

result, err := client.PutObject(context.TODO(), &oss.PutObjectRequest{
  Bucket: oss.Ptr("examplebucket"),
  Key:    oss.Ptr("exampleobject.txt"),
  Body:   bytes.NewReader([]byte("example data")),
})

预签名

V2版本把预签名接口名字从SignURL修改为Presign，同时把接口迁移到Client下。接口形式如下：

func (c *Client) Presign(ctx context.Context, request any, optFns ...func(*PresignOptions)) (*PresignResult, error)

对于request参数，其类型与API接口中的'<OperationName>Request'一致。

对于返回结果，除了返回预签名URL外，还返回HTTP方法，过期时间和被签名的请求头，如下：

type PresignResult struct {
  Method        string
  URL           string
  Expiration    time.Time
  SignedHeaders map[string]string
}

关于预签名的详细使用说明，请参考预签名接口。

以生成下载对象的预签名URL为例，如何从V1迁移到V2。

V1版示例

import "github.com/aliyun/aliyun-oss-go-sdk/oss"

...

provider, err := oss.NewEnvironmentVariableCredentialsProvider()

client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))  

bucket, err := client.Bucket("examplebucket")

signedURL, err := bucket.SignURL("exampleobject.txt", oss.HTTPGet, 60)

fmt.Printf("Sign Url:%s\n", signedURL)

V2版示例

import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"

...

cfg := oss.LoadDefaultConfig().
	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	WithRegion("your region")

client := oss.NewClient(cfg)

result, err := client.Presign(
	context.TODO(),
	&oss.GetObjectRequest{
		Bucket: oss.Ptr("examplebucket"),
		Key:    oss.Ptr("exampleobject.txt"),
	},
	oss.PresignExpires(60*time.Second),
)

fmt.Printf("Sign Method:%v\n", result.Method)
fmt.Printf("Sign Url:%v\n", result.URL)
fmt.Printf("Sign Expiration:%v\n", result.Expiration)
for k, v := range result.SignedHeaders {
	fmt.Printf("SignedHeader %v:%v\n", k, v)
}

断点续传接口

V2版本使用传输管理器'Uploader'，'Downloader' 和'Copier'分别管理对象的上传，下载和拷贝。同时移除了原有的断点续传接口Bucket.UploadFile，Bucket.DownloadFile和Bucket.CopyFile。

接口对比如下：

使用场景	v2	v1
上传文件	Uploader.UploadFile	Bucket.UploadFile
上传流（io.Reader）	Uploader.UploadFrom	不支持
下载到文件	Downloader.DownloadFile	Bucket.DownloadFile
拷贝对象	Copier.Copy	Bucket.CopyFile

默认参数的变化：

场景	v2	v1
上传-分片默认值	6 MiB	通过参数设置
上传-并发默认值	3	1
上传-阈值	分片大小	无
上传-记录checkpoint	支持	支持
下载-分片默认值	6 MiB	通过参数设置
下载-并发默认值	3	1
下载-阈值	分片大小	无
下载-记录checkpoint	支持	支持
拷贝-分片默认值	64 MiB	Bucket.UploadFile
拷贝-并发默认值	3	1
拷贝-阈值	200 MiB	无
拷贝-记录checkpoint	不支持	支持

阈值（上传/下载拷贝）表示对象/文件大小大于该值时，使用分片方式（上传/下载/拷贝）。

关于传输管理器的详细使用说明，请参考传输管理器。

客户端加密

V2版本使用EncryptionClient来提供客户端加密功能，同时也对API 接口做了精简，采用了和Client一样的接口命名规则和调用方式。另外，该版本仅保留基于RSA自主管理的主密钥的参考实现。

对于KMS的实现，可以参考sample/crypto/kms.go。

关于客户端加密的详细使用说明，请参考客户端加密。

下面以使用主密钥RSA上传对象为例，展示如何从 V1 迁移到 V2。

V1版本

import "github.com/aliyun/aliyun-oss-go-sdk/oss"
import "github.com/aliyun/aliyun-oss-go-sdk/oss/crypto"

...

provider, err := oss.NewEnvironmentVariableCredentialsProvider()

client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))  

materialDesc := make(map[string]string)
materialDesc["desc"] = "your master encrypt key material describe information"

masterRsaCipher, err := osscrypto.CreateMasterRsa(materialDesc, "yourRsaPublicKey", "yourRsaPrivateKey")

contentProvider := osscrypto.CreateAesCtrCipher(masterRsaCipher)

cryptoBucket, err := osscrypto.GetCryptoBucket(client, "examplebucket", contentProvider)

err = cryptoBucket.PutObject("exampleobject.txt", bytes.NewReader([]byte("example data")))

V2版本

import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/crypto"

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
  WithRegion("your region")

client := oss.NewClient(cfg)

materialDesc := make(map[string]string)
materialDesc["desc"] = "your master encrypt key material describe information"

mc, err := crypto.CreateMasterRsa(materialDesc, "yourRsaPublicKey", "yourRsaPrivateKey")
eclient, err := NewEncryptionClient(client, mc)

result, err := eclient.PutObject(context.TODO(), &PutObjectRequest{
  Bucket: Ptr("examplebucket"),
  Key:    Ptr("exampleobject.txt"),
  Body:   bytes.NewReader([]byte("example data")),
})

重试

V2版本默认开启对HTTP请求的重试行为。从V1版本迁移到V2时，您需要移除原有的重试代码，避免放大重试次数。