PlumX.Core.CAP 1.0.0-preview.9

PlumX.Core.CAP

NuGet 包 ID：PlumX.Core.CAP

注册方式

新应用使用模块化入口 AddPlumCap，并显式引用和传入实际使用的传输与存储 Provider：

builder.Services.AddPlumCap(
    builder.Configuration,
    CapRabbitMqProvider.Configure,
    CapMySqlProvider.Configure);

PlumX.Core.CAP 本身不静态依赖 RabbitMQ、MySQL 或 SQL Server Provider。推荐使用上面的显式 Provider 委托重载；也可调用 AddPlumCap(builder.Configuration)，它会在运行时加载 PlumX.Core.CAP.RabbitMQ，并根据 CAP:CapDBType 加载 PlumX.Core.CAP.MySql 或 PlumX.Core.CAP.SqlServer。使用配置驱动重载的应用必须引用所需的 Provider 包；CAP:RabbitMq、Provider 包或其 Configure 方法缺失时，启动会抛出包含包名的 InvalidOperationException。

定位

封装 DotNetCore.CAP 8.4.1 的发布/订阅与事务消息基础能力，负责框架通用适配和配置约定。CAP 的消息传输和持久化 provider 由同名扩展项目提供。

依赖与接入

• 目标框架：net8.0
• 直接依赖：DotNetCore.CAP、PlumX.Core.Common；通知使用 .NET 内置 JSON 和 HTTP 客户端。

按 CAP 官方方式注册数据库存储、传输器和订阅者，再使用本项目提供的扩展类型。具体 provider 见 PlumX.Core.CAP.RabbitMQ、PlumX.Core.CAP.MySql 和 PlumX.Core.CAP.SqlServer。

配置中心中的 CAP 配置

AddPlumCap 从当前 IConfiguration 的 CAP 节绑定 CapOption。当应用启用 Nacos 或 Consul 配置中心时，远程 CAP 节会按配置加载顺序覆盖本地同名值，因此数据库连接、RabbitMQ 凭据和失败通知配置可以由配置中心提供。

{
  "CAP": {
    "CapDBType": "MySql",
    "CapDBConnectionString": "由配置中心或密钥管理服务提供",
    "SucceedMessageExpiredAfter": 86400,
    "FailedRetryInterval": 60,
    "FailedRetryCount": 50,
    "GroupVersion": "v1",
    "GroupPrefix": "Orders.Api",
    "IgnoreUnsubscribedMessages": true,
    "RabbitMq": {
      "Host": "rabbitmq.internal",
      "Port": 5672,
      "UserName": "由密钥管理服务提供",
      "Password": "由密钥管理服务提供",
      "ExchangeName": "cap.default",
      "VirtualHost": "/",
      "BasicQos": 1
    },
    "WeComRobotAlert": {
      "Enabled": false,
      "WebhookUrl": "",
      "TimeoutSeconds": 10
    }
  }
}

• CapDBType：MySql 时使用 PlumX.Core.CAP.MySql；其他值走 PlumX.Core.CAP.SqlServer。两者都需要 CapDBConnectionString。
• SucceedMessageExpiredAfter：成功消息保留秒数，默认 86400。
• FailedRetryInterval、FailedRetryCount：失败消息重试间隔秒数和最大次数，默认 60、50。
• GroupVersion：传递给 CAP Version，默认 v1。
• GroupPrefix：CAP 默认消费组前缀；为空时使用入口程序集名。当前默认组名仍包含实例机器名，业务消费者应通过 [CapSubscribe(..., Group = "...")] 明确指定消费组。
• IgnoreUnsubscribedMessages：true 时忽略“找不到订阅者”失败；其他失败在达到阈值后仍会执行失败回调。
• RabbitMq：RabbitMQ Provider 必填。BasicQos 大于 1 时才会向 CAP 设置 Qos；默认 1 使用 CAP 默认行为。
• WeComRobotAlert：可选的企业微信群机器人失败告警，默认关闭；启用方法见下节。

生产环境必须将 CapDBConnectionString、RabbitMq:UserName、RabbitMq:Password 和通知敏感值放在配置中心、环境变量或密钥管理系统中，不能提交到 Git。配置中心的加载顺序和覆盖规则见 配置中心与本地配置加载。

企业微信群失败告警

将 CAP:WeComRobotAlert:Enabled 设为 true，并通过配置中心、环境变量或密钥管理服务注入 HTTPS WebhookUrl。使用 AddPlumCap 即完成接入，不需要额外注册方法或项目。环境变量键为 CAP__WeComRobotAlert__Enabled 和 CAP__WeComRobotAlert__WebhookUrl，不要把真实地址提交到 Git。

发布和订阅失败达到 FailedRetryCount 阈值、由 CAP 调用 FailedThresholdCallback 时才告警，不是每次失败都发送。默认最大重试次数为 50，告警可能晚于首次失败；IgnoreUnsubscribedMessages=true 时继续过滤包含 can not be found subscriber 的失败。配置在注册时读取，变更需重启应用；显式 Provider 配置委托可覆盖该回调，覆盖后内置告警不再执行。

消息使用企业微信 markdown_v2（msgtype 和内容字段均为 markdown_v2），包含应用、机器、主题、消息 ID、消费组、时间和异常首行摘要。主题和消费组使用行内代码展示，保留下划线（包括连续及首尾下划线）；动态字段中的反引号等标记仍会净化，避免破坏消息格式。按 UTF-8 字节截断以满足 4096 字节限制，不发送消息正文或完整堆栈。异常首行仍可能含业务敏感信息，业务应避免将敏感值写入异常。格式与客户端兼容要求见企业微信官方消息推送说明。

TimeoutSeconds 默认 10，非正数回退到 10。CAP 8.4.1 的回调是同步委托，因此发送期间占用回调线程，最多等待请求超时时间；不使用 async void。空或无效 Webhook 不阻止应用启动，而是在触发告警时跳过并记录警告。非 HTTPS 地址不接受，HTTP 重定向不跟随。

告警尽力发送：HTTP 错误、超时、网络异常、无效响应及非零企业微信 errcode 均只记录警告，不改变 CAP 的失败状态；不另行持久化、重试或保证仅发送一次。默认 HTTP 客户端日志已关闭，发送器不记录 Webhook、响应正文或原始 HTTP 异常。宿主自定义 HTTP 处理器、追踪或代理日志仍需自行脱敏。

旧 CAP:WxMsgOption（OpenId + 公众号模板）和 WxTemplateInfoOption 已移除，旧配置不会再生效；代码引用需删除或迁移到 WeComRobotAlert。MessageBus:ExceptionWXMsgConfig 不受影响。

边界

CAP 与 PlumX.Core.MessageBus 是两套独立消息模型。当前不承诺 CAP 多 MQ 实例路由，也不提供跨 provider 的统一配置。

完整使用示例

CAP Core 注册、发布订阅与消费组示例见 模块使用示例。

注释与 XML 文档检查

公开 API 应提供中文 XML 注释；告警发送器的内部构造函数和关键方法也说明应用名回退、错误隔离、消息内容边界及 UTF-8 裁剪规则。简单实现无需机械重复方法名，注释不改变运行行为。

当前 CAP 项目未默认启用 XML 文档生成；.editorconfig 将 CS1591 设为错误，并不等于默认构建会检查所有缺失注释。该诊断针对对外可见的类型与成员，不强制要求内部类型的所有方法具有 XML 注释。

先构建解决方案以准备依赖，再临时对 CAP 项目启用 XML 文档检查：

dotnet build PlumX.Core/PlumX.Core.sln
dotnet build PlumX.Core/Core/PlumX.Core.CAP/PlumX.Core.CAP.csproj --no-restore --no-incremental -p:BuildProjectReferences=false -p:GenerateDocumentationFile=true

此检查不持久修改项目配置，不关闭 CS1591，也不将文档检查扩展到全部历史项目；其他编译告警仍需分别处理。