Healnet.Infrastructure
6.7.0
See the version list below for details.
dotnet add package Healnet.Infrastructure --version 6.7.0
NuGet\Install-Package Healnet.Infrastructure -Version 6.7.0
<PackageReference Include="Healnet.Infrastructure" Version="6.7.0" />
<PackageVersion Include="Healnet.Infrastructure" Version="6.7.0" />
<PackageReference Include="Healnet.Infrastructure" />
paket add Healnet.Infrastructure --version 6.7.0
#r "nuget: Healnet.Infrastructure, 6.7.0"
#:package Healnet.Infrastructure@6.7.0
#addin nuget:?package=Healnet.Infrastructure&version=6.7.0
#tool nuget:?package=Healnet.Infrastructure&version=6.7.0
Healnet.Infrastructure 基础设施层
版本: 5.0.0 | 依赖: Healnet.Core → Healnet.Common | TFM: net10.0 | License: MIT
Healnet.Infrastructure 是 Healnet 微服务框架的基础设施实现层:对 26 个中间件/基础设施组件提供统一封装与 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 分布式锁 | 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 |
| 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)统一版本号发布;
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 (>= 2.4.0)
- AspectCore.Extensions.DependencyInjection (>= 2.4.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.2.0)
- 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 (>= 2.9.11)
- 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)
- System.Interactive.Async (>= 6.0.1)
- 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.11.0 | 31 | 11/19/2026 |
| 6.10.0 | 51 | 11/18/2026 |
| 6.9.0 | 51 | 11/18/2026 |
| 6.8.0 | 51 | 11/18/2026 |
| 6.7.0 | 44 | 11/18/2026 |
| 6.6.0 | 51 | 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 | 66 | 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 |
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 路径仅新增装配诊断日志)。