Luosimao.Sms 1.0.1

Luosimao.Sms

螺丝帽（Luosimao）SMS 服务的 C# SDK，支持单发、批量、定时发送及余额查询。

功能特性

• ✅ 单条短信发送（验证码、触发类消息）
• ✅ 批量短信发送（通知、提醒类消息）
• ✅ 定时短信发送
• ✅ 账户余额查询
• ✅ Webhook 状态回执模型
• ✅ 完整的错误码和异常处理
• ✅ 依赖注入（DI）支持
• ✅ IHttpClientFactory 集成

系统要求

• .NET Standard 2.0 及以上
• .NET Framework 4.6.1+
• .NET Core 2.0+
• .NET 5/6/7/8+

安装方式

NuGet 包管理器

dotnet add package Luosimao.Sms

Package Manager Console

Install-Package Luosimao.Sms

快速开始

1. 配置服务（ASP.NET Core）

在 Program.cs 中注册服务：

using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// 注册螺丝帽短信服务
builder.Services.AddLuosimaoSms(options =>
{
    options.ApiKey = "your-api-key-here"; // 不含 "key-" 前缀
    options.TimeoutSeconds = 30;
});

var app = builder.Build();

2. 发送单条短信

using Luosimao.Sms;
using Luosimao.Sms.Exceptions;

public class SmsService
{
    private readonly ILuosimaoSmsClient _smsClient;

    public SmsService(ILuosimaoSmsClient smsClient)
    {
        _smsClient = smsClient;
    }

    public async Task SendVerificationCodeAsync(string mobile, string code)
    {
        try
        {
            // 短信内容末尾必须包含签名
            var message = $"您的验证码是：{code}【签名】";
            var result = await _smsClient.SendAsync(mobile, message);

            Console.WriteLine($"发送成功，批次号：{result.BatchId}");
        }
        catch (LuosimaoSmsException ex) when (ex.ErrorCode == -31)
        {
            Console.WriteLine($"发送失败，敏感词：{ex.HitWord}");
        }
        catch (LuosimaoSmsException ex)
        {
            Console.WriteLine($"API 错误：{ex.ErrorCode} - {ex.ErrorMessage}");
        }
    }
}

3. 批量发送短信

var mobiles = new[] { "13800138000", "13800138001", "13800138002" };
var message = "您的订单已发货，请注意查收【签名】";

// 立即发送
var result = await _smsClient.SendBatchAsync(mobiles, message);

// 定时发送
var scheduledTime = DateTime.Now.AddHours(1);
var scheduledResult = await _smsClient.SendBatchAsync(mobiles, message, scheduledTime);

4. 查询账户余额

var status = await _smsClient.GetAccountStatusAsync();
Console.WriteLine($"短信余额：{status.Deposit} 条");

5. 处理 Webhook 状态回执

在您的 Web 服务中接收状态推送：

[HttpPost("webhook/sms-status")]
public IActionResult ReceiveStatusCallback([FromForm] DeliveryReceipt receipt)
{
    switch (receipt.Status)
    {
        case "DELIVRD":
            Console.WriteLine($"手机号 {receipt.Mobile} 接收成功");
            break;
        case "UNDELIV":
            Console.WriteLine($"手机号 {receipt.Mobile} 接收失败");
            break;
        case "REJECTED":
            Console.WriteLine($"手机号 {receipt.Mobile} 被退回，原因：{receipt.Memo}");
            break;
    }

    return Ok();
}

错误处理

SDK 在以下情况下会抛出异常：

LuosimaoSmsException 属性

public class LuosimaoSmsException : Exception
{
    public int ErrorCode { get; }      // 错误码
    public string ErrorMessage { get; } // 错误描述
    public string HitWord { get; }     // 敏感词（仅 error=-31 时有值）
}

完整错误码表

项目结构

Luosimao.Sms/
├── Luosimao.Sms.csproj
├── LuosimaoSmsClient.cs           # 客户端实现
├── ILuosimaoSmsClient.cs         # 客户端接口
├── LuosimaoSmsOptions.cs         # 配置选项
├── Models/
│   ├── SmsResponse.cs             # 单发响应
│   ├── BatchSmsResponse.cs        # 批量响应
│   ├── AccountStatus.cs           # 余额查询响应
│   └── DeliveryReceipt.cs         # Webhook 回执
├── Exceptions/
│   └── LuosimaoSmsException.cs   # 自定义异常
└── Extensions/
    └── ServiceCollectionExtensions.cs  # DI 扩展

Luosimao.Sms.Tests/
├── Luosimao.Sms.Tests.csproj
└── LuosimaoSmsClientTests.cs    # 单元测试

运行测试

dotnet test Luosimao.Sms.Tests/Luosimao.Sms.Tests.csproj

构建与打包

# 构建 Release 版本
dotnet build Luosimao.Sms/Luosimao.Sms.csproj -c Release

# 打包 NuGet 包
dotnet pack Luosimao.Sms/Luosimao.Sms.csproj -c Release

贡献代码

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

许可证

本项目基于 MIT 许可证开源，详见 LICENSE 文件。

致谢

• 螺丝帽 SMS API 文档
• .NET Community