Bitzsoft.Integrations.Sms 1.0.0-alpha.6

Bitzsoft.Integrations.Sms

短信双通道集成 -- 阿里云短信 + 腾讯云短信统一抽象，一套接口切换两大云厂商。

功能

• 统一 ISMS 接口，屏蔽阿里云与腾讯云 SDK 差异
• 支持 SendAsync 异步发送，返回标准化 SMSResult
• 阿里云短信：基于 OpenPlatform POP 签名调用
• 腾讯云短信：基于腾讯云 API 3.0 签名调用
• Options 强类型配置，支持 IConfigurationSection 绑定
• 独立 DI 注册，可按需引入单通道或双通道

安装

dotnet add package Bitzsoft.Integrations.Sms

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

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

配置

在 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"
  }
}

注册

阿里云短信通道

using Bitzsoft.Integrations.Sms.Aliyun;

// 方式一：通过 IConfigurationSection 绑定
builder.Services.AddAliyunSms(builder.Configuration.GetSection("AliyunSms"));

// 方式二：通过委托手动配置
builder.Services.AddAliyunSms(options =>
{
    options.AccessKeyId = "your-access-key-id";
    options.AccessKeySecret = "your-access-key-secret";
    options.RegionId = "cn-hangzhou";
    options.Domain = "dysmsapi.aliyuncs.com";
    options.Version = "2017-05-25";
});

腾讯云短信通道

using Bitzsoft.Integrations.Sms.Tencent;

// 方式一：通过 IConfigurationSection 绑定
builder.Services.AddTencentSms(builder.Configuration.GetSection("TencentSms"));

// 方式二：通过委托手动配置
builder.Services.AddTencentSms(options =>
{
    options.SecretId = "your-secret-id";
    options.SecretKey = "your-secret-key";
    options.AppId = "1400xxxxxx";
    options.Region = "ap-guangzhou";
    options.CountryCode = "+86";
});

第三方请求日志

⚠️ 机制说明：本连接器基于阿里云 aliyun-net-sdk-core 与腾讯云 TencentCloudAPI3.0 SDK，HTTP 管道封装在各自 SDK 内部，无法用 DelegatingHandler 拦截（与 HttpClient 直连实现不同）。因此请求日志改由 IRequestLogRecorder 回调钩子实现——在短信发送包装层记录每次 API 调用，汇入与 HttpClient 拦截同一个日志管道（IRequestLogStore），由宿主统一持久化。

记录内容（每次短信 API 调用产生一条）：

局限（诚实声明）：

• SDK 不暴露原始 HTTP 状态码与响应头，故无法像 HttpClient 拦截那样记录真实 HTTP StatusCode/RequestHeaders，StatusCode 仅为尽力而为（成功记 200、异常时留空）。
• 仅本连接器实现的 SendSms 发送动作会被记录；SDK 的其他能力（签名管理、模板审核、回执拉取等）本连接器未实现，不在记录范围。

// ① 默认：启用回调但不持久化（日志丢弃）
services.AddAliyunSms(options => { /* ... */ });
//   或
services.AddTencentSms(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，短信调用自动落库
//    AddXxxSms 内部已注入 IRequestLogRecorder，宿主无需再额外挂载 handler
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 8192;            // 单条正文截断上限
    opts.SensitiveFields.Add("mySecret"); // 额外脱敏字段
});
services.AddAliyunSms(options => { /* ... */ });

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

使用

以下示例展示在业务服务中通过阿里云通道发送验证码短信：

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 templateParams = JsonSerializer.Serialize(new { code = verificationCode });

        SMSResult result = await _sms.SendAsync(
            phoneNumber: phoneNumber,
            signName: "我的应用",
            templateCode: "SMS_123456789",
            templateParams: templateParams,
            cancellationToken: cancellationToken);

        if (!result.Success)
        {
            // 记录失败日志，包含错误码与错误消息
            Console.WriteLine(
                "短信发送失败: ErrorCode={0}, ErrorMessage={1}",
                result.ErrorCode,
                result.ErrorMessage);
            return false;
        }

        // 可将 result.BizId 存储用于后续状态查询
        Console.WriteLine("短信发送成功, BizId={0}", result.BizId);
        return true;
    }
}

依赖

• Microsoft.Extensions.Logging.Abstractions -- 日志抽象
• Microsoft.Extensions.Configuration.Abstractions -- 配置抽象
• Microsoft.Extensions.Options -- Options 配置模式
• Microsoft.Extensions.Options.ConfigurationExtensions -- 配置节点绑定
• aliyun-net-sdk-core -- 阿里云 OpenAPI SDK
• Aliyun.OSS.SDK.NetCore -- 阿里云 SDK 基础依赖
• TencentCloudSDK -- 腾讯云短信 SDK

相关包

• Bitzsoft.Integrations.MFA -- 多因素认证集成（短信验证码通道）
• Bitzsoft.Integrations.CrawlingService -- 网页爬取服务集成客户端
• Bitzsoft.Integrations.Ocr -- OCR 文字识别集成