登录 注册

开发者文档中心

为开发者提供短信、人机验证、SSL等产品的 API 接入指南与多种开发语言 SDK

短信服务 SDK

Go SDK 接入指南

Luosimao 官方提供的 Go 语言 SDK，支持 Go 1.16+ 及 Go Modules，为您提供快速发送短信、查询余额及异步处理的能力。

环境要求：Go >= 1.16，支持 Go Modules。

1. 安装

推荐使用 go get 命令安装：

Terminal 
go get github.com/luosimao-oss/sms-go

2. 快速使用

2.1 初始化客户端

引入 github.com/luosimao-oss/sms-go 包，并使用您的 API_KEY 初始化 Client 实例。客户端是并发安全的，建议在应用中作为全局单例使用。

init.go 
package main

import (
    "time"
    luosimao "github.com/luosimao-oss/sms-go"
)

func main() {
    // 基础初始化
    client := luosimao.NewClient("your_api_key")

    // 或者使用可选参数配置（例如设置超时时间）
    clientWithOptions := luosimao.NewClient("your_api_key",
        luosimao.WithTimeout(10 * time.Second),
    )
}

支持的初始化配置选项：

  • WithTimeout(d time.Duration) - 设置 HTTP 请求超时时间
  • WithHTTPClient(c *http.Client) - 使用自定义的 HTTP 客户端
  • WithBaseURL(url string) - 设置自定义的基础 API URL

2.2 发送单条短信

调用 Send 方法向单个手机号发送短信，注意短信内容必须包含审核通过的【签名】。

send.go 
package main

import (
    "context"
    "fmt"
    "log"

    luosimao "github.com/luosimao-oss/sms-go"
)

func main() {
    client := luosimao.NewClient("your_api_key")

    // 发送单条短信
    resp, err := client.Send(context.Background(), "13800138000", "验证码：123456【你的公司】")
    if err != nil {
        log.Fatalf("发送失败: %v", err)
    }

    fmt.Printf("发送成功，流水号: %s\n", resp.Msg)
}

2.3 批量发送短信

如果您需要向多个用户发送相同的内容，建议使用批量发送接口 SendBatch，以获得更高的发送效率。

batch.go 
mobiles := []string{"13800138000", "13800138001"}

// 第四个参数为可选的定时发送时间，传 nil 表示立即发送
resp, err := client.SendBatch(context.Background(), mobiles, "活动通知：全场半价！【你的公司】", nil)
if err != nil {
    // 您可以使用 SDK 提供的错误判断方法
    if luosimao.IsInsufficientBalance(err) {
        log.Fatal("余额不足，请充值")
    }
    log.Fatalf("批量发送失败: %v", err)
}

fmt.Printf("批量发送成功，批次流水号: %s\n", resp.Msg)

2.4 查询账户余额

通过 GetStatus 方法可以查询当前账户的短信剩余条数。

status.go 
status, err := client.GetStatus(context.Background())
if err != nil {
    log.Fatalf("查询失败: %v", err)
}

fmt.Printf("当前账户余额: %d 条\n", status.Result.Deposit)

2.5 异常处理

当 API 返回错误（如余额不足、敏感词等）或发生网络错误时，SDK 会返回 error 接口的实现。所有的 API 业务错误都会被包装为 luosimao.APIError。

error_handling.go 
resp, err := client.Send(context.Background(), "13800138000", "包含敏感词的内容【你的公司】")
if err != nil {
    // 检查是否是因为命中敏感词拦截
    if luosimao.IsHitSensitiveWord(err) {
        // 可以通过类型断言获取具体的敏感词
        if apiErr, ok := err.(*luosimao.APIError); ok {
            fmt.Printf("触发敏感词拦截: %s\n", apiErr.Hit)
        }
    } else if luosimao.IsAuthFailed(err) {
        fmt.Println("API Key 错误或被禁用")
    } else {
        fmt.Printf("其他错误: %v\n", err)
    }
}

辅助方法列表：

  • luosimao.IsAuthFailed(err)：是否认证失败 (对应错误码 -10, -11)
  • luosimao.IsInsufficientBalance(err)：是否余额不足 (对应错误码 -20)
  • luosimao.IsHitSensitiveWord(err)：是否命中敏感词 (对应错误码 -31)