docs: 完善Go SDK集成说明
- SDK包名修正为 dysmsapi-20170525/v4/client - 补充三种操作系统环境变量配置（Linux/macOS/Windows CMD/PowerShell） - 完善SDK使用代码（初始化、发送短信、异常处理） - 补充更多返回码和常见错误处理 - 推荐单例模式创建客户端 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
parent
3370f0507d
commit
c8501c9895
@ -405,67 +405,137 @@ SMS_REGION=cn-hangzhou
|
||||
|
||||
### 12.5 Go SDK 使用说明
|
||||
|
||||
#### 环境要求
|
||||
|
||||
- Go 环境版本必须不低于 1.10.x
|
||||
|
||||
#### 依赖安装
|
||||
|
||||
```bash
|
||||
go get github.com/alibabacloud-go/dysmsapi-20180501/v2
|
||||
go get github.com/alibabacloud-go/dysmsapi-20170525/v4/client
|
||||
go get github.com/alibabacloud-go/darabonba-openapi/v2/client
|
||||
go get github.com/aliyun/credentials-go/credentials
|
||||
go get github.com/alibabacloud-go/tea/tea
|
||||
go get github.com/alibabacloud-go/tea-utils/v2/service
|
||||
```
|
||||
|
||||
#### 初始化客户端
|
||||
#### 设置访问凭据
|
||||
|
||||
阿里云 SDK 支持通过环境变量自动查找凭据，推荐使用 AK 方式：
|
||||
|
||||
**Linux / macOS**
|
||||
```bash
|
||||
export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyID
|
||||
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret
|
||||
```
|
||||
|
||||
**Windows CMD**
|
||||
```cmd
|
||||
setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M
|
||||
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M
|
||||
```
|
||||
|
||||
**Windows PowerShell**
|
||||
```powershell
|
||||
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::Machine)
|
||||
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::Machine)
|
||||
```
|
||||
|
||||
#### 初始化客户端（推荐单例模式）
|
||||
|
||||
```go
|
||||
import (
|
||||
dysmsapi20180501 "github.com/alibabacloud-go/dysmsapi-20180501/v2/client"
|
||||
"os"
|
||||
openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
|
||||
credential "github.com/aliyun/credentials-go/credentials"
|
||||
dysmsapi20170525 "github.com/alibabacloud-go/dysmsapi-20170525/v4/client"
|
||||
"github.com/alibabacloud-go/tea/tea"
|
||||
)
|
||||
|
||||
// 使用默认凭据链初始化
|
||||
cred, _ := credential.NewCredential(nil)
|
||||
config := &openapi.Config{
|
||||
Credential: cred,
|
||||
Endpoint: tea.String("dysmsapi.aliyuncs.com"),
|
||||
func CreateClient() (_result *dysmsapi20170525.Client, _err error) {
|
||||
config := &openapi.Config{
|
||||
AccessKeyId: tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")),
|
||||
AccessKeySecret: tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")),
|
||||
}
|
||||
config.Endpoint = tea.String("dysmsapi.aliyuncs.com")
|
||||
_result, _err = dysmsapi20170525.NewClient(config)
|
||||
return _result, _err
|
||||
}
|
||||
client, _ := dysmsapi20180501.NewClient(config)
|
||||
```
|
||||
|
||||
> ⚠️ **注意**：客户端实例线程安全，建议采用单例模式，避免频繁创建。
|
||||
|
||||
#### 发送短信（注册验证码场景）
|
||||
|
||||
```go
|
||||
// 构造请求
|
||||
request := &dysmsapi20180501.SendSmsRequest{
|
||||
PhoneNumbers: tea.String("13800138000"), // 手机号
|
||||
SignName: tea.String("TopFans"), // 签名
|
||||
TemplateCode: tea.String("SMS_xxxxxxx"), // 模板CODE
|
||||
TemplateParam: tea.String(`{"code":"123456"}`), // 模板变量
|
||||
}
|
||||
import (
|
||||
dysmsapi20170525 "github.com/alibabacloud-go/dysmsapi-20170525/v4/client"
|
||||
util "github.com/alibabacloud-go/tea-utils/v2/service"
|
||||
"github.com/alibabacloud-go/tea/tea"
|
||||
)
|
||||
|
||||
// 发送
|
||||
resp, err := client.SendSmsWithOptions(request, &util.RuntimeOptions{})
|
||||
if err != nil {
|
||||
// 错误处理
|
||||
return err
|
||||
}
|
||||
func SendVerificationCode() (_result *dysmsapi20170525.SendSmsResponse, _err error) {
|
||||
client, _err := CreateClient()
|
||||
if _err != nil {
|
||||
return nil, _err
|
||||
}
|
||||
|
||||
// 成功返回
|
||||
fmt.Println(resp.Body.RequestId) // 请求ID
|
||||
fmt.Println(resp.Body.Code) // 状态码
|
||||
fmt.Println(resp.Body.Message) // 状态消息
|
||||
// 构造请求
|
||||
sendSmsRequest := &dysmsapi20170525.SendSmsRequest{
|
||||
PhoneNumbers: tea.String("13800138000"), // 手机号
|
||||
SignName: tea.String("TopFans"), // 签名
|
||||
TemplateCode: tea.String("SMS_xxxxxxx"), // 模板CODE
|
||||
TemplateParam: tea.String(`{"code":"123456"}`), // 模板变量
|
||||
}
|
||||
|
||||
// 发送
|
||||
runtime := &util.RuntimeOptions{}
|
||||
response, _err := client.SendSmsWithOptions(sendSmsRequest, runtime)
|
||||
if _err != nil {
|
||||
return nil, _err
|
||||
}
|
||||
return response, nil
|
||||
}
|
||||
```
|
||||
|
||||
#### 返回码说明
|
||||
|
||||
| Code | Message | 说明 |
|
||||
|------|---------|------|
|
||||
| OK | 请求成功 | 短信发送成功 |
|
||||
| isv.BUSINESS_LIMIT_CONTROL | 触发频率限制 | 发送过于频繁 |
|
||||
| isv.DAY_LIMIT_CONTROL | 触发日限额 | 当天发送量已达上限 |
|
||||
| isv.SMS_CONTENT_ILLEGAL | 内容违规 | 短信内容包含敏感词 |
|
||||
| isv.MOBILE_NUMBER_ILLEGAL | 手机号格式错误 | 手机号不符合规范 |
|
||||
| Code | 说明 |
|
||||
|------|------|
|
||||
| OK | 请求成功，短信发送成功 |
|
||||
| isv.BUSINESS_LIMIT_CONTROL | 触发频率限制，发送过于频繁 |
|
||||
| isv.DAY_LIMIT_CONTROL | 当天发送量已达上限 |
|
||||
| isv.SMS_CONTENT_ILLEGAL | 短信内容包含敏感词 |
|
||||
| isv.MOBILE_NUMBER_ILLEGAL | 手机号格式错误 |
|
||||
| isv.SMS_SIGNATURE_ILLEGAL | 签名格式错误或未审核通过 |
|
||||
| isv.TEMPLATE_MISSING_PARAMETERS | 模板变量缺失 |
|
||||
| isv.BLACK_KEY_CONTROL_LIMIT | 黑名单关键字 |
|
||||
|
||||
#### 异常处理
|
||||
|
||||
V2.0 Go SDK 将异常分为两类：
|
||||
|
||||
- **error**：非业务报错（如文件损坏、解析失败）
|
||||
- **SDKError**：业务报错（如频率超限、配额不足）
|
||||
|
||||
```go
|
||||
response, err := client.SendSmsWithOptions(sendSmsRequest, runtime)
|
||||
if err != nil {
|
||||
// 打印错误诊断
|
||||
fmt.Println(tea.StringValue(err.Message))
|
||||
return err
|
||||
}
|
||||
|
||||
// 获取请求ID
|
||||
fmt.Println(tea.StringValue(response.Body.RequestId))
|
||||
fmt.Println(tea.StringValue(response.Body.Code))
|
||||
```
|
||||
|
||||
#### 常见问题
|
||||
|
||||
| 错误提示 | 可能原因 | 解决方案 |
|
||||
|---------|---------|---------|
|
||||
| "You are not authorized to perform this operation" | 无权限调用该 API | 检查 RAM 权限策略 |
|
||||
| "Specified access key is not found" | AccessKey ID 错误或已删除 | 确认环境变量是否正确设置 |
|
||||
| "dial tcp: lookup xxx: no such host" | Endpoint 配置错误 | 确认 Endpoint 为 `dysmsapi.aliyuncs.com` |
|
||||
|
||||
### 12.6 相关文档
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user