Healnet.Infrastructure 6.10.0

dotnet add package Healnet.Infrastructure --version 6.10.0
                    
NuGet\Install-Package Healnet.Infrastructure -Version 6.10.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Healnet.Infrastructure" Version="6.10.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Healnet.Infrastructure" Version="6.10.0" />
                    
Directory.Packages.props
<PackageReference Include="Healnet.Infrastructure" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Healnet.Infrastructure --version 6.10.0
                    
#r "nuget: Healnet.Infrastructure, 6.10.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Healnet.Infrastructure@6.10.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Healnet.Infrastructure&version=6.10.0
                    
Install as a Cake Addin
#tool nuget:?package=Healnet.Infrastructure&version=6.10.0
                    
Install as a Cake Tool

Healnet.Infrastructure 基础设施层

版本: 6.10.0 | 依赖: Healnet.Core → Healnet.Common | TFM: net10.0 | License: MIT

Healnet.Infrastructure 是 Healnet 微服务框架的基础设施实现层:对 28 个中间件/基础设施组件提供统一封装与 DI 注册约定,实现 Healnet.Core 定义的抽象契约(ICacheService、IUnitOfWork、ITokenService、IHttpClientService、IConsulService、ISessionChatClient 等)。契约在 Core、实现在本层(DIP);AI 抽象位于 Healnet.Core.AI / Healnet.Core.AI.Memory,本层 AI/ 仅含实现。

安装与最小接入

dotnet add package Healnet.Infrastructure
// Program.cs —— 业务服务推荐的两行入口(Service Defaults)
builder.AddHealnetServiceDefaults();   // 日志 / Consul / gRPC 转码 / MVC / JWT / 健康检查 / Swagger / Kestrel
// ...
app.UseHealnetServiceDefaults();       // 请求日志 → 全局异常 → CorrelationId → 认证授权 → 端点映射 → Consul 注册

按需细粒度接入时,各模块独立 AddXxx(见下表),配置节点统一约定在 Healnet:<模块>。

模块目录

模块 一句话定位 README
Extensions 聚合注册入口 + Service Defaults(推荐接入点) Extensions/README.md
Authentication JWT 令牌 + API Key 认证 Authentication/README.md
Security 安全响应头 + CORS Security/README.md
SqlSugar ORM:多库连接 + 泛型仓储 SqlSugar/README.md
UnitOfWork SqlSugar 事务工作单元 UnitOfWork/README.md
MongoDB 多租户文档数据库 MongoDB/README.md
ElasticSearch NEST 全文搜索封装 ElasticSearch/README.md
Milvus 向量数据库(ANN 检索) Milvus/README.md
Redis 分布式缓存 + Lua 分布式锁(含 IRedisDatabaseFactory 多库访问) Redis/README.md
RabbitMQ 消息队列(发布/订阅/死信) RabbitMQ/README.md
OSS 阿里云对象存储(IFileService 实现) OSS/README.md
Consul 服务注册/发现/健康检查 Consul/README.md
Http HttpClient + Polly 弹性 + Consul 发现 Http/README.md
YARP API 网关(静态路由/Consul 动态发现) YARP/README.md
gRPC 通道缓存 + 强类型客户端封装 gRPC/README.md
Logging Serilog 结构化日志 Logging/README.md
OpenTelemetry Tracing/Metrics/Logging 三件套 OpenTelemetry/README.md
HealthChecks 多组件健康检查(统一 JSON) HealthChecks/README.md
Middleware 请求日志 / 关联 ID 中间件 Middleware/README.md
Resilience Polly 重试/熔断/限流策略 Resilience/README.md
Background Cron 后台任务基类(Cronos 调度,不引 Quartz/Hangfire) Background/README.md
EventBus 领域事件进程内分发 + Outbox 可靠投递(at-least-once) EventBus/README.md
AOP AspectCore 内置拦截器族 AOP/README.md
Swagger API 文档(含 gRPC Transcoding 文档) Swagger/README.md
AI MEAI 统一会话链路 + 记忆分层 AI/README.md
Skill Skill 模板加载/解析/渲染(一句话 README) Skill/README.md
Helpers gRPC 客户端 IP 提取等静态助手(一句话 README) Helpers/README.md
Mvc 模型校验统一 ApiResponse(一句话 README) Mvc/README.md

gRPC 客户端完整调用案例(多层嵌套消息 / 流式 / Swagger JSON 对照)见 Swagger/GRPC_EXAMPLE.md。

版本策略

  • 三库(Common / Core / Infrastructure)各自独立发版,不再强制同号:本轮发布 Infrastructure 6.10.0,依赖 Common 5.3.1 与 Core 6.1.0(三者当前版本号见各自 README 首行);本次未改 Common / Core 代码,二者不发版。PackageReleaseNotes 逐版本记录缺陷修复与兼容性说明,历史明细用 git log 追溯。
  • 破坏性变更集中在主版本(3.0 / 5.0);4.x 内的 DI 生命周期调整等行为变化均在该版本 ReleaseNotes 中显式标注兼容性。

架构约定(精简版)

  • 契约在 Core,实现在 Infrastructure:本层各模块 README 顶部均标注对应的 Core 抽象来源。
  • OSS 替换 Common 的 IFileService:AddAliyunOssFileService 经 services.Replace 切换实现。
  • 过时成员已标 [Obsolete]:如 Middleware 的 UseExceptionHandling / UseHealthCheck,替代指引见各模块 README「⚠️ 常见坑」。
  • 各模块 README 只保留「快速上手」:一句话定位 + 3 步接入 + 最小配置 + 常见坑;API 签名细节看代码 IntelliSense(包内随带 XML 注释)。
Product Compatible and additional computed target framework versions.
.NET 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
6.10.0 34 11/18/2026
6.9.0 47 11/18/2026
6.8.0 49 11/18/2026
6.7.0 42 11/18/2026
6.6.0 49 11/18/2026
6.5.0 49 11/17/2026
6.4.0 63 11/12/2026
6.3.0 59 11/12/2026
6.2.0 67 11/11/2026
6.1.0 63 11/11/2026
6.0.1 65 11/10/2026
6.0.0 80 11/5/2026
5.3.0 68 11/5/2026
5.2.0 58 11/5/2026
5.1.1 64 11/5/2026
5.1.0 58 11/5/2026
5.0.0 72 11/4/2026
4.0.40 68 11/4/2026
4.0.39 65 11/4/2026
4.0.38 65 11/3/2026
Loading failed

v6.10.0: Redis 多库访问 + DefaultDatabase 语义修正(无破坏性 API 变更;仅一处可选迁移)。① 新增 Redis 多库访问(IRedisDatabaseFactory):ForDatabase(db) / Default 返回 IRedisDatabaseScope(Database / Cache / Locks / Idempotency / FeatureFlags 五成员,四类能力全部作用于同一个库),同一进程内可同时访问 db3 / db4;作用域复用同一个 IConnectionMultiplexer(绝不按库新建连接),同库多次调用返回同一实例(ConcurrentDictionary + Lazy 把创建收敛为一次),Cluster 探测结果按需缓存。约束:仅单机/主从支持 0-15,Cluster 只有 db0——ForDatabase 越界抛 ArgumentOutOfRangeException,探测到 Cluster 连接且库索引非 0 抛 NotSupportedException(探测失败一律视为非集群,不阻塞正常路径);默认库路径(DI 注入的 IRedisService / IDistributedLockService 等)方法签名与行为零变化。② RedisOptions.DefaultDatabase 由 int(默认值 0)改为 int?(无默认值):修复「连接串里显式写 defaultDatabase=n 却被无条件覆盖回 0」的缺陷——原实现每次构造 ConfigurationOptions 后都用 options.DefaultDatabase 覆盖,未配置时也覆盖为 0。新优先级:配置项 Healnet:Redis:DefaultDatabase > 连接串 defaultDatabase= > StackExchange.Redis 默认 0;仅在 HasValue 时覆盖,IConfiguration 重载直接透传可空值。迁移提示:把 options.DefaultDatabase 赋给 int 变量的代码需补 .Value 或 ?? 0(该属性无默认值,未配置时为 null);若配置文件里显式写了 "DefaultDatabase": 0,它会覆盖连接串取值,建议二者只写一处(仓库三个 examples 模板中原有的该行已删除,改为注释说明)。③ 修复 RedisService.ClearAsync 在多库作用域下会 flush 到默认库的问题:绑定库时走 FlushDatabaseAsync(db),未绑定仍走无参 FlushDatabaseAsync(默认库路径行为保持不变);修复 GetKeysByPatternAsync 跨库扫描导致 RemoveByPatternAsync 落空的问题(SCAN 改由绑定库对应的 IServer 执行,默认库路径行为不变)。④ 语义约束提醒:跨库无原子性(Redis 无跨库事务、无跨库 Lua),分布式锁必须与它保护的数据同库、幂等键同理;ClearAsync 只清当前库,多库清理需按作用域逐个调用;Pub/Sub 频道是连接级全局的,不区分库,需要隔离请用 channel 命名前缀。⑤ 测试基线:单测 571/571 全过、E2E 49/49 全过(2026-11-18 全量测试报告);其中 Redis 相关 60/60。⑥ 依赖 Healnet.Common [5.3.1,) 不变;本次未改 Common / Core 代码,二者不发版。 v6.9.0: 三项批次(多桶 OSS 新特性 + AspectCore 3 升级 + 死依赖清理)。① 新增多桶对象存储体系(OSS/MultiBucket,并行于既有单桶 IFileService,零既有文件修改):AliyunBucketFileService 单桶实现(签名对齐 IFileService,复刻既有 StripBucketPrefixIfPresent/ForceHttps 历史修复);AliyunMultiBucketStorageService——OssClient 按 endpoint+AK 去重缓存,同端点跨桶走服务端 CopyObject,跨 region/账号自动降级流式中转,endpoint 统一规范为纯 host;MultiBucketServiceCollectionExtensions.AddMultiBucketStorage 两重载(有参/无参配置节),注册即 fail-fast 校验,TryAddSingleton 不触碰既有 IFileService 注册,默认配置节 Healnet:FileStorage:MultiBucket,桶级配置可覆盖全局 endpoint/AK/SK/BaseUrl。契约面位于 Healnet.Common 5.3.1(IBucketFileService/IMultiBucketStorageService/MultiBucketStorageOptions/BucketConfig;注意该契约 5.3.0 程序集已包含但 5.3.0 说明漏记,5.3.1 为说明订正版)。回归:MultiBucketStorageTests 18/18(配置校验/继承解析/实例缓存/别名大小写归一/BucketName 回退/前缀剥离/公共 URL 拼装/DI 注册)。② AspectCore.Core/AspectCore.Extensions.DependencyInjection 2.4.0 → 3.0.0:编译/单测零改动——3.0.0 破坏面仅 TFM ≥ net6.0 与 LangVersion C# 13(本仓库 net10.0 / C# 14 均满足),在用 API(ConfigureDynamicProxy/IAspectConfiguration/NonAspectPredicates/Interceptors.AddTyped/AbstractInterceptor)无重命名;附带收益为内置 DI 容器修复(#331/#271/#254)与 keyed service 拦截支持;AOP 拦截器回归 22/22 通过。③ 移除死依赖 System.Interactive.Async(原 6.0.1,全仓库零代码引用,未升级而直接删除);消费方若在自己的代码中使用该包请自行引入 7.x 线。依赖 Healnet.Common [5.3.1,)。测试基线:单测 536/536 全过、E2E 49/49 全过(2026-11-18 全量测试报告)。 v6.8.0: 存储驱动升级:StackExchange.Redis 2.9.11 → [3.4.35,)。① 编译面仅 1 处适配:StringSetAsync(key, value, TimeSpan?) 3 参重载被 Expiration 类型取代(RedisService.SetAsync 已修复;Expiration 有 TimeSpan 隐式转换,仅 TimeSpan? 不适用;带 When 的 4/5 参重载仍在,DistributedLockService/RedisIdempotencyStore 零改动)。② 行为级变更:RESP3 默认化——Redis server ≥ 6.0 时客户端协商 RESP3(低于 6.0 自动回落 RESP2);本仓库 ScriptEvaluateAsync 均为简单 Lua(SET NX 锁/幂等,返回 integer),RESP3 结果形状变更不影响;若消费方直接使用 ExecuteAsync/ScriptEvaluateAsync 处理复杂返回结构(map/double/bool 等 RESP3 新类型),请自查结果解析。③ I/O 核心重写(reader 式解析器 + 库内缓冲控制),大回复场景吞吐显著提升。④ RabbitMQ.Client 维持 6.8.0(7.x 移除全部同步 API,重写级专项另行排期;6.x 已 EOL)。⑤ 无破坏性 API 变更,消费方直接升级即可。 v6.7.0: 存储驱动升级批次。① MongoDB.Driver 2.29.0 → [3.14.0,):编译/单测零改动通过——在用面仅核心稳定 API(MongoClient/GetCollection/Builders/JsonCommand ping),避开 3.x 移除面(LINQ2/IMongoQueryable/MongoDB.Driver.Core 拆分/旧 GUID 模式)。部署前提:driver 3.10+ 要求 MongoDB server ≥ 4.4(已核实部署满足);3.x 默认 GUID 序列化固定 V3 模式,消费方若有 Mongo 实体用 Guid 主键需自查。② Milvus.Client 2.3.0-preview.1 → 3.0.0(V1 SDK,官方 maintenance mode):编译/单测零改动通过——V1 3.0.0 保留旧 API 面(SimilarityMetricType 等),proto 向后兼容(新 SDK 可连旧 server)。注意:V1 不再加新功能,长期应迁 Milvus.Client.V2(API 面完全不同,重写级专项);部署侧需与实际 Milvus server 版本组合冒烟验证。③ 无破坏性 API 变更,消费方直接升级即可。 v6.6.0: 修复:AddApiKeyAuth 配置缺失不再阻塞进程启动(行为变更)。① 此前 Healnet:ApiKeyAuth 配置节缺失或 ApiKey 为空时,AuthenticationExtensions.cs 直接抛 InvalidOperationException(节缺失 / API Key 未配置两处硬抛),进程无法启动——对"运行时才注入 ApiKey"或"仅依赖 CustomTokenResolver(绑定码/session token 等动态凭据)"的消费方是硬阻塞。② 现改为:缺配置时用默认选项照常注册 ApiKey 方案 + PostConfigure 阶段打 Warning("静态比对未激活"),Handler 侧检测到 ApiKey 为空即显式跳过静态比对(FixedTimeEquals 对空串本就返回 false,显式短路固化语义);CustomTokenResolver 动态凭据路径完全不受影响,无 Resolver 时 Bearer token 认证失败(安全底线不变:不会意外放行)。③ 升级注意:此前依赖"配置缺失即启动失败"做 fail-fast 防呆的消费方,请改用启动后检查 Warning 日志或自行校验配置。新增回归测试 ApiKeyAuthMissingConfigTests(5 例:节缺失/空 Key 不抛 + Warning 断言 + CustomTokenResolver 路径 + 安全底线)。 v6.5.0: 依赖抬升批次(net10 线内)+ 升级适配修复两处。① 依赖:M.E.*/M.A.* 浮动下限 → [10.0.15,)、M.E.AI(.OpenAI) → [10.11.0,)、Serilog → [4.4.0,)、Jwt → [8.23.0,);钉版:SqlSugarCore 5.1.4.215→5.1.4.221(ClickHouse .1→.201)、Polly(.RateLimiting) 8.3.0→8.9.1、gRPC 四件套 2.65/2.66→2.85、Google.Protobuf 3.27.2→3.36.2(CommonProtos 2.15.0→2.17.0)、Oracle.ManagedDataAccess.Core 23.8.0→23.26.401、Consul 1.7.14.1→1.8.0、Yarp 2.2.0→2.3.0、NEST 7.17.5、Serilog.Sinks.OpenSearch 2.0.0、OTel 六件套 1.7.0→1.21.0、MiniExcel 1.47.1、ClosedXML [0.105.1,0.106.0)、Aliyun.OSS 2.14.1。② 升级适配修复(真实缺陷):ServiceDefaultsExtensions.MapAllDiscoveredGrpcServices 反射取 MapGrpcService 改为按「单参 IEndpointRouteBuilder 泛型定义」精确筛选——gRPC 2.85 新增重载后无参 GetMethod 抛 AmbiguousMatchException,此前该扩展方法在 gRPC 2.85 下服务映射直接崩溃;Consul 1.8.0 适配为内部行为(ServiceRegister 1-arg 由扩展方法变接口重载,注册逻辑等价,无需消费方改动)。③ 已知告警:AddZipkinExporter CS0618(OTel 1.21 标记废弃,下批仿 Jaeger 模式映射到 OTLP 后移除)。④ RabbitMQ 7/MongoDB 3/StackExchange.Redis 3/Swashbuckle 11 等跨主版本升级另行专项。 v6.2.0: 手写管线等价入口。① 背景:6.1.0 已把 gRPC 标准健康服务(grpc.health.v1.Health)三件套收编进 Service Defaults,但不走 ServiceDefaults 的手写管线(自行 AddGrpc/MapGrpcService/ConfigureKestrel/UseConsul 的服务)仍需自行拼装——漏掉 HealthCheckPublisherOptions.Delay=0(启动盲窗,Consul 首轮 GRPC 探测 critical 一次)或 self 兜底(零条目报告经 gRPC 映射解析为 Unknown,探测恒 critical)就会踩回 6.1.0 修复前的坑。② 新增三入口(幂等防重):AddHealnetConsulGrpcHealth()——收编三件套(官方 AddGrpcHealthChecks + Delay=0 + 恒 Healthy self 检查)并内置 AddGrpc() 保障(MapGrpcService* 映射时校验官方 GrpcMarkerService,缺失即抛 InvalidOperationException,此前 gRPC/README 给出的手工配方即含此坑);UseHealnetConsulGrpcHealth()——映射 /grpc.health.v1.Health/{Check,Watch} + 装配诊断(漏调 Add 侧记 Error、GrpcHealthCheckEnabled=true 但缺 GrpcPort 记 Warning);AddHealnetGrpcKestrelPorts()——Service Defaults Kestrel 双端口策略等价形态(读 Healnet:Consul:ServicePort/GrpcPort,双端口 HTTP + HTTP/2 Only,单端口退化记 Error),enableGrpc 缺省自动探测入口程序集。③ ServiceDefaultsExtensions 同源重构:Add 侧 3.1 与第 9 步、Use 侧健康映射改为调用同一实现,两条路径字面等价。④ 新增 Healnet.Example.HandwrittenGrpc 手写管线参考模板(ProjectReference 直引本地源码,便于发布前 E2E 直接验证;复制到外部解决方案按 csproj 注释换 NuGet 包引用)+ E2E 用例(含裸 gRPC wire Health/Check → SERVING 断言)。无破坏性行为变更(纯新增 API + ServiceDefaults 内部同源重构,ServiceDefaults 路径仅新增装配诊断日志)。