MYDev.WuXingSms 1.0.0-preview.5

MYDev.WuXingSms

五兴短信服务SDK，基于MYDev项目架构和Sparkdo框架实现，完整支持五兴短信API v1.6版本。

功能特性

• ✅ 短信发送：批量发送、一对一发送，支持定时发送和模板短信
• ✅ 余额查询：实时查询账户余额和短信条数
• ✅ 状态报告：获取短信投递状态和回执信息
• ✅ 上行短信：接收用户回复的上行短信
• ✅ 模板管理：提交和查询短信模板
• ✅ 签名管理：报备和查询短信签名
• ✅ MD5签名验证：自动处理API请求签名
• ✅ 依赖注入：完整的DI支持和配置管理

快速开始

1. 安装依赖

在项目中引用此包：

<PackageReference Include="MYDev.WuXingSms" Version="x.x.x" />

2. 配置服务

在 Program.cs 或 Startup.cs 中配置：

// 配置五兴短信选项
builder.Services.Configure<WuXingSmsOptions>(options =>
{
    options.UserName = "your_username";  // 必填：账号用户名
    options.Password = "your_password";  // 必填：账号密码
});

// 注册五兴短信服务
builder.Services.AddWuXingSms();

或通过配置文件（appsettings.json）：

{
  "WuXingSms": {
    "UserName": "your_username",
    "Password": "your_password"
  }
}

3. 使用短信发送器

通过 ISmsSender 接口发送短信：

public class MyService
{
    private readonly ISmsSender _smsSender;

    public MyService(ISmsSender smsSender)
    {
        _smsSender = smsSender;
    }

    public async Task SendVerificationCodeAsync()
    {
        await _smsSender.SendAsync(new SmsMessage
        {
            PhoneNumber = "13800138000",
            Text = "您的验证码是：123456，5分钟内有效",
            Properties = new Dictionary<string, object>
            {
                ["SendTime"] = DateTime.Now.AddMinutes(5), // 可选：定时发送
                ["Extcode"] = "1001",                       // 可选：扩展号
                ["CallData"] = "order_12345"                // 可选：回调数据
            }
        });
    }
}

4. 直接使用请求工厂

通过 WuXingSmsRequests 工厂类直接使用所有API：

// 批量发送短信
var sendRequest = WuXingSmsRequests.ToSendMass(new WuXingSmsRequests.SendMassModel
{
    PhoneList = new List<string> { "13800138000", "13900139000" },
    Content = "您的验证码是：123456",
    SendTime = "2024-01-01 12:00:00" // 可选：定时发送
});
var sendResponse = await sender.SendAsync(sendRequest);

// 一对一发送短信（每个号码不同内容）
var sendOneRequest = WuXingSmsRequests.ToSendOne(new WuXingSmsRequests.SendOneModel
{
    MessageList = new List<WuXingSmsRequests.MessageItem>
    {
        new() { Phone = "13800138000", Content = "用户A的验证码：111111" },
        new() { Phone = "13900139000", Content = "用户B的验证码：222222" }
    }
});
var sendOneResponse = await sender.SendAsync(sendOneRequest);

// 查询余额
var balanceRequest = WuXingSmsRequests.ToBalanceQuery();
var balanceResponse = await sender.SendAsync(balanceRequest);
Console.WriteLine($"余额：{balanceResponse.Amount}元，剩余条数：{balanceResponse.Number}");

// 查询状态报告
var reportRequest = WuXingSmsRequests.ToReportQuery(limit: 100);
var reportResponse = await sender.SendAsync(reportRequest);

// 查询上行短信
var uplinkRequest = WuXingSmsRequests.ToUplinkQuery(limit: 100);
var uplinkResponse = await sender.SendAsync(uplinkRequest);

// 提交短信模板
var templateRequest = WuXingSmsRequests.ToTemplateCreate(new WuXingSmsRequests.TemplateCreateModel
{
    Content = "您的验证码是{%code%}，{%minutes%}分钟内有效",
    Type = 2,                    // 2=模糊模板
    MatchPercent = 80,           // 匹配度80%
    ExpireDate = "2025-12-31"    // 可选：失效日期
});
var templateResponse = await sender.SendAsync(templateRequest);
Console.WriteLine($"模板ID：{templateResponse.TemplateId}");

// 查询短信模板
var queryTemplateRequest = WuXingSmsRequests.ToTemplateQuery(templateId: 12345);
var queryTemplateResponse = await sender.SendAsync(queryTemplateRequest);

// 报备签名
var signatureRequest = WuXingSmsRequests.ToSignatureAdd(new WuXingSmsRequests.SignatureAddModel
{
    SignatureList = new List<string> { "【公司名】", "【产品名】" }
});
var signatureResponse = await sender.SendAsync(signatureRequest);

// 查询签名
var querySignatureRequest = WuXingSmsRequests.ToSignatureQuery();
var querySignatureResponse = await sender.SendAsync(querySignatureRequest);

API 接口说明

1. 短信发送接口

批量发送（SendMessageMass）

端点：POST /sms/api/sendMessageMass

请求参数：

响应字段：

一对一发送（SendMessageOne）

端点：POST /sms/api/sendMessageOne

支持为每个手机号发送不同的内容，参数结构与批量发送类似，使用 messageList 数组。

2. 余额查询（GetBalance）

端点：POST /sms/api/getBalance

响应字段：

3. 状态报告查询（GetReport）

端点：POST /sms/api/getReport

请求参数：

4. 上行短信查询（GetUpstream）

端点：POST /sms/api/getUpstream

请求参数：

5. 模板管理接口

提交模板（CreateTemplate）

端点：POST /sms/api/createTemplate

请求参数：

查询模板（QueryTemplates）

端点：POST /sms/api/queryTemplates

请求参数：

6. 签名管理接口

报备签名（AddSignature）

端点：POST /sms/api/addSignature

请求参数：

查询签名（QuerySignature）

端点：POST /sms/api/querySignature

配置选项

WuXingSmsOptions

签名机制

五兴短信API使用MD5签名验证，签名规则：

sign = MD5(userName + timestamp + MD5(password))

SDK自动处理签名计算，通过 IWuXingSmsSigner 接口实现：

public interface IWuXingSmsSigner
{
    string Sign(WuXingSmsOptions options, long timestamp);
}

默认实现 WuXingSmsSigner 已注册为瞬态服务，无需额外配置。

响应状态码

项目结构

MYDev.WuXingSms/
├── MYDev/WuXingSms/
│   ├── Requests/                              # 请求类
│   │   ├── HttpRequest.cs                     # HTTP请求基类
│   │   ├── WuXingResponse.cs                  # 响应基类
│   │   ├── WuXingSmsRequests.cs               # 请求工厂类
│   │   ├── WuXingSmsRequests.SendMassRequest.cs      # 批量发送
│   │   ├── WuXingSmsRequests.SendOneRequest.cs       # 一对一发送
│   │   ├── WuXingSmsRequests.BalanceQueryRequest.cs  # 余额查询
│   │   ├── WuXingSmsRequests.StatusReportRequest.cs  # 状态报告
│   │   ├── WuXingSmsRequests.UplinkQueryRequest.cs   # 上行短信
│   │   ├── WuXingSmsRequests.TemplateCreateRequest.cs # 创建模板
│   │   ├── WuXingSmsRequests.TemplateQueryRequest.cs  # 查询模板
│   │   ├── WuXingSmsRequests.SignatureAddRequest.cs   # 报备签名
│   │   └── WuXingSmsRequests.SignatureQueryRequest.cs # 查询签名
│   ├── IWuXingSmsSigner.cs                    # 签名器接口
│   ├── WuXingSmsSigner.cs                     # 签名器实现
│   ├── WuXingSmsSignerExtensions.cs           # 签名器扩展
│   ├── WuXingSmsOptions.cs                    # 配置选项
│   ├── WuXingSmsSender.cs                     # 短信发送器
│   └── MYDevWuXingSmsModule.cs                # 模块注册
├── Microsoft/Extensions/DependencyInjection/
│   └── MYDevWuXingSmsServiceCollectionExtensions.cs # DI扩展
└── Sparkdo/Mediation/
    └── MYDevWuXingSmsMediationExtensions.cs           # Mediation扩展

高级用法

自定义签名器

如果需要自定义签名逻辑，可以实现 IWuXingSmsSigner 接口：

public class CustomWuXingSmsSigner : IWuXingSmsSigner
{
    public string Sign(WuXingSmsOptions options, long timestamp)
    {
        // 自定义签名逻辑
        return $"custom_sign_{timestamp}";
    }
}

// 注册自定义签名器
builder.Services.AddSingleton<IWuXingSmsSigner, CustomWuXingSmsSigner>();

批量发送模板短信

var request = WuXingSmsRequests.ToSendMass(new WuXingSmsRequests.SendMassModel
{
    PhoneList = new List<string> { "13800138000", "13900139000" },
    TemplateId = 12345,
    Params = new Dictionary<string, string>
    {
        ["code"] = "123456",
        ["minutes"] = "5"
    }
});

var response = await sender.SendAsync(request);

定时发送

var request = WuXingSmsRequests.ToSendMass(new WuXingSmsRequests.SendMassModel
{
    PhoneList = new List<string> { "13800138000" },
    Content = "定时发送的短信内容",
    SendTime = DateTime.Now.AddHours(2).ToString("yyyy-MM-dd HH:mm:ss")
});

await sender.SendAsync(request);

注意事项

1. API域名：默认使用 https://smsvb.wxkjwlw.com:8443，如需更改请修改 WuXingSmsOptions.Domain 常量
2. 签名格式：报备签名时必须包含完整的"【】"符号，例如：["【公司名】"]
3. 模板变量：模板内容中的变量必须使用 {%变量名%} 格式
4. 时间格式：定时发送时间格式为 yyyy-MM-dd HH:mm:ss
5. 频率限制：注意遵守API的频率限制，避免触发限流
6. 错误处理：始终检查响应的 Code 字段，0表示成功

开发指南

添加新接口

1. 在 Requests 文件夹创建新的请求类文件
2. 继承 HttpRequest<TResponse> 基类
3. 实现 Endpoint、Method、RequestUri 和 Content 属性
4. 在 WuXingSmsRequests.cs 中添加工厂方法
5. 定义对应的请求模型和响应类

编译项目

# Debug模式
dotnet build

# Release模式
dotnet build -c Release

依赖项

• .NET 10.0
• Sparkdo框架
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.Http
• System.Text.Json

许可证

MIT

参考资料

• 五兴短信官方接口文档 v1.6
• Sparkdo框架文档