PlumX.Core.CAP 1.0.0-preview.7

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、Newtonsoft.Json、PlumX.Core.Common

按 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
    },
    "WxMsgOption": {
      "WxApiUrl": "",
      "CapFailWxTemplateId": "",
      "FailWeixinNumber": "",
      "FailSendWxMsgOpenIds": []
    }
  }
}

• 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 默认行为。
• WxMsgOption：可选的失败通知配置。仅在包含 OpenId 列表时调用 WxApiUrl；不得把 URL、模板标识或接收者信息写入公开示例。

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

边界

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

完整使用示例

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