Bitzsoft.Integrations.Sms 1.0.0-alpha.7

Bitzsoft.Integrations.Sms

短信多供应商集成，国内（阿里云 / 腾讯云 / 华为云 / 云片）+ 国际（Twilio / Vonage）六家供应商统一抽象，一套 ISMS 接口 + 统一 SmsMessage 消息对象切换任意厂商。

功能

• 统一 ISMS 接口，屏蔽各厂商 SDK / HTTP 差异，消费方仅依赖 ISMS
• 统一 SmsMessage 消息对象承载各厂商所需字段，各 Provider 读取自身需要的字段
• 支持 SendAsync 异步发送，返回标准化 SMSResult（Ok / Fail / FromException）
• 6 家供应商：
  • 阿里云 / 腾讯云：沿用各自官方 SDK（POP 签名 / API 3.0）
  • 华为云 / 云片 / Twilio / Vonage：纯手写 HttpClient（零额外 SDK 依赖，net5.0 安全）
• 第三方请求审计日志：HttpClient 类 Provider 走 DelegatingHandler 拦截；SDK 类 Provider（阿里 / 腾讯）走 IRequestLogRecorder 回调
• Options 强类型配置，支持 IConfigurationSection 绑定与委托两种注册方式
• 多目标框架：net5.0;net8.0;net10.0

⚠️ v2 破坏性变更（接口重构）

ISMS.SendAsync 由位置参数改为消息对象，统一国内外厂商的发送入口：

// v1（旧）
Task<SMSResult> SendAsync(string phoneNumber, string signName, string templateCode, string templateParams, ...);

// v2（新）
string ProviderName { get; }                                              // 新增：供应商标识
Task<SMSResult> SendAsync(SmsMessage message, CancellationToken ct = default);

迁移：将原 phoneNumber/signName/templateCode/templateParams 组装为 SmsMessage 对象传入（见 使用）。

安装

dotnet add package Bitzsoft.Integrations.Sms

或直接在项目文件中引用：

<PackageReference Include="Bitzsoft.Integrations.Sms" Version="*" />

供应商总览

单供应商注册：ISMS 在 DI 容器中仅保留最后注册的一个供应商实现（多次 Add*Sms 后注册者覆盖前者）。一个应用实例对应一个短信通道；如需多通道并存，请用命名/工厂方式自行管理多个实例。

配置

在 appsettings.json 中按所选供应商添加配置节点（以下为完整示例，按需选用其一）：

{
  "AliyunSms": {
    "AccessKeyId": "your-access-key-id",
    "AccessKeySecret": "your-access-key-secret",
    "RegionId": "cn-hangzhou",
    "Domain": "dysmsapi.aliyuncs.com",
    "Version": "2017-05-25"
  },
  "TencentSms": {
    "SecretId": "your-secret-id",
    "SecretKey": "your-secret-key",
    "AppId": "1400xxxxxx",
    "Region": "ap-guangzhou",
    "CountryCode": "+86"
  },
  "HuaweiSms": {
    "AppKey": "your-app-key",
    "AppSecret": "your-app-secret",
    "Endpoint": "smsapi.cn-north-4.myhuaweicloud.com:443",
    "Sender": "csms12345678",
    "CountryCode": "86"
  },
  "YunpianSms": {
    "ApiKey": "your-apikey",
    "Domain": "sms.yunpian.com",
    "Sender": ""
  },
  "TwilioSms": {
    "AccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "AuthToken": "your-auth-token",
    "From": "+12025550123",
    "Domain": "api.twilio.com",
    "Version": "2010-04-01"
  },
  "VonageSms": {
    "ApiKey": "your-api-key",
    "ApiSecret": "your-api-secret",
    "From": "Bitzsoft",
    "Domain": "rest.nexmo.com"
  }
}

注册

每个供应商均提供「IConfigurationSection 绑定」与「委托手动配置」两种重载。

国内供应商

// 阿里云
builder.Services.AddAliyunSms(builder.Configuration.GetSection("AliyunSms"));

// 腾讯云
builder.Services.AddTencentSms(builder.Configuration.GetSection("TencentSms"));

// 华为云
builder.Services.AddHuaweiSms(builder.Configuration.GetSection("HuaweiSms"));

// 云片
builder.Services.AddYunpianSms(builder.Configuration.GetSection("YunpianSms"));

国际供应商

// Twilio
builder.Services.AddTwilioSms(builder.Configuration.GetSection("TwilioSms"));

// Vonage
builder.Services.AddVonageSms(builder.Configuration.GetSection("VonageSms"));

委托方式示例（以华为云为例，其余同构）：

builder.Services.AddHuaweiSms(options =>
{
    options.AppKey = "your-app-key";
    options.AppSecret = "your-app-secret";
    options.Endpoint = "smsapi.cn-north-4.myhuaweicloud.com:443";
    options.Sender = "csms12345678";
});

SmsMessage 字段说明

SmsMessage 统一承载各厂商所需字段，各 Provider 读取自身需要的字段、忽略其余：

TemplateParams 格式差异（按目标厂商填写）：

第三方请求日志

本包支持两种审计日志记录路径，最终汇入同一 IRequestLogStore：

• HttpClient 类 Provider（华为云 / 云片 / Twilio / Vonage）：通过 AddRequestLogging<TClient>() DelegatingHandler 拦截 HTTP 调用，自动记录请求/响应（含真实状态码与响应体，经脱敏）。
• SDK 类 Provider（阿里云 / 腾讯云）：SDK HTTP 管道封装在内部，无法用 DelegatingHandler 拦截，改由 IRequestLogRecorder 回调在发送包装层记录（Method 记为 SDK）。

// ① 默认：启用审计但不持久化（日志丢弃）
services.AddTwilioSms(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，调用自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 8192;
    opts.SensitiveFields.Add("AuthToken");
});
services.AddTwilioSms(options => { /* ... */ });

自定义 IRequestLogStore 实现（SqlSugar / Dapper / MongoDB）详见 Bitzsoft.Integrations.RequestLogging。

使用

以下示例展示在业务服务中通过注入的 ISMS 发送验证码（厂商由 DI 注册决定）：

using System.Text.Json;
using Bitzsoft.Integrations.Sms;

/// <summary>
/// 用户注册服务
/// </summary>
public class RegistrationService
{
    private readonly ISMS _sms;

    /// <summary>
    /// 初始化注册服务实例
    /// </summary>
    /// <param name="sms">短信发送服务（由 DI 注入具体供应商实现）</param>
    public RegistrationService(ISMS sms)
    {
        _sms = sms;
    }

    /// <summary>
    /// 发送手机验证码
    /// </summary>
    /// <param name="phoneNumber">目标手机号</param>
    /// <param name="verificationCode">6 位数字验证码</param>
    /// <param name="cancellationToken">取消令牌</param>
    public async Task<bool> SendVerificationCodeAsync(
        string phoneNumber,
        string verificationCode,
        CancellationToken cancellationToken = default)
    {
        // 国内厂商（阿里/腾讯/华为）：模板 + 签名
        var message = new SmsMessage
        {
            To = phoneNumber,
            SignName = "我的应用",
            TemplateId = "SMS_123456789",
            TemplateParams = JsonSerializer.Serialize(new { code = verificationCode })
        };

        // 国际厂商（Twilio/Vonage）：主叫号 + 纯文本
        // var message = new SmsMessage
        // {
        //     To = phoneNumber,
        //     Body = $"【我的应用】您的验证码是 {verificationCode}"
        // };

        SMSResult result = await _sms.SendAsync(message, cancellationToken);

        if (!result.Success)
        {
            Console.WriteLine(
                "短信发送失败: ErrorCode={0}, ErrorMessage={1}",
                result.ErrorCode,
                result.ErrorMessage);
            return false;
        }

        Console.WriteLine("短信发送成功, BizId={0}", result.BizId);
        return true;
    }
}

依赖

公共依赖：

• Microsoft.Extensions.Logging.Abstractions，日志抽象
• Microsoft.Extensions.Configuration.Abstractions，配置抽象
• Microsoft.Extensions.Options / Microsoft.Extensions.Options.ConfigurationExtensions，Options 配置模式
• Bitzsoft.Integrations.RequestLogging，第三方请求审计日志

厂商 SDK（仅阿里云 / 腾讯云使用）：

• aliyun-net-sdk-core / Aliyun.OSS.SDK.NetCore，阿里云 OpenAPI SDK
• TencentCloudSDK，腾讯云短信 SDK

华为云 / 云片 / Twilio / Vonage 为纯手写 HttpClient实现，不引入任何厂商 SDK 依赖（华为云 X-WSSE 签名、Twilio/Vonage Basic 鉴权、云片 apikey 均自实现），Directory.Packages.props 无新增。

相关包

• Bitzsoft.Integrations.MFA，多因素认证集成（短信验证码通道）
• Bitzsoft.Integrations.OutboundCall，外呼集成（与短信同属通信域）
• Bitzsoft.Integrations.RequestLogging，第三方请求审计日志横切包