Galosys.Foundation.Yarp 26.5.20.1

Galosys.Foundation.Yarp

基于 YARP (Yet Another Reverse Proxy) 的网关核心模块，提供反向代理、JSON 配置管理和轻量级指标采集。

依赖: 仅依赖 Galosys.Foundation.Core，不依赖任何消息队列实现。

安装

dotnet add package Galosys.Foundation.Yarp

最小化配置

在 appsettings.json 中配置路由：

{
 "Gateway": {
 "Routes": [
 {
 "Id": "user-service",
 "Uri": "http://localhost:5001",
 "Predicate": {
 "Path": "/api/users/**"
 }
 }
 ]
 }
}

在 Program.cs 中注册：

builder.Services.AddYarpCore(builder.Environment);
builder.Services.AddYarbConfigProvider<JsonYarpConfigProvider>(); // JSON 配置（默认）

app.MapYarpReverseProxy();

分布式配置刷新（RabbitMQ 消费端）

YARP 核心模块只负责广播配置刷新事件（通过 ICloudBus），不内置消费端。 使用 RabbitMQ 的项目需自行实现消费端 handler：

1. 添加 RabbitMQ 依赖

dotnet add package Galosys.Foundation.RabbitMQ.Client

2. 实现消费端 Handler

using Galosys.Foundation.Core;
using Galosys.Foundation.Yarp;
using RabbitMQ.Client;
using Yarp.ReverseProxy.Configuration;

namespace YourApp.Handlers;

/// <summary>
/// RabbitMQ 分布式网关配置刷新消费者
/// </summary>
public class GatewayConfigRefreshedHandler : IMessageHandler<GatewayConfigRefreshedCloudEvent>
{
 private readonly IYarpConfigManager _mgr;
 private readonly ILogger<GatewayConfigRefreshedHandler> _logger;

 public GatewayConfigRefreshedHandler(
 IYarpConfigManager mgr,
 ILogger<GatewayConfigRefreshedHandler> logger)
 {
 _mgr = mgr;
 _logger = logger;
 }

 [AmqpHandler("base_gw_config_refreshed", true)]
 public async Task<bool> HandleAsync(GatewayConfigRefreshedCloudEvent msg)
 {
 await Task.Run(() => _mgr.UpdateConfig());
 _logger.LogInformation("=====网关路由已刷新=====");
 return true;
 }
}

/refresh 端点

默认关闭。需要在 appsettings.json 中显式开启：

{
 "Gateway": {
 "EnableRefreshEndpoint": true
 }
}

开启后 /refresh 端点会触发配置刷新事件，且强制要求认证（RequireAuthorization()）。

指标采集配置

网关内置轻量级指标采集中间件 (GatewayMetricMiddleware)，仅记录元数据（路径、方法、状态码、耗时），不缓冲请求/响应 Body。

配置节名称：Gateway:Metric

{
 "Gateway": {
 "Metric": {
 "SamplingRate": 0.1, // 正常请求采样率，0.0-1.0（默认 0.1，即 10%）
 "AlwaysLogErrors": true, // 异常/失败请求是否全量记录（默认 true）
 "BatchSize": 200, // 批量写入 DB 的批次大小（默认 200）
 "BatchIntervalMs": 500, // 批量写入最大间隔毫秒数（默认 500）
 "BatchChannelCapacity": 50000 // 独立 Channel 容量（默认 50000）
 }
 }
}

采样策略

• 正常请求（状态码 2xx/3xx 且转发成功）：按 SamplingRate 概率采样
• 异常请求（转发失败或状态码 ≥ 400）：AlwaysLogErrors = true 时全量记录

配置项说明

路由配置

每条路由支持以下配置：

{
 "Id": "order-service",
 "Uri": "http://localhost:5002,http://localhost:5003", // 多地址负载均衡
 "Predicate": {
 "Path": "/api/orders/**,/api/payments/**", // 多路径逗号分隔
 "Host": "api.example.com",
 "Method": "GET,POST",
 "Header": { "X-Version": "1" },
 "QueryParameter": { "debug": "true" }
 },
 "LoadBalancer": "RoundRobin", // 可选：RoundRobin（默认）、LeastRequests、PowerOfTwoChoices 等
 "Filter": {
 "PathPrefix": "/api",
 "PathRemovePrefix": "/api"
 },
 "Metadata": {
 "custom-key": "custom-value"
 }
}

路由配置项说明

高可用配置

网关内置限流、健康检查和超时机制，保护网关和后端服务稳定运行。配置节名称：Gateway:Ha

最小化配置（使用默认值）

不配置 Gateway:Ha 节即可使用默认值：最大并发 2000、被动健康检查启用、默认超时 30s。

完整配置

{
 "Gateway": {
 "Ha": {
 "MaxConcurrentRequests": 2000, // 最大并发请求数（默认 2000）
 "RateLimitStatusCode": 429, // 限流响应状态码（默认 429）
 "PassiveHealthCheckEnabled": true, // 被动健康检查（默认 true）
 "ActiveHealthCheckEnabled": false, // 主动健康检查（默认 false，启用后定期探测目标 /health）
 "ActiveHealthCheckIntervalSeconds": 10, // 主动探测间隔秒数（默认 10）
 "ActiveHealthCheckTimeoutSeconds": 5, // 主动探测超时秒数（默认 5）
 "ReactivationPeriodSeconds": 60, // 不健康目标恢复等待秒数（默认 60）
 "DefaultActivityTimeoutMs": 30000 // 默认请求超时毫秒数（默认 30000，即 30s）
 }
 }
}

限流

GatewayRateLimitMiddleware 基于 SemaphoreSlim 限制最大并发请求数，超限立即返回 429（可配置状态码）。

• 当并发请求数 < MaxConcurrentRequests 时，请求正常通过
• 当并发请求数 >= MaxConcurrentRequests 时，立即返回 HTTP 429，不会转发到后端
• 请求完成（无论成功或失败）后自动释放信号量

健康检查

被动健康检查（默认启用）

使用 YARP 内置 TransportFailureRate 策略，跟踪请求失败率，自动标记不健康目标并从负载均衡中排除。经过 ReactivationPeriodSeconds 后重新纳入候选。

主动健康检查（默认关闭）

启用后（ActiveHealthCheckEnabled = true），网关每隔 ActiveHealthCheckIntervalSeconds 向每个目标发送健康探测请求，超时 ActiveHealthCheckTimeoutSeconds。探测策略为 Any5xxResponse。

超时

ForwarderRequestConfig.ActivityTimeout 控制转发请求超时。超时后网关立即返回 504 Gateway Timeout，不会继续等待。

• 默认超时：DefaultActivityTimeoutMs（30000ms）
• 数据库路由模板可按路由覆盖：RouterTemplate.ActivityTimeout 字段

配置项说明

配置管理选项

配置节名称：Gateway:Config

{
 "Gateway": {
 "Config": {
 "CacheExpirationSeconds": 30, // 数据库配置缓存过期秒数（默认 30s）
 "EnablePollingFallback": false, // 是否启用轮询降级（默认 false，RabbitMQ 不可用时开启）
 "PollingIntervalSeconds": 30 // 轮询间隔秒数（默认 30s）
 }
 }
}

配置缓存

DatabaseYarpConfigProvider 使用 IMemoryCache 缓存数据库查询结果，避免每次请求查库：

• 缓存 Key：YarpDatabaseConfig
• 过期时间：CacheExpirationSeconds（默认 30s）
• UpdateConfig() 调用时自动清除缓存，下次请求重新查询 DB

轮询降级

当 RabbitMQ 不可用时，可开启轮询降级模式，由 GatewayConfigPollingService（BackgroundService）定时刷新配置：

{
 "Gateway": {
 "Config": {
 "EnablePollingFallback": true,
 "PollingIntervalSeconds": 30
 }
 }
}

配置项说明

BREAKING CHANGES

• v3.0: 移除了对 Galosys.Foundation.Amqp 和 Galosys.Foundation.RabbitMQ.Client 的依赖。使用 RabbitMQ 分布式刷新的项目需自行实现 IMessageHandler<GatewayConfigRefreshedCloudEvent> 消费端（参考上方示例）。
• v3.0: /refresh 端点默认关闭，需配置 Gateway:EnableRefreshEndpoint = true 并配合认证使用。
• v4.0: 新增 GatewayHaOptions 高可用配置（配置节 Gateway:Ha）。新增 GatewayRateLimitMiddleware 限流中间件。启用 ActivityTimeout 超时和被动健康检查（默认行为变更：请求超过 30s 将返回 504）。
• v5.0: IYarpConfigProvider 新增 GetConfigAsync() 方法（默认调用同步 GetConfig()，不影响现有实现）。JsonYarpConfigProvider 修复 hot reload（每次 GetConfig() 读取 IOptionsMonitor.CurrentValue）。YarpConfigManager.UpdateConfig() 添加异常处理和日志。新增 GatewayConfigOptions 配置缓存和轮询降级。