sms-server-cli/README.md

sms-server-cli

短信服务 Go SDK，用于对接 sms-server 的 HTTP API。

模块路径: gitea.s1f.ren/shiran/sms-server-cli
Go 版本: 1.21+

安装

go get gitea.s1f.ren/shiran/sms-server-cli

快速开始

使用 ServiceToken（服务端对服务端）

package main

import (
	"context"
	"fmt"
	"log"

	smscli "gitea.s1f.ren/shiran/sms-server-cli"
)

func main() {
	client := smscli.NewServiceClient("https://sms.example.com", "your-service-token")

	ctx := context.Background()

	// 创建签名
	sig, err := client.CreateSignature(ctx, smscli.CreateSignatureReq{
		Title:         "我的应用",
		ApplicantName: "张三",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("签名 ID: %d\n", sig.ID)

	// 批量发送短信
	resp, err := client.SendBatch(ctx, smscli.SendBatchReq{
		SignatureID: sig.ID,
		TemplateID:  1,
		Params:      map[string]string{"code": "123456"},
		Phones:      []string{"13800138000"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("消息 ID: %s, 计费条数: %d\n", resp.MsgID, resp.FeeCount)
}

使用 UserToken（用户令牌）

client := smscli.NewUserTokenClient("https://sms.example.com", "your-user-token")

resp, err := client.SendBatch(ctx, smscli.SendBatchReq{
	SignatureID: 1,
	TemplateID:  2,
	Params:      map[string]string{"code": "654321"},
	Phones:      []string{"13900139000"},
})

认证方式

方式	构造函数	Header	适用场景
ServiceAuth	NewServiceClient(baseURL, token)	Authorization: ServiceToken <token>	服务端对服务端调用
BearerAuth	NewBearerClient(baseURL, token)	Authorization: Bearer <token>	已登录用户调用
UserTokenAuth	NewUserTokenClient(baseURL, token)	Authorization: UserToken <token>	用户令牌调用

枚举值

ReviewStatus（审核状态）

常量	值	说明
ReviewStatusDraft	0	草稿
ReviewStatusReviewing	1	审核中
ReviewStatusApproved	2	已通过
ReviewStatusRejected	3	已驳回

QuotaType（额度类型）

常量	值	说明
QuotaTypeLongTerm	1	长期额度
QuotaTypeShortTerm	2	短期额度
QuotaTypeCycle	3	周期额度

SendStatus（发送状态）

常量	值	说明
SendStatusPending	0	待发送
SendStatusSubmitted	1	已提交
SendStatusSuccess	2	发送成功
SendStatusFailed	3	发送失败
SendStatusRejected	4	已拒绝

AuthType（认证类型）

常量	值	说明
AuthTypeAuthToken	1	登录令牌
AuthTypeServiceToken	2	服务令牌
AuthTypeUserToken	3	用户令牌

API 参考

签名管理（Signature）

用户接口

方法	说明
CreateSignature(ctx, req)	创建签名
ListSignatures(ctx, query)	获取签名列表
GetSignature(ctx, id)	获取签名详情
UpdateSignature(ctx, id, req)	更新签名
DeleteSignature(ctx, id)	删除签名
SubmitSignature(ctx, id)	提交签名审核

管理员接口

方法	说明
AdminListSignatures(ctx, query)	获取签名列表（支持 UserID/Status 筛选）
AdminGetSignature(ctx, id)	获取签名详情
AdminCreateSignature(ctx, req)	创建签名（可指定用户）
AdminUpdateSignature(ctx, id, req)	更新签名
AdminDeleteSignature(ctx, id)	删除签名
AdminSubmitSignature(ctx, id)	提交签名审核
ApproveSignature(ctx, id)	审核通过签名
RejectSignature(ctx, id, req)	驳回签名

模板管理（Template）

用户接口

方法	说明
CreateTemplate(ctx, req)	创建模板
ListTemplates(ctx, query)	获取模板列表
GetTemplate(ctx, id)	获取模板详情
UpdateTemplate(ctx, id, req)	更新模板
DeleteTemplate(ctx, id)	删除模板
SubmitTemplate(ctx, id)	提交模板审核
ListRecommendedTemplates(ctx, query)	获取推荐模板列表

管理员接口

方法	说明
AdminListTemplates(ctx, query)	获取模板列表（支持 UserID/Status 筛选）
AdminListRecommendedTemplates(ctx, query)	获取推荐模板列表
AdminGetTemplate(ctx, id)	获取模板详情
AdminCreateTemplate(ctx, req)	创建模板（可指定用户）
AdminUpdateTemplate(ctx, id, req)	更新模板
AdminDeleteTemplate(ctx, id)	删除模板
AdminSubmitTemplate(ctx, id)	提交模板审核
ApproveTemplate(ctx, id)	审核通过模板
RejectTemplate(ctx, id, req)	驳回模板
CreateRecommendedTemplate(ctx, req)	创建推荐模板
UpdateRecommendedTemplate(ctx, id, req)	更新推荐模板
DeleteRecommendedTemplate(ctx, id)	删除推荐模板

用户令牌管理（Token）

用户接口

方法	说明
CreateUserToken(ctx, req)	创建令牌
ListUserTokens(ctx, query)	获取令牌列表
GetUserToken(ctx, id)	获取令牌详情
UpdateUserToken(ctx, id, req)	更新令牌
DeleteUserToken(ctx, id)	删除令牌
ToggleUserToken(ctx, id)	切换令牌启用/禁用

管理员接口

方法	说明
AdminListUserTokens(ctx, query)	获取令牌列表（支持 UserID/Status 筛选）
AdminGetUserToken(ctx, id)	获取令牌详情
AdminCreateUserToken(ctx, req)	创建令牌（可指定用户）
AdminUpdateUserToken(ctx, id, req)	更新令牌
AdminDeleteUserToken(ctx, id)	删除令牌
AdminToggleUserToken(ctx, id)	切换令牌启用/禁用

额度管理（Quota）

用户接口

方法	说明
ListQuotas(ctx, query)	获取额度列表
GetQuotaSummary(ctx)	获取额度汇总

管理员接口

方法	说明
AdminListQuotas(ctx, query)	获取额度列表（支持 UserID 筛选）
AdminGetQuotaSummary(ctx, userID)	获取指定用户的额度汇总
CreateQuota(ctx, req)	创建额度
UpdateQuota(ctx, id, req)	更新额度
DeleteQuota(ctx, id)	删除额度

发送管理（Send）

用户接口

方法	说明
SendBatch(ctx, req)	批量发送（相同内容，多号码）
SendMulti(ctx, req)	个性化群发（不同参数，多号码）
ListSendRecords(ctx, query)	获取发送记录列表
GetSendStatus(ctx, msgID)	查询发送状态

管理员接口

方法	说明
AdminListSendRecords(ctx, query)	获取发送记录列表（支持 UserID 筛选）
AdminGetSendStatus(ctx, msgID)	查询发送状态

适配器管理（Adapter）

管理员接口

方法	说明
GetAdapterBalance(ctx)	查询适配器余额

响应结构

所有 API 的 HTTP 响应统一为以下 JSON 结构：

{
  "code": 0,
  "msg": "success",
  "data": { }
}

SDK 会自动处理响应解析，code != 0 时返回包含 msg 的 error。

分页列表接口返回 PaginationResult[T]：

{
  "list": [],
  "total": 100,
  "page": 1
}

License

MIT