Healnet.Infrastructure 1.7.1

Healnet.Infrastructure 基础设施模块

版本: v1.7.0 | TFM: net10.0 | 依赖: Healnet.Core, Healnet.Common

概述

Healnet.Infrastructure 是 Healnet 微服务框架的基础设施层，对 24+ 个 中间件/基础设施组件进行了统一封装，提供一致的 DI 注册方式与配置约定，业务系统通过简单的 AddXxx 扩展方法即可集成。

v1.7.0 新增功能：

• ✅ Consul 便捷调用 - IConsulHttpClient 自动服务发现 + 负载均衡，UseConsul 一行代码注册服务
• ✅ YARP 配置文件驱动 - AddYarpConsulDiscovery(IConfiguration) 从 appsettings.json 读取服务映射
• ✅ YARP 弹性策略 - AddYarpResilience() 集成 Polly 重试/熔断/限流
• ✅ Swagger gRPC 支持 - gRPC JSON Transcoding，自动将 gRPC 方法映射为 REST HTTP 端点

---

快速导航

类别	模块	注册方法	配置节点	生命周期
认证安全	Authentication	AddJwtAuth(...)	Healnet:Jwt	Scoped/Singleton
认证安全	Security	AddSecurityHeaders(...) / AddCorsPolicy(...)	Healnet:Security / Healnet:Cors	Singleton
数据存储	SqlSugar	AddSqlSugar(...)	Healnet:SqlSugar	Singleton
数据存储	MongoDB	手动注册 IMongoClient + IMongoDbContext	自定义	Singleton
数据存储	ClickHouse	AddClickHouse(...)	Healnet:ClickHouse	Scoped
数据存储	ElasticSearch	AddElasticSearch(...)	Healnet:ElasticSearch	Singleton
缓存锁	Redis	AddRedis(...)	Healnet:Redis	Singleton
消息队列	RabbitMQ	手动注册 IConnection + IRabbitMQService	自定义	Singleton
服务发现	Consul	AddConsul(...)	Healnet:Consul	Singleton
HTTP 客户端	Http	AddHttpClientService(...)	Healnet:HttpClient:{name}	Scoped
API 网关	YARP	AddYarpConfigBuilder() / AddYarpConsulDiscovery(...)	代码配置	Transient/Singleton
RPC	gRPC	AddGrpcService(...)	Healnet:gRPC	Singleton
可观测性	Logging	UseHealnetSerilog() / AddSerilog(...)	Healnet:Serilog	Singleton
可观测性	OpenTelemetry	AddHealnetOpenTelemetry(...)	代码配置	Singleton
可观测性	HealthChecks	AddHealnetHealthChecks(...) + MapHealnetHealthChecks()	代码配置	Transient
可观测性	Middleware	UseExceptionHandling() / UseRequestLogging() / UseCorrelationId()	代码配置	Transient
容错	Resilience	AddResilience(...)	代码配置	Singleton
容错	AOP 拦截器	AddAspectCoreWithInterceptors()	代码配置	Scoped
API 文档	Swagger	AddSwagger(...) + UseSwaggerWithUI()	Healnet:Swagger	Singleton
对象存储	OSS	AddAliyunOssFileService(...)	Healnet:FileStorage	Singleton
AI 集成	AI	AddAIServices(...)	Healnet:AI	Scoped
工作单元	UnitOfWork	AddUnitOfWork()	无	Scoped

---

通用入口

对于只需要常用基础服务的场景，提供了快捷注册入口：

// Program.cs
builder.Services.AddHealnetInfrastructure(options =>
{
    options.HttpClientName = "default";
    options.ConsulAddress = "http://consul.healnet.net:8500";
});

// 或仅基础通用服务（Serilog + SnowflakeId）
builder.Services.AddHealnetCommonServices();

---

模块详细说明

1. JWT 认证 (Healnet.Infrastructure.Authentication)

注册方式:

// 方式一：配置委托
builder.Services.AddJwtAuth(options =>
{
    options.SecretKey = "your-32-char-minimum-secret-key!!";
    options.Issuer = "Healnet";
    options.Audience = "Healnet.Api";
    options.AccessTokenExpireMinutes = 60;
    options.RefreshTokenExpireDays = 7;
});

// 方式二：配置文件
builder.Services.AddJwtAuth(builder.Configuration);

// 中间件（必须）
app.UseAuthentication();
app.UseAuthorization();

配置示例 (appsettings.json):

{
  "Healnet": {
    "Jwt": {
      "SecretKey": "your-secret-key-at-least-32-characters-long!!",
      "Issuer": "Healnet",
      "Audience": "Healnet.Api",
      "AccessTokenExpireMinutes": 60,
      "RefreshTokenExpireDays": 7,
      "ValidateIssuer": true,
      "ValidateAudience": true,
      "ValidateLifetime": true,
      "ValidateIssuerSigningKey": true
    }
  }
}

注入服务:

接口	实现	生命周期	用途
JwtHelper	JwtHelper	Scoped	Token 生成及验证
ITokenService	TokenService	Scoped	Token 管理（生成/刷新/撤销）

JwtHelper API:

public class JwtHelper
{
    string GenerateToken(IEnumerable<Claim> claims);  // 生成 JWT Token
    ClaimsPrincipal? ValidateToken(string token);     // 验证 Token
    string? GetClaimValue(string token, string claimType);  // 获取声明值
    long? GetUserId(string token);                    // 获取用户 ID
    string? GetEmail(string token);                   // 获取邮箱
    bool IsTokenValid(string token);                  // Token 是否有效
}

⚠️ SecretKey 必须 ≥ 32 字符，注册时自动校验，不满足会抛出 ArgumentException。

---

2. 安全头与 CORS (Healnet.Infrastructure.Security)

安全头注册:

// 默认安全头（XSS、Frame、HSTS、CSP 等）
builder.Services.AddSecurityHeaders();
app.UseSecurityHeaders();

// 自定义
builder.Services.AddSecurityHeaders(options =>
{
    options.EnableHsts = true;
    options.EnableCsp = true;
    options.ContentSecurityPolicy = "default-src 'self'; script-src 'self' 'unsafe-inline';";
});

// 从配置读取
builder.Services.AddSecurityHeaders(builder.Configuration);
app.UseSecurityHeaders();

配置示例:

{
  "Healnet": {
    "Security": {
      "EnableHsts": true,
      "HstsMaxAgeDays": 365,
      "EnableCsp": false,
      "ContentSecurityPolicy": "default-src 'self';",
      "EnableXssProtection": true,
      "EnableFrameOptions": true,
      "FrameOptionsValue": "DENY"
    }
  }
}

CORS 注册:

// 从配置读取
builder.Services.AddCorsPolicy(builder.Configuration, "DefaultPolicy");
app.UseCorsPolicy("DefaultPolicy");

// 手动配置
builder.Services.AddCorsPolicy("MyPolicy", policy =>
{
    policy.WithOrigins("https://app.example.com")
          .AllowCredentials()
          .WithMethods("GET", "POST");
});

配置示例:

{
  "Healnet": {
    "Cors": {
      "AllowedOrigins": ["https://app.example.com"],
      "AllowedMethods": ["GET", "POST", "PUT", "DELETE"],
      "AllowedHeaders": ["Authorization", "Content-Type"],
      "AllowCredentials": true,
      "PreflightMaxAgeMinutes": 10
    }
  }
}

---

3. SqlSugar ORM (Healnet.Infrastructure.SqlSugar)

注册方式:

// 方式一：连接字符串（默认 MySQL）
builder.Services.AddSqlSugar("Server=192.168.114.213;Database=KP_BRM;Uid=sa;Pwd=xxx;");

// 方式二：配置委托
builder.Services.AddSqlSugar(options =>
{
    options.ConnectionString = "Server=...";
    options.DbType = DbType.SqlServer;
    options.IsAutoCloseConnection = true;
    options.InitKeyType = InitKeyType.Attribute;
});

// 方式三：配置文件
builder.Services.AddSqlSugar(builder.Configuration);

配置示例:

{
  "Healnet": {
    "SqlSugar": {
      "ConnectionString": "Server=192.168.114.213;Database=KP_BRM;Uid=sa;Pwd=xxx;",
      "DbType": "SqlServer",
      "IsAutoCloseConnection": true,
      "InitKeyType": "Attribute"
    }
  }
}

注入服务:

接口	实现	生命周期	用途
ISqlSugarClient	SqlSugarClient	Singleton	ORM 操作（SQL 日志/错误自动上报）

注册实体仓储:

// 单个实体
builder.Services.AddSqlSugarRepository<User>();

// 批量注册
builder.Services.AddSqlSugarRepositories(typeof(User), typeof(Order), typeof(Product));

// 使用
public class UserService
{
    private readonly ISqlSugarRepository<User> _repo;
    public UserService(ISqlSugarRepository<User> repo) => _repo = repo;
}

ISqlSugarRepository<T> 方法:

Task<T> GetByIdAsync(object id);
Task<List<T>> GetAllAsync();
Task<List<T>> GetListAsync(Expression<Func<T, bool>> where);
Task<T> GetSingleAsync(Expression<Func<T, bool>> where);
Task<int> InsertAsync(T entity);
Task<int> InsertRangeAsync(List<T> entities);
Task<int> UpdateAsync(T entity);
Task<int> UpdateRangeAsync(List<T> entities);
Task<int> DeleteByIdAsync(object id);
Task<int> DeleteAsync(Expression<Func<T, bool>> where);
Task<int> CountAsync(Expression<Func<T, bool>> where);
Task<List<T>> PageAsync(int page, int size, Expression<Func<T, bool>> where, ...);

---

4. MongoDB (Healnet.Infrastructure.MongoDB)

MongoDB 模块采用手动 DI 注册方式，提供灵活的多租户上下文。

注册方式:

// 注册 MongoClient
builder.Services.AddSingleton<IMongoClient>(sp =>
    new MongoClient("mongodb://localhost:27017"));

// 注册配置
builder.Services.AddSingleton(new MongoDbContextOptions
{
    DefaultDatabase = "HealnetDB",
    EnableAudit = true,
    TenantDatabases = new List<TenantDatabase>
    {
        new() { TenantId = "tenant1", DatabaseName = "HealnetDB_Tenant1" }
    }
});

// 注册上下文
builder.Services.AddSingleton<IMongoDbContext, MongoDbContext>();

// 注册审计处理
builder.Services.AddSingleton<IAuditHandler, AuditHandler>();

注入服务:

接口	实现	用途
IMongoDbContext	MongoDbContext	数据库上下文，支持多租户、集合获取
IAuditHandler	AuditHandler	审计字段自动设置（CreatedAt/CreatedBy/UpdatedAt/UpdatedBy）

使用示例:

public class UserRepository
{
    private readonly IMongoDbContext _context;

    public UserRepository(IMongoDbContext context) => _context = context;

    public async Task<User> GetById(string id)
    {
        var collection = _context.GetCollection<User>();
        return await collection.Find(u => u.Id == id).FirstOrDefaultAsync();
    }

    public async Task Insert(User user)
    {
        // 审计处理由 AuditHandler 在 MongoDbContext 层自动完成
        var collection = _context.GetCollection<User>();
        await collection.InsertOneAsync(user);
    }
}

---

5. ClickHouse 列式数据库 (Healnet.Infrastructure.ClickHouse)

注册方式:

// 配置委托
builder.Services.AddClickHouse(options =>
{
    options.Host = "192.168.114.206";
    options.Port = 8123;
    options.Database = "analytics";
    options.Username = "default";
    options.Password = "password";
});

// 配置文件
builder.Services.AddClickHouse(builder.Configuration);

// 连接字符串
builder.Services.AddClickHouse("http://192.168.114.206:8123/analytics");

配置示例:

{
  "Healnet": {
    "ClickHouse": {
      "Host": "192.168.114.206",
      "Port": 8123,
      "Database": "analytics",
      "Username": "default",
      "Password": "password",
      "UseSsl": false,
      "ConnectionTimeout": 30,
      "CommandTimeout": 300,
      "BatchSize": 1000
    }
  }
}

注入服务:

接口	实现	生命周期	用途
IClickHouseService	ClickHouseService	Scoped	查询、批量插入（多行 VALUES）、执行 DDL

核心 API:

Task<IEnumerable<T>> QueryAsync<T>(string sql, object? parameters = null);
Task<int> ExecuteAsync(string sql, object? parameters = null);
Task BulkInsertAsync<T>(string tableName, IEnumerable<T> data);  // 多行 VALUES 优化

---

6. ElasticSearch (Healnet.Infrastructure.ElasticSearch)

注册方式:

// 配置委托
builder.Services.AddElasticSearch(options =>
{
    options.Uri = "http://192.168.114.206:9200";
    options.DefaultIndex = "healnet-logs";
    options.Username = "elastic";
    options.Password = "password";
});

// 配置文件
builder.Services.AddElasticSearch(builder.Configuration);

配置示例:

{
  "Healnet": {
    "ElasticSearch": {
      "Uri": "http://192.168.114.206:9200",
      "DefaultIndex": "healnet-logs",
      "Username": "elastic",
      "Password": "password",
      "EnableSniffing": false,
      "TimeoutSeconds": 30,
      "ConnectionLimit": 10
    }
  }
}

注入服务:

接口	实现	用途
IElasticClient	ElasticClient (NEST)	ElasticSearch 低级客户端
IElasticSearchService	ElasticSearchService	全文搜索、聚合查询封装

---

7. Redis 缓存与分布式锁 (Healnet.Infrastructure.Redis)

注册方式:

// 配置委托
builder.Services.AddRedis(options =>
{
    options.Configuration = "192.168.114.206:6379,password=xxx,defaultDatabase=0";
    options.InstanceName = "MyApp";
    options.KeyPrefix = "MyApp:";
});

// 配置文件
builder.Services.AddRedis(builder.Configuration);

配置示例:

{
  "Healnet": {
    "Redis": {
      "Configuration": "192.168.114.206:6379,password=xxx,defaultDatabase=0",
      "InstanceName": "Healnet",
      "KeyPrefix": "Healnet:",
      "ConnectTimeout": 5000,
      "SyncTimeout": 5000,
      "AbortOnConnectFail": false,
      "DefaultDatabase": 0,
      "PoolSize": 10
    }
  }
}

注入服务:

接口	实现	生命周期	用途
IConnectionMultiplexer	ConnectionMultiplexer	Singleton	Redis 连接
IRedisService / ICacheService	RedisService	Singleton	缓存读写、模式匹配、TTL
IDistributedLockService	DistributedLockService	Singleton	分布式锁（SETNX + Lua 原子释放）

IRedisService 核心 API:

// ICacheService 基础方法
Task SetAsync<T>(string key, T value, TimeSpan? expiry = null);
Task<T?> GetAsync<T>(string key);
Task<T?> GetOrSetAsync<T>(string key, Func<Task<T>> factory, TimeSpan? expiry = null);
Task RemoveAsync(string key);
Task<bool> ExistsAsync(string key);

// IRedisService 扩展方法
Task RefreshAsync(string key, TimeSpan expiry);         // 刷新过期时间
Task<List<string>> GetKeysByPatternAsync(string pattern); // SCAN 模式匹配
Task RemoveByPatternAsync(string pattern);               // 批量删除（Pipeline）
Task ClearAsync();                                       // FLUSHDB（危险操作）
Task<long> GetTtlAsync(string key);                      // 剩余 TTL（秒）
string KeyPrefix { get; set; }                           // 键前缀（默认 "Healnet:"）

IDistributedLockService 核心 API:

Task<bool> AcquireLockAsync(string key, TimeSpan expiry);  // 获取锁（SETNX）
Task ReleaseLockAsync(string key);                         // 释放锁（Lua 原子校验）
Task<T?> ExecuteWithLockAsync<T>(string key, TimeSpan expiry, Func<Task<T>> action, T? defaultValue = default);
Task<bool> ExecuteWithLockAsync(string key, TimeSpan expiry, Func<Task> action);
Task<bool> TryAcquireLockAsync(string key, TimeSpan expiry, int maxRetryCount = 3, TimeSpan? retryDelay = null);

🔒 安全特性: 释放锁使用 Lua 脚本 GET + DEL 原子校验锁值，防止误删他人持有的锁；锁值通过 AsyncLocal 上下文隔离存储。

---

8. RabbitMQ 消息队列 (Healnet.Infrastructure.RabbitMQ)

注册方式:

// 注册 RabbitMQ 连接
builder.Services.AddSingleton<IConnection>(sp =>
{
    var factory = new ConnectionFactory
    {
        HostName = "192.168.114.206",
        UserName = "guest",
        Password = "guest",
        VirtualHost = "/"
    };
    return factory.CreateConnection();
});

// 注册服务
builder.Services.AddSingleton<IRabbitMQService, RabbitMQService>();

注入服务:

接口	实现	生命周期	用途
IRabbitMQService	RabbitMQService	Singleton	消息发布、订阅、队列/交换机管理

核心 API:

// 消息发布
void Publish<T>(string exchange, string routingKey, T message);
Task PublishAsync<T>(string exchange, string routingKey, T message);

// 消息订阅
void Subscribe<T>(string queue, Func<T, Task> handler);
Task SubscribeAsync<T>(string queue, Func<T, Task> handler);

// 队列管理
void DeclareQueue(string queue, bool durable = true, bool exclusive = false, bool autoDelete = false);
void DeclareExchange(string exchange, string type = "direct");
void BindQueue(string queue, string exchange, string routingKey);
void PurgeQueue(string queue);
void DeleteQueue(string queue);
void DeleteExchange(string exchange);
bool IsConnected { get; }
void Initialize();

---

9. Consul 服务发现 (Healnet.Infrastructure.Consul)

注册方式:

// 直接指定地址
builder.Services.AddConsul("http://consul.healnet.net:8500");

// 配置委托
builder.Services.AddConsul(options =>
{
    options.Address = "http://consul.healnet.net:8500";
});

// 配置文件
builder.Services.AddConsul(builder.Configuration);

配置示例:

{
  "Healnet": {
    "Consul": {
      "Address": "http://consul.healnet.net:8500"
    }
  }
}

注入服务:

接口	实现	生命周期	用途
IConsulService	ConsulService	Singleton	服务注册、发现、KV 存储、健康检查

---

10. HTTP 客户端 (Healnet.Infrastructure.Http)

内置 重试（指数退避 2^n 秒）、熔断（阈值 5 次/30 秒）、超时（30 秒）三种 Polly 策略。

注册方式:

// 最简
builder.Services.AddHttpClientService();

// 带 BaseAddress
builder.Services.AddHttpClientService(client =>
{
    client.BaseAddress = new Uri("https://api.example.com");
    client.DefaultRequestHeaders.Add("Accept", "application/json");
});

// 自定义弹性策略
builder.Services.AddHttpClientService(
    client => client.BaseAddress = new Uri("https://api.example.com"),
    options =>
    {
        options.MaxRetries = 5;
        options.TimeoutSeconds = 60;
        options.CircuitBreakerThreshold = 10;
    });

// 泛型客户端
builder.Services.AddHttpClientService<IMyApiClient, MyApiClient>("my-api");

// 从配置读取（支持 Consul 服务发现集成）
builder.Services.AddHttpClientService(builder.Configuration, "default");

注入服务:

接口	实现	生命周期	用途
IHttpClientService	HttpClientService	Scoped	HTTP 调用（GET/POST/PUT/DELETE）
IHttpClientFactoryService	HttpClientFactoryService	Singleton	HttpClient 工厂

配置示例:

{
  "Healnet": {
    "HttpClient": {
      "default": {
        "BaseAddress": "https://api.example.com",
        "TimeoutSeconds": 30,
        "MaxRetries": 3,
        "CircuitBreakerThreshold": 5,
        "CircuitBreakerDurationSeconds": 30,
        "EnableConsulIntegration": false
      }
    }
  }
}

弹性策略 Builder 扩展（用于其他 IHttpClientBuilder）:

services.AddHttpClient<ISomeClient, SomeClient>()
    .AddResiliencePolicies()              // 三合一（重试+熔断+超时）
    .AddRetryPolicy(maxRetries: 5)        // 仅重试
    .AddCircuitBreakerPolicy(10, 60)      // 仅熔断
    .AddTimeoutPolicy(seconds: 60);       // 仅超时

---

11. YARP API 网关 (Healnet.Infrastructure.YARP)

静态路由:

builder.Services.AddReverseProxy();
builder.Services.AddYarpConfigBuilder();

// 代码配置
builder.Services.AddYarpStaticConfig(options =>
{
    options.Routes.Add(new YarpRoute
    {
        RouteId = "api-route",
        ClusterId = "api-cluster",
        MatchPath = "/api/{**catch-all}"
    });
    options.Clusters.Add(new YarpCluster
    {
        ClusterId = "api-cluster",
        Destinations = new() { "http://localhost:5001" }
    });
});

Consul 动态服务发现:

builder.Services.AddReverseProxy();
builder.Services.AddYarpConsulDiscovery(options =>
{
    options.AddServiceMapping("auth-route", "auth-cluster", "auth-service", "/auth/{**catch-all}");
    options.AddServiceMapping("order-route", "order-cluster", "order-service", "/orders/{**catch-all}");
});

YARP 弹性策略（Polly 装饰器）:

// 必须在 AddReverseProxy() 之后调用
builder.Services.AddReverseProxy();
builder.Services.AddResilience();  // 注册 IResiliencePolicyProvider
builder.Services.AddYarpResilience();  // 装饰 IHttpForwarder

---

12. gRPC (Healnet.Infrastructure.gRPC)

// 注册
builder.Services.AddGrpcService();

// 带配置
builder.Services.AddGrpcService(options =>
{
    options.EnableConsulIntegration = true;
});

// 从配置
builder.Services.AddGrpcService(builder.Configuration);

配置示例:

{
  "Healnet": {
    "gRPC": {
      "EnableConsulIntegration": false,
      "ConsulAddress": "http://localhost:8500",
      "DefaultTimeoutSeconds": 30,
      "EnableRetry": true,
      "MaxRetryAttempts": 3
    }
  }
}

⚠️ IGrpcService.CallGrpcMethodAsync 当前抛出 NotSupportedException，需业务系统自行集成 gRPC 客户端调用。

---

13. 日志 - Serilog (Healnet.Infrastructure.Logging)

推荐方式 — IHostBuilder:

var builder = WebApplication.CreateBuilder(args);
builder.Host.UseHealnetSerilog();  // 自动读取 Healnet:Serilog 配置，注册 ILoggerService

// 启用请求日志
app.UseSerilogRequestLogging();

IServiceCollection 方式:

// 默认控制台 + 文件日志
builder.Services.AddSerilogDefault();

// 自定义
builder.Services.AddSerilog(config =>
{
    config.MinimumLevel.Debug()
          .WriteTo.Console()
          .WriteTo.File("logs/app.log");
});

// 从配置文件
builder.Services.AddSerilog(builder.Configuration);

配置示例:

{
  "Healnet": {
    "Serilog": {
      "MinimumLevel": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      },
      "Console": {
        "Enabled": true,
        "OutputTemplate": "[{Timestamp:yyyy-MM-dd HH:mm:ss.fff} {Level:u3}] {Message:lj}{NewLine}{Exception}"
      },
      "File": {
        "Enabled": true,
        "Path": "logs/log-.txt",
        "RollingInterval": "Day",
        "RetainedFileCountLimit": 30,
        "OutputTemplate": "[{Timestamp:yyyy-MM-dd HH:mm:ss.fff} {Level:u3}] {Message:lj}{NewLine}{Exception}"
      },
      "Elasticsearch": {
        "Enabled": false,
        "NodeUris": "http://localhost:9200",
        "IndexFormat": "healnet-logs-{0:yyyy.MM.dd}",
        "AutoRegisterTemplate": true
      }
    }
  }
}

日志级别映射:

verbose / trace → Verbose
debug           → Debug
information/info → Information
warning/warn    → Warning
error           → Error
fatal/critical  → Fatal

---

14. OpenTelemetry 可观测性 (Healnet.Infrastructure.OpenTelemetry)

builder.Services.AddHealnetOpenTelemetry(options =>
{
    options.Enabled = true;
    options.ServiceName = "MyService";
    options.ServiceVersion = "1.0.0";

    // Trace / Metrics / Logging（默认全开）
    options.EnableTracing = true;
    options.EnableMetrics = true;
    options.EnableLogging = true;

    // 导出器
    options.Console.Enabled = true;
    options.Otlp.Enabled = true;
    options.Otlp.Endpoint = "http://jaeger:4317";
    options.Jaeger.Enabled = false;
    options.Zipkin.Enabled = false;

    // 自动埋点
    options.InstrumentationNames = new() { "AspNetCore", "HttpClient", "SqlClient" };
});

app.UseHealnetOpenTelemetry();

支持的导出器:

导出器	配置属性	默认地址
Console	Console.Enabled	—
OTLP (gRPC)	Otlp.Enabled / Otlp.Endpoint	http://localhost:4317
Jaeger	Jaeger.Enabled / Jaeger.Host:Port	localhost:6831
Zipkin	Zipkin.Enabled / Zipkin.Endpoint	http://localhost:9411/api/v2/spans

---

15. 健康检查 (Healnet.Infrastructure.HealthChecks)

// 注册（支持 Redis / MongoDB / RabbitMQ）
builder.Services.AddHealnetHealthChecks(
    redisEnabled: true,
    mongoEnabled: true,
    rabbitMqEnabled: true);

// 映射端点（返回 JSON）
app.MapHealnetHealthChecks("/health");

健康检查响应格式:

{
  "Status": "Healthy",
  "Checks": [
    {
      "Name": "redis",
      "Status": "Healthy",
      "Description": "Redis is connected",
      "Duration": 12.5,
      "ErrorMessage": null
    }
  ],
  "TotalDuration": 25.8
}

---

16. 中间件 (Healnet.Infrastructure.Middleware)

// 异常处理（自动捕获未处理异常，返回统一 JSON）
app.UseExceptionHandling(showDetailedErrors: false);

// 请求日志（记录请求路径 + 耗时）
app.UseRequestLogging();

// 关联 ID（从 X-Correlation-Id 头读取或自动生成）
app.UseCorrelationId();

// 健康检查端点（自定义路径）
app.UseHealthCheck("/healthz");

⚠️ HealthCheckMiddleware 和 ExceptionHandlingMiddleware (Infrastructure 版本) 已标记 [Obsolete]，推荐使用 ASP.NET Core 内置健康检查及 Core 层 ExceptionHandlerMiddleware。

---

17. 弹性策略 (Healnet.Infrastructure.Resilience)

// 默认配置
builder.Services.AddResilience();

// 自定义
builder.Services.AddResilience(options =>
{
    options.RetryCount = 5;
    options.CircuitBreakerThreshold = 10;
    options.CircuitBreakerDurationSeconds = 60;
});

// 注入
public class MyService
{
    public MyService(IResiliencePolicyProvider provider)
    {
        var retryPolicy = provider.GetRetryPolicy();
        var circuitBreaker = provider.GetCircuitBreakerPolicy();
    }
}

---

18. AOP 拦截器 (Healnet.Infrastructure.AOP)

基于 AspectCore 提供 5 个内置拦截器：

拦截器	用途
LogInterceptor	方法调用日志（入参/出参/耗时）
CacheInterceptor	方法结果缓存
ExceptionHandlerInterceptor	异常捕获与统一处理
PerformanceMonitorInterceptor	性能监控（慢方法告警）
RetryInterceptor	方法重试

注册方式:

// 方式一：全部注册
builder.Services.AddAspectCoreWithInterceptors();

// 方式二：选择性注册
builder.Services.AddAspectCore(config =>
{
    config.AddLogInterceptor()
          .AddExceptionHandlerInterceptor()
          .AddPerformanceMonitorInterceptor();
});

// 然后在需要代理的服务上用 [Intercept] 标记
[Intercept(typeof(LogInterceptor))]
public class UserService : IUserService
{
    // 所有方法自动记录日志
}

---

19. Swagger API 文档 (Healnet.Infrastructure.Swagger)

// 注册
builder.Services.AddSwagger(options =>
{
    options.Title = "My API";
    options.Version = "v1";
    options.EnableJwtAuth = true;
    options.IncludeXmlComments = true;
});

// 或从配置读取
builder.Services.AddSwagger(builder.Configuration);

// 启用
app.UseSwaggerWithUI();  // 路径: /swagger

配置示例:

{
  "Healnet": {
    "Swagger": {
      "Title": "Healnet API",
      "Description": "Healnet 微服务 API 文档",
      "Version": "v1",
      "EnableJwtAuth": true,
      "JwtSchemeName": "Bearer",
      "IncludeXmlComments": true,
      "DocExpansion": "List",
      "DefaultModelExpandDepth": 2
    }
  }
}

---

20. 阿里云 OSS 对象存储 (Healnet.Infrastructure.OSS)

// 方式一：简单参数
builder.Services.AddAliyunOssFileService(
    endpoint: "oss-cn-hangzhou.aliyuncs.com",
    accessKeyId: "your-access-key",
    accessKeySecret: "your-secret",
    bucketName: "my-bucket");

// 方式二：配置委托
builder.Services.AddAliyunOssFileService(options =>
{
    options.OssEndpoint = "oss-cn-hangzhou.aliyuncs.com";
    options.OssAccessKeyId = "your-access-key";
    options.OssAccessKeySecret = "your-secret";
    options.OssBucketName = "my-bucket";
});

// 方式三：配置文件
builder.Services.AddAliyunOssFileService(builder.Configuration);

配置示例:

{
  "Healnet": {
    "FileStorage": {
      "StorageType": "Oss",
      "OssEndpoint": "oss-cn-hangzhou.aliyuncs.com",
      "OssAccessKeyId": "your-access-key",
      "OssAccessKeySecret": "your-secret",
      "OssBucketName": "my-bucket",
      "BaseUrl": "https://cdn.example.com"
    }
  }
}

注入服务:

接口	实现	生命周期	用途
IFileService	AliyunOssFileService	Singleton	文件上传/下载/删除（替换默认实现）

---

21. AI 服务集成 (Healnet.Infrastructure.AI)

支持 Semantic Kernel 和 Microsoft.Extensions.AI 两种 AI 框架，以及 Agent 框架。

// 完整 AI 服务
builder.Services.AddAIServices(options =>
{
    options.Provider = AIProvider.SemanticKernel;
    options.ApiKey = "sk-xxx";
    options.ModelName = "gpt-4o";
    options.Endpoint = "https://api.openai.com/v1";
});

// 仅 Semantic Kernel
builder.Services.AddSemanticKernelOnly(options => { ... });

// 仅 Microsoft.Extensions.AI
builder.Services.AddMicrosoftAIOnly(options => { ... });

// 仅 Agent Framework
builder.Services.AddAgentFrameworkOnly(options => { ... });

// 从配置文件
builder.Services.AddAIServices(builder.Configuration);

配置示例:

{
  "Healnet": {
    "AI": {
      "Provider": "SemanticKernel",
      "ApiKey": "sk-xxx",
      "Endpoint": "https://api.openai.com/v1",
      "ModelName": "gpt-4o",
      "MaxTokens": 4096,
      "Temperature": 0.7,
      "TopP": 0.9,
      "ContextWindowSize": 128000,
      "RAG": {
        "Enabled": true,
        "TopK": 5,
        "MaxContextLength": 8192
      },
      "AgentFramework": {
        "Endpoint": "https://agent.example.com",
        "DeploymentName": "my-agent",
        "EnableToolCalling": true,
        "MaxIterations": 10
      }
    }
  }
}

注入服务:

接口	实现	用途
IAIService	UnifiedAIService	统一 AI 服务入口
IChatContextManager	ChatContextManager	对话上下文管理
IRAGService	RAGService	检索增强生成
IAgentService	AgentService	Agent 服务
IAgentContextManager	AgentContextManager	Agent 上下文管理
ICopilotClient	CopilotClient / MicrosoftAIClient	AI 客户端

---

22. 工作单元 (Healnet.Infrastructure.UnitOfWork)

builder.Services.AddUnitOfWork();

// 使用
public class OrderService
{
    private readonly IUnitOfWork _uow;
    public OrderService(IUnitOfWork uow) => _uow = uow;

    public async Task Process()
    {
        await _uow.BeginTransactionAsync();
        try
        {
            // 业务操作...
            await _uow.CommitTransactionAsync();
        }
        catch
        {
            await _uow.RollbackTransactionAsync();
            throw;
        }
    }
}

---

完整配置总览

以下是所有模块在实际 appsettings.json 中的配置结构一览（按需使用）：

{
  "Healnet": {
    "Redis": {
      "Configuration": "localhost:6379",
      "InstanceName": "Healnet",
      "KeyPrefix": "Healnet:",
      "ConnectTimeout": 5000,
      "SyncTimeout": 5000,
      "AbortOnConnectFail": false,
      "DefaultDatabase": 0,
      "PoolSize": 10
    },
    "Jwt": {
      "SecretKey": "your-secret-key-at-least-32-characters-long!!",
      "Issuer": "Healnet",
      "Audience": "Healnet.Api",
      "AccessTokenExpireMinutes": 60,
      "RefreshTokenExpireDays": 7
    },
    "SqlSugar": {
      "ConnectionString": "Server=localhost;Database=MyDB;Uid=root;Pwd=123456;",
      "DbType": "MySql",
      "IsAutoCloseConnection": true,
      "InitKeyType": "Attribute"
    },
    "ClickHouse": {
      "Host": "localhost",
      "Port": 8123,
      "Database": "analytics",
      "Username": "default",
      "Password": "",
      "BatchSize": 1000
    },
    "ElasticSearch": {
      "Uri": "http://localhost:9200",
      "DefaultIndex": "healnet-logs",
      "Username": "",
      "Password": ""
    },
    "Consul": {
      "Address": "http://localhost:8500"
    },
    "Serilog": {
      "MinimumLevel": "Information",
      "Console": { "Enabled": true },
      "File": { "Enabled": true, "Path": "logs/log-.txt", "RollingInterval": "Day" }
    },
    "Swagger": {
      "Title": "Healnet API",
      "Version": "v1",
      "EnableJwtAuth": true
    },
    "Security": {
      "EnableHsts": true,
      "EnableXssProtection": true
    },
    "Cors": {
      "AllowedOrigins": ["https://app.example.com"],
      "AllowedMethods": ["GET", "POST", "PUT", "DELETE"],
      "AllowedHeaders": ["Authorization", "Content-Type"]
    },
    "AI": {
      "Provider": "SemanticKernel",
      "ApiKey": "",
      "ModelName": "gpt-4o"
    },
    "FileStorage": {
      "StorageType": "Oss",
      "OssEndpoint": "",
      "OssAccessKeyId": "",
      "OssAccessKeySecret": "",
      "OssBucketName": ""
    },
    "gRPC": {
      "EnableConsulIntegration": false,
      "DefaultTimeoutSeconds": 30
    }
  }
}

---

依赖关系

Healnet.Infrastructure (net10.0)
├── Healnet.Core
├── Healnet.Common
├── StackExchange.Redis 2.9.0
├── MongoDB.Driver 2.29.0
├── SqlSugarCore 5.1.4
├── ClickHouse.Client 6.5.0
├── NEST 7.17.5
├── RabbitMQ.Client 6.8.1
├── Consul 1.7.14
├── Yarp.ReverseProxy 2.2.0
├── Grpc.AspNetCore 2.65.0
├── Serilog.AspNetCore 8.0.0
├── OpenTelemetry 1.7.x（Tracing + Metrics + Logging）
├── Polly 8.3.1
├── AspectCore 2.4.0
├── Swashbuckle 6.5.0
├── Microsoft.SemanticKernel 1.67.1
├── Microsoft.Extensions.AI 9.10.0
├── Aliyun.OSS.SDK.NetCore 2.14.1
└── Microsoft.AspNetCore.Authentication.JwtBearer 8.0.8

---

版本历史

版本	日期	变更
1.0.0	—	初始版本
1.1.0	—	添加 Microsoft.Extensions.AI 封装，完善文档
1.2.0	2026-05	新增 YARP 弹性策略装饰器、AddYarpResilience；AddSwagger 自动注册 AddEndpointsApiExplorer；UseHealnetSerilog 自动注册 ILoggerService；安全修复（分布式锁原子操作、密码哈希随机盐）；gRPC/AI 桩实现改为 NotSupportedException；AOP 拦截器正确注册