Healnet.Infrastructure 1.0.18

Healnet.Infrastructure

Healnet.Infrastructure 是 Healnet 框架的基础设施层类库，提供各种基础设施服务的封装和集成。

功能特性

模块	描述	状态
Consul	服务发现与注册	✅
Redis	分布式缓存	✅
RabbitMQ	消息队列	✅
gRPC	远程过程调用	✅
Elasticsearch	全文搜索与数据分析	✅
SQLSugar	ORM 框架	✅
JWT	身份认证	✅
YARP	反向代理	✅
Polly	熔断与重试	✅
OpenTelemetry	可观测性（追踪、指标、日志）	✅
Serilog	日志框架	✅
MongoDB	NoSQL 数据库	✅
AI	AI 助手与 RAG 服务	✅
ClickHouse	列式数据库	✅

目录

1. Consul 服务发现
2. Redis 缓存服务
3. ElasticSearch 服务
4. Authentication 认证服务
5. Security 安全服务
6. Swagger API 文档
7. UnitOfWork 工作单元
8. SqlSugar ORM
9. Polly 熔断重试
10. gRPC 服务
11. RabbitMQ 消息队列
12. HttpClient 客户端
13. Logging 日志
14. Middleware 中间件
15. OpenTelemetry 可观测性
16. AI 服务
17. ClickHouse 服务

---

2. Consul 服务发现

概述

基于 Consul 的服务发现与注册组件，支持自动获取服务地址进行注册。

核心功能

• 服务注册与发现
• 健康检查
• 多环境支持（K8s、Docker、开发环境）
• 自动获取服务地址

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 Consul 服务
builder.Services.AddConsul(config =>
{
    config.Address = "http://localhost:8500";
    config.Datacenter = "dc1";
});

var app = builder.Build();

// 注册服务到 Consul
app.UseConsul();

app.Run();

配置说明

{
  "Healnet": {
    "Consul": {
      "Address": "http://localhost:8500",
      "Datacenter": "dc1",
      "ServiceName": "Healnet.Api",
      "ServicePort": 5000,
      "HealthCheckPath": "/health",
      "HealthCheckInterval": "10s",
      "AutoRegister": true
    }
  }
}

---

3. Redis 缓存服务

概述

基于 StackExchange.Redis 的分布式缓存实现。

核心功能

• 分布式缓存操作
• 分布式锁
• 缓存序列化与反序列化
• 连接池管理

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 Redis 服务
builder.Services.AddRedis(config =>
{
    config.ConnectionString = "localhost:6379";
    config.InstanceName = "Healnet";
});

var app = builder.Build();
app.Run();

配置说明

{
  "Healnet": {
    "Redis": {
      "ConnectionString": "localhost:6379",
      "InstanceName": "Healnet",
      "ConnectTimeout": 5000,
      "SyncTimeout": 5000
    }
  }
}

---

4. ElasticSearch 服务

概述

基于 NEST 的 Elasticsearch 客户端封装，提供文档操作和搜索功能。

核心功能

• 文档 CRUD 操作
• 全文搜索
• 聚合查询
• 索引管理

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 Elasticsearch 服务
builder.Services.AddElasticsearch(config =>
{
    config.NodeUris = "http://localhost:9200";
});

var app = builder.Build();
app.Run();

配置说明

{
  "Healnet": {
    "Elasticsearch": {
      "NodeUris": "http://localhost:9200",
      "DefaultIndex": "healnet",
      "EnableSniffing": true
    }
  }
}

---

5. Authentication 认证服务

概述

基于 JWT 的身份认证组件。

核心功能

• JWT 令牌生成与验证
• 令牌刷新
• 认证中间件
• 权限验证

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册认证服务
builder.Services.AddJwtAuthentication(config =>
{
    config.SecretKey = "your-secret-key";
    config.Issuer = "Healnet";
    config.Audience = "Healnet";
    config.ExpireMinutes = 60;
});

var app = builder.Build();

// 使用认证中间件
app.UseAuthentication();
app.UseAuthorization();

app.Run();

配置说明

{
  "Healnet": {
    "Jwt": {
      "SecretKey": "your-secret-key",
      "Issuer": "Healnet",
      "Audience": "Healnet",
      "ExpireMinutes": 60
    }
  }
}

---

6. Security 安全服务

概述

安全相关工具和中间件。

核心功能

• 密码加密
• XSS 防护
• CSRF 防护
• CORS 配置

快速开始

var builder = WebApplication.CreateBuilder(args);

// 配置安全选项
builder.Services.ConfigureSecurity(options =>
{
    options.AllowedOrigins = ["https://example.com"];
    options.AllowCredentials = true;
});

var app = builder.Build();

// 使用 CORS 中间件
app.UseCors();

app.Run();

---

7. Swagger API 文档

概述

基于 Swashbuckle 的 API 文档生成组件。

核心功能

• 自动生成 API 文档
• 接口测试
• 自定义文档配置

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 Swagger 服务
builder.Services.AddSwagger(config =>
{
    config.Title = "Healnet API";
    config.Version = "v1";
    config.Description = "Healnet 框架 API 文档";
});

var app = builder.Build();

// 启用 Swagger UI
app.UseSwagger();
app.UseSwaggerUI();

app.Run();

配置说明

{
  "Healnet": {
    "Swagger": {
      "Title": "Healnet API",
      "Version": "v1",
      "Description": "Healnet 框架 API 文档",
      "RoutePrefix": "swagger"
    }
  }
}

---

9. UnitOfWork 工作单元

概述

工作单元模式实现，支持事务管理。

核心功能

• 事务管理
• 统一提交/回滚
• 多数据源支持

快速开始

public class UserService
{
    private readonly IUnitOfWork _unitOfWork;
    
    public UserService(IUnitOfWork unitOfWork)
    {
        _unitOfWork = unitOfWork;
    }
    
    public async Task CreateUserAsync(User user)
    {
        using (var transaction = await _unitOfWork.BeginTransactionAsync())
        {
            try
            {
                await _unitOfWork.Repository<User>().AddAsync(user);
                await _unitOfWork.SaveChangesAsync();
                await transaction.CommitAsync();
            }
            catch
            {
                await transaction.RollbackAsync();
                throw;
            }
        }
    }
}

---

10. SqlSugar ORM

概述

基于 SqlSugar 的 ORM 框架封装。

核心功能

• 实体映射
• LINQ 查询
• 事务支持
• 自动生成实体

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 SqlSugar（从配置自动读取）
builder.Services.AddSqlSugar(builder.Configuration);

var app = builder.Build();
app.Run();

配置说明

{
  "Healnet": {
    "SqlSugar": {
      "ConnectionString": "Server=localhost;Database=HealnetDB;Trusted_Connection=True;",
      "DbType": "SqlServer",
      "IsAutoCloseConnection": true,
      "IsShardSameThread": false
    }
  }
}

使用示例

public class UserRepository : ISqlSugarRepository<User, long>
{
    public UserRepository(ISqlSugarClient db, ILoggerService logger) 
        : base(db, logger) { }
    
    public async Task<User?> GetByEmailAsync(string email)
    {
        return await Db.Queryable<User>()
            .Where(u => u.Email == email)
            .FirstAsync();
    }
}

---

11. Polly 熔断重试

概述

基于 Polly 的熔断和重试策略实现。

核心功能

• 熔断策略
• 重试策略
• 超时策略
• 舱壁隔离

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 Polly 策略
builder.Services.AddResiliencePolicy(config =>
{
    config.RetryCount = 3;
    config.CircuitBreakThreshold = 0.5;
    config.CircuitBreakDuration = "30s";
});

var app = builder.Build();
app.Run();

使用示例

public class UserService
{
    private readonly IResiliencePolicyProvider _policyProvider;
    
    public UserService(IResiliencePolicyProvider policyProvider)
    {
        _policyProvider = policyProvider;
    }
    
    public async Task<User> GetUserAsync(long id)
    {
        var policy = _policyProvider.GetPolicy();
        return await policy.ExecuteAsync(async () =>
        {
            // 调用外部服务
            return await _externalService.GetUserByIdAsync(id);
        });
    }
}

---

12. gRPC 服务

概述

gRPC 客户端封装，支持服务发现集成。

核心功能

• gRPC 客户端创建
• 负载均衡
• 与 Consul 集成
• 重试机制

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 gRPC 服务
builder.Services.AddGrpcClient<UserService.UserServiceClient>(options =>
{
    options.Address = new Uri("https://localhost:5001");
});

var app = builder.Build();
app.Run();

---

13. RabbitMQ 消息队列

概述

基于 RabbitMQ.Client 的消息队列封装。

核心功能

• 生产者/消费者模式
• 消息持久化
• 消息确认
• 死信队列

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 RabbitMQ 服务
builder.Services.AddRabbitMQ(config =>
{
    config.HostName = "localhost";
    config.UserName = "guest";
    config.Password = "guest";
});

var app = builder.Build();
app.Run();

使用示例

// 发送消息
await _rabbitMQService.PublishAsync("exchange", "routingKey", message);

// 消费消息
await _rabbitMQService.SubscribeAsync("queue", async (message) =>
{
    // 处理消息
    await ProcessMessage(message);
});

---

14. HttpClient 客户端

概述

基于 HttpClient 的 HTTP 客户端封装，支持熔断和重试。

核心功能

• HTTP 请求封装
• 熔断重试
• 请求日志
• 响应处理

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 HttpClient 服务
builder.Services.AddHttpClientService();

var app = builder.Build();
app.Run();

使用示例

public class UserService
{
    private readonly IHttpClientService _httpClient;
    
    public UserService(IHttpClientService httpClient)
    {
        _httpClient = httpClient;
    }
    
    public async Task<User> GetUserAsync(long id)
    {
        var response = await _httpClient.GetAsync($"https://api.example.com/users/{id}");
        return await response.Content.ReadFromJsonAsync<User>();
    }
}

---

15. Logging 日志

概述

统一日志接口，基于 Serilog 实现，支持多种日志输出目标（控制台、文件、ElasticSearch）。

核心类说明

类	说明
SerilogService	Serilog 日志服务实现
LoggingExtensions	日志服务注册扩展方法
LoggingOptions	日志配置选项

ILoggerService 接口方法

方法	说明	参数
Trace	记录跟踪级别日志（最详细）	message: 消息, args: 参数
Debug	记录调试级别日志	message: 消息, args: 参数
Information	记录信息级别日志	message: 消息, args: 参数
Warning	记录警告级别日志	message: 消息, args: 参数
Error	记录错误级别日志	message: 消息, args: 参数
Error(Exception, ...)	记录错误级别日志（含异常）	exception: 异常, message: 消息
Critical	记录严重级别日志	message: 消息, args: 参数
Critical(Exception, ...)	记录严重级别日志（含异常）	exception: 异常, message: 消息
Log(LogLevel, ...)	记录指定级别日志	level: 日志级别, message: 消息

快速开始

方式一：使用默认配置

var builder = WebApplication.CreateBuilder(args);

// 使用默认配置（控制台 + 文件输出）
builder.Services.AddSerilogDefault();

var app = builder.Build();
app.Run();

方式二：使用自定义配置

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSerilog(config =>
{
    config.MinimumLevel.Debug()
          .Enrich.FromLogContext()
          .WriteTo.Console()
          .WriteTo.File("logs/log-.txt", rollingInterval: RollingInterval.Day);
});

var app = builder.Build();
app.Run();

方式三：使用配置文件

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSerilog(builder.Configuration);

var app = builder.Build();
app.Run();

配置说明

{
  "Healnet": {
    "Serilog": {
      "MinimumLevel": {
        "Default": "Information",
        "Override": {
          "Microsoft": "Warning",
          "System": "Warning",
          "Healnet": "Debug"
        }
      },
      "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": true,
        "NodeUris": "http://localhost:9200",
        "IndexFormat": "healnet-logs-{0:yyyy.MM.dd}",
        "AutoRegisterTemplate": true
      }
    }
  }
}

在服务中使用

public class UserService
{
    private readonly ILoggerService _logger;
    
    public UserService(ILoggerService logger)
    {
        _logger = logger;
    }
    
    public async Task<User?> GetUserByIdAsync(long id)
    {
        _logger.Debug("Getting user with id: {UserId}", id);
        
        try
        {
            var user = await _repository.GetByIdAsync(id);
            
            if (user == null)
            {
                _logger.Warning("User not found with id: {UserId}", id);
                return null;
            }
            
            _logger.Information("User retrieved successfully: {UserId}", id);
            return user;
        }
        catch (Exception ex)
        {
            _logger.Error(ex, "Error getting user with id: {UserId}", id);
            throw;
        }
    }
}

日志级别说明

级别	说明	使用场景
Trace	最详细的日志	详细的调试信息
Debug	调试信息	开发调试
Information	常规运行时信息	记录关键业务操作
Warning	潜在问题	需要关注的情况
Error	已发生的错误	业务异常
Critical	严重错误	系统级故障

最佳实践

1. 结构化日志：使用命名参数而非字符串拼接

   // 推荐
   _logger.Information("User {UserId} logged in from {IpAddress}", userId, ipAddress);
   
   // 不推荐
   _logger.Information($"User {userId} logged in from {ipAddress}");
   

2. 包含上下文信息：在请求上下文中添加关联ID

   using (LogContext.PushProperty("CorrelationId", correlationId))
   {
       _logger.Information("Processing request");
   }
   

3. 异常处理：记录异常时包含完整异常对象

   try
   {
       // 业务逻辑
   }
   catch (Exception ex)
   {
       _logger.Error(ex, "Operation failed");
       throw;
   }
   

依赖包

包名	版本
Serilog.AspNetCore	8.0.1
Serilog.Sinks.Console	6.0.0
Serilog.Sinks.File	5.0.0
Serilog.Sinks.Elasticsearch	9.0.0
Serilog.Enrichers.Context	4.0.0

---

16. Middleware 中间件

概述

中间件组件，提供异常处理、请求日志、链路追踪和健康检查等功能。

核心功能

• 异常处理中间件
• 请求日志中间件
• 链路追踪中间件
• 健康检查中间件

快速开始

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

// 使用中间件
app.UseExceptionHandling();
app.UseRequestLogging();
app.UseCorrelationId();

app.Run();

---

17. OpenTelemetry 可观测性

概述

OpenTelemetry 封装，提供分布式追踪、指标和日志功能。

核心功能

• 分布式追踪
• 指标收集
• 日志导出
• 多种导出器支持

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 OpenTelemetry
builder.Services.AddHealnetOpenTelemetry(options =>
{
    options.ServiceName = "Healnet.Api";
    options.ServiceVersion = "1.0.0";
    options.Enabled = true;
    options.Otlp.Enabled = true;
    options.Otlp.Endpoint = "http://localhost:4317";
    options.Console.Enabled = true;
});

var app = builder.Build();

// 使用 OpenTelemetry
app.UseHealnetOpenTelemetry();

app.Run();

配置说明

{
  "Healnet": {
    "OpenTelemetry": {
      "Enabled": true,
      "ServiceName": "Healnet.Api",
      "ServiceVersion": "1.0.0",
      "EnableTracing": true,
      "EnableMetrics": true,
      "EnableLogging": true,
      "InstrumentationNames": ["AspNetCore", "HttpClient", "SqlClient"],
      "Otlp": {
        "Enabled": true,
        "Endpoint": "http://localhost:4317",
        "Protocol": "grpc"
      },
      "Jaeger": {
        "Enabled": false,
        "Endpoint": "http://localhost:14268"
      },
      "Zipkin": {
        "Enabled": false,
        "Endpoint": "http://localhost:9411/api/v2/spans"
      },
      "Console": {
        "Enabled": true
      }
    }
  }
}

支持的 Instrumentation

Instrumentation	说明
AspNetCore	ASP.NET Core 请求追踪
HttpClient	HTTP 客户端请求追踪
SqlClient	SQL 数据库操作追踪
GrpcClient	gRPC 客户端请求追踪
StackExchangeRedis	Redis 操作追踪

依赖包

包名	版本
OpenTelemetry.Extensions.Hosting	1.8.0
OpenTelemetry.Instrumentation.AspNetCore	1.8.0
OpenTelemetry.Instrumentation.Http	1.8.0
OpenTelemetry.Instrumentation.SqlClient	1.8.0
OpenTelemetry.Instrumentation.GrpcNetClient	1.8.0
OpenTelemetry.Exporter.Console	1.8.0
OpenTelemetry.Exporter.OpenTelemetryProtocol	1.8.0

---

18. AI 服务

概述

AI 服务模块提供了对 Semantic Kernel 和 Microsoft Agent Framework 的统一封装，支持双框架混合使用，简化 AI 应用开发。

核心功能

功能	说明
双框架支持	同时支持 Semantic Kernel 和 Microsoft Agent Framework
统一接口	提供 IAIService 统一接口，简化上层调用
智能体开发	支持智能体注册、执行和工具调用
上下文管理	支持对话上下文管理
RAG 服务	支持检索增强生成

核心接口和类

接口/类	说明
IAIService	统一 AI 服务接口
IagentService	Agent Framework 智能体服务接口
UnifiedAIService	统一 AI 服务实现
AgentService	Agent Framework 服务实现
AIOptions	AI 配置选项

快速开始

注册 AI 服务

var builder = WebApplication.CreateBuilder(args);

// 注册 AI 服务
builder.Services.AddAIService(builder.Configuration);

var app = builder.Build();
app.Run();

使用统一 AI 服务

public class ChatService
{
    private readonly IAIService _aiService;
    
    public ChatService(IAIService aiService)
    {
        _aiService = aiService;
    }
    
    public async Task<string> ChatAsync(string prompt)
    {
        return await _aiService.ChatAsync(prompt);
    }
    
    public async Task<string> ExecuteAgentAsync(string agentName, string task)
    {
        return await _aiService.ExecuteAgentAsync(agentName, task);
    }
}

配置说明

{
  "Healnet": {
    "AI": {
      "Framework": "Hybrid",
      "ApiKey": "your-api-key",
      "Endpoint": "https://your-resource.openai.azure.com/",
      "ModelName": "gpt-4o",
      "AgentFramework": {
        "Endpoint": "https://your-agent-endpoint",
        "DeploymentName": "gpt-4o",
        "EnableToolCalling": true,
        "MaxIterations": 10,
        "Tools": {
          "SearchTool": "Search web for information",
          "CalculatorTool": "Perform mathematical calculations"
        }
      }
    }
  }
}

框架选择

框架	说明
SemanticKernel	使用 Semantic Kernel 框架
AgentFramework	使用 Microsoft Agent Framework
Hybrid	混合使用双框架

使用示例

聊天功能

// 简单聊天
var response = await _aiService.ChatAsync("Hello, how are you?");

// 带上下文的聊天
var contextId = "user-123";
var response = await _aiService.ChatAsync("What's the weather today?", contextId);

智能体执行

// 注册智能体
await _aiService.ExecuteAgentAsync("coder", "Write a C# function to calculate factorial");

// 执行带参数的智能体
var parameters = new Dictionary<string, object>
{
    { "input", "12345" },
    { "format", "json" }
};
var response = await _aiService.ExecuteAgentWithToolsAsync("analyzer", "Analyze this data", parameters);

文本处理

// 文本摘要
var summary = await _aiService.SummarizeAsync(longText);

// 文本翻译
var translated = await _aiService.TranslateAsync(text, "zh-CN");

依赖包

包名	版本
Microsoft.SemanticKernel	1.67.1
Azure.AI.OpenAI	2.9.0-beta.1
NEST (Elasticsearch)	7.17.5
Consul	1.7.14.10

---

19. ClickHouse 服务

概述

ClickHouse 服务模块提供了对 ClickHouse 列式数据库的完整封装，支持高性能的 OLAP 查询和批量数据操作。

核心功能

功能	说明
查询操作	支持返回 DataTable、对象列表、单个对象、标量值
执行操作	支持 INSERT、UPDATE、DELETE 等 SQL 语句
批量插入	支持高性能批量数据插入
表管理	支持创建、删除表，获取表结构
元数据查询	支持查询数据库列表、表列表
连接测试	支持测试数据库连接

快速开始

var builder = WebApplication.CreateBuilder(args);

// 注册 ClickHouse 服务
builder.Services.AddClickHouse(builder.Configuration);

var app = builder.Build();
app.Run();

配置说明

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

使用示例

基础查询

// 返回对象列表
var users = await _clickHouse.QueryAsync<User>("SELECT * FROM users WHERE status = @status", 
    new Dictionary<string, object> { { "status", "active" } });

// 返回单个对象
var user = await _clickHouse.QuerySingleAsync<User>("SELECT * FROM users WHERE id = @id",
    new Dictionary<string, object> { { "id", userId } });

// 返回标量值
var count = await _clickHouse.QueryScalarAsync<int>("SELECT COUNT(*) FROM users");

批量插入

// 批量插入对象列表
var users = new List<User> { /* ... */ };
await _clickHouse.BulkInsertAsync("users", users);

表管理

// 创建表
var columns = new Dictionary<string, string>
{
    { "id", "UInt64" },
    { "name", "String" },
    { "created_at", "DateTime" }
};
await _clickHouse.CreateTableAsync("users", columns, "MergeTree", "id");

// 检查表是否存在
var exists = await _clickHouse.TableExistsAsync("users");

// 获取表结构
var schema = await _clickHouse.GetTableSchemaAsync("users");

依赖包

包名	版本
ClickHouse.Client	最新

---

许可证

MIT License