Healnet.Infrastructure
6.10.0
dotnet add package Healnet.Infrastructure --version 6.10.0
NuGet\Install-Package Healnet.Infrastructure -Version 6.10.0
<PackageReference Include="Healnet.Infrastructure" Version="6.10.0" />
<PackageVersion Include="Healnet.Infrastructure" Version="6.10.0" />
<PackageReference Include="Healnet.Infrastructure" />
paket add Healnet.Infrastructure --version 6.10.0
#r "nuget: Healnet.Infrastructure, 6.10.0"
#:package Healnet.Infrastructure@6.10.0
#addin nuget:?package=Healnet.Infrastructure&version=6.10.0
#tool nuget:?package=Healnet.Infrastructure&version=6.10.0
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 | Versions 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. |
-
net10.0
- Aliyun.OSS.SDK.NetCore (>= 2.14.1)
- AspectCore.Core (>= 3.0.0)
- AspectCore.Extensions.DependencyInjection (>= 3.0.0)
- Azure.AI.OpenAI (>= 2.9.0-beta.1)
- Consul (>= 1.8.0)
- Cronos (>= 0.13.0)
- Google.Api.CommonProtos (>= 2.17.0)
- Google.Protobuf (>= 3.36.2)
- Grpc.AspNetCore (>= 2.85.0)
- Grpc.AspNetCore.HealthChecks (>= 2.85.0)
- Grpc.Net.Client (>= 2.85.0)
- Healnet.Common (>= 5.3.1)
- Healnet.Core (>= 6.1.0)
- Microsoft.AspNetCore.Authentication.JwtBearer (>= 10.0.15)
- Microsoft.AspNetCore.Grpc.JsonTranscoding (>= 10.0.15)
- Microsoft.Extensions.AI (>= 10.11.0)
- Microsoft.Extensions.AI.OpenAI (>= 10.11.0)
- Microsoft.Extensions.Caching.Memory (>= 10.0.15)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.15)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Diagnostics.HealthChecks (>= 10.0.15)
- Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Http.Polly (>= 10.0.15)
- Microsoft.Extensions.Logging (>= 10.0.15)
- Milvus.Client (>= 3.0.0)
- MongoDB.Driver (>= 3.14.0)
- NEST (>= 7.17.5)
- OpenTelemetry.Exporter.Console (>= 1.21.0)
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.21.0)
- OpenTelemetry.Exporter.Zipkin (>= 1.21.0)
- OpenTelemetry.Extensions.Hosting (>= 1.21.0)
- OpenTelemetry.Instrumentation.AspNetCore (>= 1.21.0)
- OpenTelemetry.Instrumentation.Http (>= 1.21.0)
- Oracle.ManagedDataAccess.Core (>= 23.26.401)
- Polly (>= 8.9.1)
- Polly.RateLimiting (>= 8.9.1)
- RabbitMQ.Client (>= 6.8.0)
- Serilog.AspNetCore (>= 10.0.0)
- Serilog.Extensions.Hosting (>= 10.0.0)
- Serilog.Sinks.Console (>= 6.1.1)
- Serilog.Sinks.File (>= 7.0.0)
- Serilog.Sinks.OpenSearch (>= 2.0.0)
- SqlSugar.ClickHouseCore (>= 5.1.4.201)
- SqlSugarCore (>= 5.1.4.221)
- StackExchange.Redis (>= 3.4.35)
- Swashbuckle.AspNetCore.SwaggerGen (>= 6.5.0)
- Swashbuckle.AspNetCore.SwaggerUI (>= 6.5.0)
- System.DirectoryServices.Protocols (>= 10.0.15)
- System.Drawing.Common (>= 10.0.15)
- System.IdentityModel.Tokens.Jwt (>= 8.23.0)
- Winton.Extensions.Configuration.Consul (>= 3.4.0)
- Yarp.ReverseProxy (>= 2.3.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 |
|---|---|---|
| 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 |
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 路径仅新增装配诊断日志)。