Mud.Wechat.OfficialAccount.Callback
1.0.0
dotnet add package Mud.Wechat.OfficialAccount.Callback --version 1.0.0
NuGet\Install-Package Mud.Wechat.OfficialAccount.Callback -Version 1.0.0
<PackageReference Include="Mud.Wechat.OfficialAccount.Callback" Version="1.0.0" />
<PackageVersion Include="Mud.Wechat.OfficialAccount.Callback" Version="1.0.0" />
<PackageReference Include="Mud.Wechat.OfficialAccount.Callback" />
paket add Mud.Wechat.OfficialAccount.Callback --version 1.0.0
#r "nuget: Mud.Wechat.OfficialAccount.Callback, 1.0.0"
#:package Mud.Wechat.OfficialAccount.Callback@1.0.0
#addin nuget:?package=Mud.Wechat.OfficialAccount.Callback&version=1.0.0
#tool nuget:?package=Mud.Wechat.OfficialAccount.Callback&version=1.0.0
Mud.Wechat.OfficialAccount.Callback
微信公众号 / 服务号 SDK 回调接收包:URL 验证(GET echostr 回显)、消息与事件推送接收(明文 / 兼容 / 安全三模式)、双验签、appid 一致性校验、抗重放、类型化事件分发与拦截器、被动回复(明文或加密 XML 回写)的 HTTP 中间件与多应用路由。
密码学与抗重放内核在叶层 Mud.Wechat.Abstractions(WechatCallbackCrypto / IWechatCallbackReplayGuard / WechatCallbackTypeRegistry<T> / WechatCallbackRouteKeys),与企业微信线共用同一份实现——同一件事只有一份事实来源(守卫 CB-L1d / CB-L1i 锁定「下沉物唯一性」,产品线内不得留副本)。
配置面
MpCallbackOptions(节 MpCallback)——Apps 字典是凭据的唯一来源(公众号应用配置 MpAppConfig 不提供推送属性):
| 属性 | 默认 | 说明 |
|---|---|---|
GlobalRoutePrefix |
mp |
路由 /{prefix}/{AppKey};CB-MP-1 锁定默认值,与企微 wechat、支付 pay 不冲突 |
Apps |
{} |
appKey → MpAppCallbackOptions;键可为 WildcardAppKey(叶层通配 "*") |
AllowClockSkewSeconds |
300 |
时效窗(缺失 / 非数字时间戳即拒) |
EventHandlingTimeoutMs |
4000 |
分发软超时,必须 < 5000ms(微信侧契约),超时即放弃等待回包 |
MaxConcurrentEvents |
10 |
并发分发容量 |
MaxRequestBodySize |
1048576 |
请求体上限(1 MB),超限直接拒绝,不进入解密 |
AllowedSourceIPs / TrustedProxies |
[] / false |
源 IP 白名单;TrustedProxies 打开时取转发头判定 |
MpAppCallbackOptions:PushToken / PushEncodingAESKey / AppId / RequireReplayGuard(默认 true)。校验失败统一抛叶层 WechatCallbackException(WechatCallbackFailureKind 映射类别),不因单应用配置错误拖垮全部路由。
用法
builder.Services.AddMpApp(builder.Configuration, "MpApps") // 令牌底座(与业务接口共用)
.AddMpCallback(builder.Configuration) // 惰性 Configure(o => section.Bind(o)),支持热更
.AddHandler<MySubscribeHandler>() // 全局(通配 appKey 桶)
.AddHandler<MyMenuClickHandler>("mp-a") // 仅该 appKey 路由生效
.AddReplyHandler<MyKefuReplyHandler>() // 被动回复(返回式)
.AddInterceptor<MyAuditInterceptor>();
app.UseMpCallback(); // GET 验证 + POST 接收
被动回复处理器返回 MpCallbackReply?(null = 不回复):
public sealed class MyKefuReplyHandler : IMpCallbackReplyHandler
{
public Task<MpCallbackReply?> TryReplyAsync(MpCallbackEnvelope envelope, CancellationToken ct)
=> Task.FromResult<MpCallbackReply?>(
envelope.Event == MpCallbackEventTypes.Subscribe
? MpCallbackReply.Text("欢迎关注") // 亦提供 Image / News(MpNewsArticle) / bodyXml 形态
: null);
}
源 IP 白名单可动态刷新(官方推送服务器 IP 会变):主包侧 AddMpCallbackSourceIpWhitelist(refreshInterval) 注册 IMpCallbackSourceIpProvider + 后台刷新服务,回调侧 MpCallbackSourceIpFilter 消费。
事件载荷体系
- 7 类可分发键集、48 个官方键(
MpCallbackKeys.cs):消息 7 + 事件 13(9 菜单 + 4 通用)+ 卡券 13 + 用户授权变更 3 + 订阅通知 3 + 微信认证 6 + 发送结果 3(群发MASSSENDJOBFINISH+ 模板TEMPLATESENDJOBFINISH/templatesendjobfinish大小写双键并存——官方页无大小写说明)。另有MpCallbackReplyTypes7 种被动回复类型。跨族不得撞键(键全局唯一,撞键会让注册表相互覆盖),数量下限由 CB-MP-4 锁定(防「静默删键」)。 - 载荷 29 个类型(
Abstractions/Callback/Payloads/),按官方报文结构族声明[MpPayloadContract]+[MpCallbackContract];字段映射与登记方法体(MpPayloadContracts.RegisterAll)由Mud.Wechat.Callback.Generator编译期发射——该生成器挂载在 Abstractions 程序集(partial 主体必须与宿主同程序集)。 - 处理器基类
MpCallbackPayloadHandler<TPayload>(抽象类而非「泛型接口 + 显式默认实现」,后者在netstandard2.0报CS8701);SupportedEventType↔ 载荷键集一致性由Mud.Wechat.Callback.Analyzers编译期校验(MUDCB002~005,本包内嵌analyzers/dotnet/cs下发)。 - 未登记键由
GenericCallbackPayload兜底;读取状态经MpPayloadReadStatus/MpPayloadReadResult表达,转换器MpPayloadConverter落 Abstractions(纯转换语义、零 Callback 依赖)。
校验次序(安全属性,不可调序)
- 路由匹配(
/{prefix}/{AppKey};仅前缀段的路径归一为通配键"*")→ 取Apps凭据并Validate。 - GET 验证:按模式验签后回显
echostr,不消费指纹(同一echostr二次保存配置必须成功)。 - POST 接收:时间戳时效窗 → 验签(密文分支必须用 4 参
ComputeSignature,CB-MP-2 锁定;明文分支用 3 参signature)→ 解密(官方 32 字节块 PKCS7 手工剥离,禁用 .NET 内置 16 块PaddingMode.PKCS7,否则误拒官方pad∈[17..32]报文)→ToUserName与本应用AppId交叉校验(MpAppIdCrossChecker,结论按 appKey 缓存一次,避免日志风暴)→ 一次性指纹(RequireReplayGuard)→ 分发。 - 两道闸均 fail-closed:分布式守卫异常必须上抛(触发官方重推),禁止吞异常放行、也禁止
false静默丢事件;不得为兼容降级为 fail-open。 - 被动回复回写:无回复时为明文成功应答(CB-MP-3 锁定回写口径),有回复时按应用模式加密回写。
依赖
Mud.Wechat.OfficialAccount.Abstractions + Mud.Wechat.Abstractions(叶层内核)+ Mud.HttpUtils.Generator 3.0.9(PrivateAssets=all,载荷字段映射)+ 本仓 Mud.Wechat.Callback.Generator / Mud.Wechat.Callback.Analyzers(均 OutputItemType=Analyzer、PrivateAssets=all,前者不打包、后者随本包 analyzers/dotnet/cs 内嵌下发)。
netstandard2.0 用 Microsoft.AspNetCore.Http / .Http.Abstractions 2.3.9,net6.0+ 用 FrameworkReference Microsoft.AspNetCore.App。中间件为经典约定式 RequestDelegate(不进 DI),由宿主 UseWechatWebhook 风格的 UseMpCallback() 接入。
硬边界:本包不得引用任何企业微信(Work)程序集,也不得引用本线主包(CB-L1a / CB-L1b 双向锁定);叶层不得引用任何产品线工程(CB-L1c / CB-L1e)。
已踩陷阱
- 双验签口径不同:GET 用 3 参
signature(sort(token, timestamp, nonce),不含echostr);POST 用 4 参msg_signature(含密文)。混用会让安全模式下恒 403。 - 明文模式没有密文可取材 ⇒ 指纹改以「时效参数 + 明文包体」计算传输级摘要(不是签名值),语义与密文模式的一次性指纹等价但取材不同。
- 指纹取材于密文,解密失败不消耗 ⇒ 官方重试可重入;一旦解密 +
appid校验成功即消费,此后同报文重推被拒(处理器须幂等)。 MpCallbackEnvelope.DecryptedXml与PushToken/PushEncodingAESKey/AppId不得进日志、遥测或异常消息。AddMpCallback(IConfiguration, sectionName)重载是惰性Configure(o => section.Bind(o))(支持前缀与凭据请求期热更),勿改回注册期急切绑定。- 载荷契约生成器挂载在 Abstractions 而非本包:
MpPayloadContracts.RegisterAll的 partial 主体必须与宿主同程序集,挂错位置即静默无登记。 - 模板发送结果事件
TEMPLATESENDJOBFINISH与templatesendjobfinish双键并存(官方现网示例为大写、历史资料通行小写),只登记一个会漏事件。
守卫
Tests/Mud.Wechat.OfficialAccount.Callback.Tests/:MpCallbackContractGuards(CB-L1a 纵向依赖 / CB-L1b 反向 / CB-L1f Roslyn 工具中立名 / CB-L1g 去中间层 + CB-MP-1 前缀 / CB-MP-2 验签口径 / CB-MP-3 回写口径 / CB-MP-4 键集下限 / CB-MP-6)、MpAppIdCrossCheckTests(结论缓存与降级)、MpCallbackHandlerAnalyzerTests(MUDCB002~005 逐条)。叶层内核守卫见 Tests/Mud.Wechat.Abstractions.Tests/ContractGuards/WechatCallbackKernelContractGuards.cs(CB-L1c / L1d / L1e / L1h / L1i)。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Microsoft.AspNetCore.Http (>= 2.3.9)
- Microsoft.AspNetCore.Http.Abstractions (>= 2.3.9)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.12)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Options (>= 10.0.12)
- Mud.Wechat.OfficialAccount (>= 1.0.0)
- System.Text.Json (>= 10.0.12)
-
net10.0
- Mud.Wechat.OfficialAccount (>= 1.0.0)
-
net6.0
- Microsoft.Extensions.Configuration.Binder (>= 10.0.12)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Options (>= 10.0.12)
- Mud.Wechat.OfficialAccount (>= 1.0.0)
-
net8.0
- Microsoft.Extensions.Configuration.Binder (>= 10.0.12)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Options (>= 10.0.12)
- Mud.Wechat.OfficialAccount (>= 1.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.0.0 | 127 | 10/29/2026 |