docs(03): capture phase context for gateway adjustment

2026-03-03 11:37:16 +08:00 · 2026-03-03 11:37:16 +08:00 · ed762b2e61
commit ed762b2e61
parent 6f1dbba4f0
2 changed files with 492 additions and 0 deletions
--- a/.planning/phases/03-/03-CONTEXT.md
+++ b/.planning/phases/03-/03-CONTEXT.md
@ -0,0 +1,199 @@
+# Phase 3: 调整网关部分的需求 - Context
+
+**Gathered:** 2026-03-03
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+调整 Gateway 模块的实体结构和 YARP 集成方式，包括：
+- 重构实体模型（删除 GwTenant 和 GwServiceInstance，新增 GwCluster）
+- 扩展 GwTenantRoute 的匹配和转换能力
+- 实现与 YARP 配置模型的完整对接
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### 实体结构调整
+
+#### 删除的实体
+- **GwTenant** - 删除，直接使用 Platform.Tenant 通过 TenantCode 关联
+- **GwServiceInstance** - 删除，改为 GwCluster 聚合根内嵌 Destination
+
+#### 新增的实体
+
+**GwCluster（集群聚合根）**
+- `string Id` - GUID，与 YARP ClusterId 类型一致
+- `string ClusterId` - 集群标识（业务 ID）
+- `string Name` - 集群名称
+- `string? Description` - 描述
+- `List<GwDestination> Destinations` - 目标端点列表（内嵌）
+- `string LoadBalancingPolicy` - 负载均衡策略 (RoundRobin, WeightedRoundRobin, LeastRequests 等)
+- `GwHealthCheckConfig? HealthCheck` - 健康检查配置
+- `GwSessionAffinityConfig? SessionAffinity` - 会话亲和配置
+- `int Status` - 状态
+- 审计字段 (CreatedBy, CreatedTime, UpdatedBy, UpdatedTime, IsDeleted, Version)
+
+**GwDestination（内嵌值对象）**
+- `string DestinationId` - 目标标识
+- `string Address` - 后端地址
+- `string? Health` - 健康检查端点
+- `int Weight` - 权重（用于加权负载均衡）
+- `int HealthStatus` - 健康状态
+- `int Status` - 状态
+
+**GwHealthCheckConfig（内嵌值对象）**
+- `bool Enabled` - 是否启用
+- `string? Path` - 健康检查路径 (默认 /health)
+- `int IntervalSeconds` - 检查间隔（秒）
+- `int TimeoutSeconds` - 超时时间（秒）
+
+**GwSessionAffinityConfig（内嵌值对象）**
+- `bool Enabled` - 是否启用
+- `string Policy` - 策略 (Header)
+- `string AffinityKeyName` - 亲和键名称
+
+#### 修改的实体
+
+**GwTenantRoute 扩展字段**
+- `string? Methods` - HTTP 方法匹配 (GET,POST,PUT,DELETE 等)
+- `string? Hosts` - Host 头匹配 (支持通配符)
+- `string? Headers` - Header 匹配规则 (JSON 格式)
+- `string? LoadBalancingPolicy` - 路由级别负载均衡策略覆盖
+- `string? AuthorizationPolicy` - 授权策略
+- `string? RateLimiterPolicy` - 限流策略
+- `string? CorsPolicy` - CORS 策略
+- `string? Transforms` - 请求/响应转换规则 (JSON 格式)
+
+保留现有字段：
+- `string Id` - GUID v7
+- `string TenantCode` - 租户代码（关联 Platform.Tenant）
+- `string ServiceName` - 服务名称
+- `string ClusterId` - 关联 GwCluster
+- `string PathPattern` - 路径匹配模式
+- `int Priority` - 优先级
+- `int Status` - 状态
+- `bool IsGlobal` - 是否全局路由
+
+### 路由匹配能力
+
+- **Path**: 完整支持 YARP Path 模式 (如 `/api/{**catch-all}`)
+- **Methods**: 支持 HTTP 方法过滤，逗号分隔 (如 `GET,POST`)
+- **Hosts**: 支持 Host 头匹配，逗号分隔 (如 `api.example.com,*.api.com`)
+- **Headers**: JSON 格式动态配置，如 `[{"Name":"X-Custom","Values":["value1"],"Mode":"ExactHeader"}]`
+
+### 负载均衡策略
+
+- **集群级别配置**: GwCluster.LoadBalancingPolicy 存储默认策略
+- **路由级别覆盖**: GwTenantRoute.LoadBalancingPolicy 可覆盖集群默认策略
+- 支持策略: `RoundRobin`, `LeastRequests`, `Random`, `PowerOfTwoChoices`, `WeightedRoundRobin`
+
+### 会话亲和 (Session Affinity)
+
+- **策略**: Header 方式
+- **标识来源**: UserId 优先，TenantCode 兜底
+- **AffinityKeyName**: `X-Session-Key`
+- **实现逻辑**: 
+  1. 已登录用户: 使用 `UserId` 作为会话键
+  2. 未登录用户: 使用 `TenantCode` 作为会话键
+  3. 同一会话键的请求路由到同一后端实例
+
+### 健康检查
+
+- **方式**: 主动健康检查 (Active Health Check)
+- **配置位置**: GwCluster.HealthCheck
+- **默认配置**:
+  - Path: `/health`
+  - Interval: 30 秒
+  - Timeout: 10 秒
+
+### 请求/响应转换 (Transforms)
+
+- **格式**: JSON 数组
+- **示例**:
+  ```json
+  [
+    {"RequestHeader": "X-Forwarded-For", "Set": "true"},
+    {"ResponseHeader": "X-Served-By", "Set": "gateway"}
+  ]
+  ```
+- 支持的转换类型: RequestHeader, ResponseHeader, PathPrefix, PathRemovePrefix 等
+
+### 租户关联
+
+- **GwTenant 删除**: 不再单独维护网关租户表
+- **关联方式**: 通过 `TenantCode` 直接关联 Platform.Tenant
+- **TenantCode 来源**: 
+  - 已登录用户: 从 User.TenantInfo.TenantCode 获取
+  - 请求头: 从 `X-Tenant-Code` 获取
+
+### ID 类型约定
+
+| 实体 | ID 类型 | 原因 |
+|------|---------|------|
+| GwTenantRoute | `string` (GUID v7) | 与 YARP RouteId 一致 |
+| GwCluster | `string` (GUID) | 与 YARP ClusterId 一致 |
+| GwDestination | 无独立 ID | 内嵌值对象 |
+
+### Claude's Discretion
+
+- Transforms JSON 的具体结构和验证规则
+- HealthCheckConfig 和 SessionAffinityConfig 的详细字段设计
+- Header 匹配规则 JSON 的完整 Schema
+- 错误处理和验证逻辑
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- 会话亲和 Header 名称: `X-Session-Key`
+- 健康检查默认路径: `/health`
+- 负载均衡默认策略: `PowerOfTwoChoices` (YARP 推荐)
+- Header 匹配采用 JSON 格式，支持运行时动态配置
+
+</specifics>
+
+<code_context>
+## Existing Code Insights
+
+### 需要删除的文件
+- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwTenant.cs`
+- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwServiceInstance.cs`
+
+### 需要修改的文件
+- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwTenantRoute.cs` - 扩展字段
+- `Fengling.Platform.Infrastructure/PlatformDbContext.cs` - 更新 DbSet 和配置
+- `Fengling.Platform.Infrastructure/IInstanceStore.cs` - 删除或改为 IClusterStore
+- `Fengling.Platform.Infrastructure/InstanceStore.cs` - 删除或改为 ClusterStore
+
+### 需要新增的文件
+- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwCluster.cs`
+- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwDestination.cs`
+- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwHealthCheckConfig.cs`
+- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwSessionAffinityConfig.cs`
+- `Fengling.Platform.Infrastructure/IClusterStore.cs`
+- `Fengling.Platform.Infrastructure/ClusterStore.cs`
+
+### 参考资源
+- YARP 配置模型文档: `docs/yarp-configuration-model.md`
+- YARP 官方仓库: https://github.com/microsoft/reverse-proxy
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+- 被动健康检查 (Passive Health Check) - 可在后续版本添加
+- 限流策略配置 (RateLimiterPolicy) - 可在后续版本添加
+- 授权策略配置 (AuthorizationPolicy) - 可在后续版本添加
+- CORS 策略配置 (CorsPolicy) - 可在后续版本添加
+
+</deferred>
+
+---
+
+*Phase: 03-*
+*Context gathered: 2026-03-03*
--- a/docs/yarp-configuration-model.md
+++ b/docs/yarp-configuration-model.md
@ -0,0 +1,293 @@
+# YARP 配置模型分析
+
+**来源:** [microsoft/reverse-proxy](https://github.com/microsoft/reverse-proxy)  
+**日期:** 2026-03-03
+
+---
+
+## 核心概念
+
+YARP (Yet Another Reverse Proxy) 的配置模型由三个核心接口/类组成：
+
+1. **IProxyConfigProvider** - 配置数据源接口
+2. **IProxyConfig** - 配置快照接口
+3. **RouteConfig / ClusterConfig** - 路由和集群配置
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    IProxyConfigProvider                     │
+│                     GetConfig() → IProxyConfig              │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      IProxyConfig                           │
+│  ┌─────────────────────┐  ┌─────────────────────┐          │
+│  │   RouteConfig[]     │  │   ClusterConfig[]   │          │
+│  │   (路由规则)         │  │   (集群配置)         │          │
+│  └─────────────────────┘  └─────────────────────┘          │
+│  ChangeToken: IChangeToken (配置变更通知)                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 1. RouteConfig (路由配置)
+
+路由定义了如何匹配传入请求并将其代理到集群。
+
+### 核心字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `RouteId` | `string` | ✓ | 全局唯一路由标识 |
+| `Match` | `RouteMatch` | ✓ | 请求匹配规则 |
+| `ClusterId` | `string` | ○ | 目标集群 ID |
+| `Order` | `int?` | ○ | 路由优先级 (数值越小优先级越高) |
+| `AuthorizationPolicy` | `string?` | ○ | 授权策略名称 |
+| `RateLimiterPolicy` | `string?` | ○ | 限流策略名称 |
+| `TimeoutPolicy` | `string?` | ○ | 超时策略名称 |
+| `CorsPolicy` | `string?` | ○ | CORS 策略名称 |
+| `MaxRequestBodySize` | `long?` | ○ | 请求体最大大小 |
+| `Metadata` | `IReadOnlyDictionary<string, string>?` | ○ | 自定义元数据 |
+| `Transforms` | `IReadOnlyList<IReadOnlyDictionary<string, string>>?` | ○ | 请求/响应转换规则 |
+
+### RouteMatch (匹配规则)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `Methods` | `IReadOnlyList<string>?` | HTTP 方法列表 (GET, POST 等) |
+| `Hosts` | `IReadOnlyList<string>?` | Host 头匹配 (支持通配符) |
+| `Path` | `string?` | 路径模式 (如 `/api/{**catch-all}`) |
+| `Headers` | `IReadOnlyList<RouteHeader>?` | 请求头匹配规则 |
+| `QueryParameters` | `IReadOnlyList<RouteQueryParameter>?` | 查询参数匹配规则 |
+
+---
+
+## 2. ClusterConfig (集群配置)
+
+集群是一组等价的后端服务端点及其相关策略。
+
+### 核心字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `ClusterId` | `string` | ✓ | 全局唯一集群标识 |
+| `Destinations` | `IReadOnlyDictionary<string, DestinationConfig>?` | ○ | 目标端点字典 |
+| `LoadBalancingPolicy` | `string?` | ○ | 负载均衡策略 |
+| `SessionAffinity` | `SessionAffinityConfig?` | ○ | 会话亲和配置 |
+| `HealthCheck` | `HealthCheckConfig?` | ○ | 健康检查配置 |
+| `HttpClient` | `HttpClientConfig?` | ○ | HTTP 客户端配置 |
+| `HttpRequest` | `ForwarderRequestConfig?` | ○ | 出站请求配置 |
+| `Metadata` | `IReadOnlyDictionary<string, string>?` | ○ | 自定义元数据 |
+
+### DestinationConfig (目标端点)
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `Address` | `string` | ✓ | 后端地址 (如 `https://127.0.0.1:8080/`) |
+| `Health` | `string?` | ○ | 主动健康检查端点 |
+| `Host` | `string?` | ○ | Host 头值 |
+| `Metadata` | `IReadOnlyDictionary<string, string>?` | ○ | 自定义元数据 |
+
+---
+
+## 3. 负载均衡策略
+
+YARP 内置以下负载均衡策略：
+
+| 策略名称 | 说明 |
+|----------|------|
+| `RoundRobin` | 轮询 |
+| `LeastRequests` | 最少请求 |
+| `Random` | 随机 |
+| `PowerOfTwoChoices` | 二选一 (推荐默认) |
+| `First` | 第一个 |
+| `WeightedRoundRobin` | 加权轮询 |
+
+> **注意:** `WeightedRoundRobin` 需要在 Destination 的 Metadata 中配置 `Weight` 字段。
+
+---
+
+## 4. 健康检查配置
+
+### HealthCheckConfig
+
+```csharp
+public sealed record HealthCheckConfig
+{
+    public PassiveHealthCheckConfig? Passive { get; init; }  // 被动健康检查
+    public ActiveHealthCheckConfig? Active { get; init; }    // 主动健康检查
+    public string? AvailableDestinationsPolicy { get; init; } // 可用目标策略
+}
+```
+
+### ActiveHealthCheckConfig (主动健康检查)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `Enabled` | `bool?` | 是否启用 |
+| `Interval` | `TimeSpan?` | 检查间隔 |
+| `Timeout` | `TimeSpan?` | 超时时间 |
+| `Policy` | `string?` | 健康检查策略 |
+| `Path` | `string?` | 健康检查路径 |
+
+### PassiveHealthCheckConfig (被动健康检查)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `Enabled` | `bool?` | 是否启用 |
+| `Policy` | `string?` | 策略名称 |
+| `ReactivationPeriod` | `TimeSpan?` | 重新激活周期 |
+
+---
+
+## 5. 会话亲和配置
+
+### SessionAffinityConfig
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `Enabled` | `bool?` | ○ | 是否启用 |
+| `Policy` | `string?` | ○ | 策略 (Cookie, Header) |
+| `FailurePolicy` | `string?` | ○ | 失败处理策略 |
+| `AffinityKeyName` | `string` | ✓ | 亲和键名称 |
+| `Cookie` | `SessionAffinityCookieConfig?` | ○ | Cookie 配置 |
+
+---
+
+## 6. 动态配置更新
+
+### IProxyConfig 接口
+
+```csharp
+public interface IProxyConfig
+{
+    string RevisionId { get; }              // 配置版本 ID
+    IReadOnlyList<RouteConfig> Routes { get; }
+    IReadOnlyList<ClusterConfig> Clusters { get; }
+    IChangeToken ChangeToken { get; }       // 配置变更通知
+}
+```
+
+### 配置更新机制
+
+1. **ChangeToken**: 当配置发生变化时，`ChangeToken` 会触发通知
+2. **RevisionId**: 每次配置更新都会生成新的版本 ID
+3. **YARP 内部**: 监听 `ChangeToken`，触发时重新加载配置
+
+### 实现动态更新的方式
+
+```csharp
+public class CustomConfigProvider : IProxyConfigProvider
+{
+    private volatile CustomProxyConfig _config;
+    
+    public IProxyConfig GetConfig() => _config;
+    
+    public void UpdateConfig(List<RouteConfig> routes, List<ClusterConfig> clusters)
+    {
+        var oldConfig = _config;
+        _config = new CustomProxyConfig(routes, clusters);
+        oldConfig.SignalChange(); // 触发 ChangeToken
+    }
+}
+```
+
+---
+
+## 7. 与现有实体的映射关系
+
+### GwTenantRoute → RouteConfig
+
+| GwTenantRoute 字段 | RouteConfig 字段 | 映射说明 |
+|-------------------|------------------|----------|
+| `Id` | `RouteId` | 直接映射 |
+| `PathPattern` | `Match.Path` | 路径匹配模式 |
+| `ClusterId` | `ClusterId` | 目标集群 |
+| `Priority` | `Order` | 路由优先级 |
+| `TenantCode` | `Metadata["TenantCode"]` | 租户标识 (元数据) |
+| `ServiceName` | `Metadata["ServiceName"]` | 服务名称 (元数据) |
+| `IsGlobal` | `Metadata["IsGlobal"]` | 全局路由标记 |
+
+### GwServiceInstance → DestinationConfig
+
+| GwServiceInstance 字段 | DestinationConfig 字段 | 映射说明 |
+|-----------------------|------------------------|----------|
+| `Address` | `Address` | 后端地址 |
+| `Health` | `Health` | 健康检查端点 |
+| `Weight` | `Metadata["Weight"]` | 权重 (加权负载均衡) |
+| `DestinationId` | Dictionary Key | 目标字典的 Key |
+
+### 多租户路由生成逻辑
+
+```
+for each GwTenantRoute:
+    routeId = $"{TenantCode}_{ServiceName}" or Id
+    routeConfig = new RouteConfig {
+        RouteId = routeId,
+        Match = new RouteMatch { Path = PathPattern },
+        ClusterId = ClusterId,
+        Order = Priority,
+        Metadata = { TenantCode, ServiceName, IsGlobal }
+    }
+```
+
+---
+
+## 8. 实体结构对比与建议
+
+### 当前实体 vs YARP 需求
+
+| 方面 | 当前实体 | YARP 需求 | 差异 |
+|------|----------|-----------|------|
+| 路由匹配 | 只有 `PathPattern` | `Methods`, `Hosts`, `Headers`, `QueryParameters` | 缺少高级匹配 |
+| 负载均衡 | 无配置 | `LoadBalancingPolicy` | 缺少策略配置 |
+| 会话亲和 | 无配置 | `SessionAffinityConfig` | 缺少会话保持 |
+| 转换规则 | 无配置 | `Transforms` | 缺少请求/响应转换 |
+| 授权策略 | 无配置 | `AuthorizationPolicy` | 缺少授权配置 |
+| 限流 | 无配置 | `RateLimiterPolicy` | 缺少限流配置 |
+
+### 建议新增字段
+
+**GwTenantRoute 新增:**
+
+```csharp
+// 匹配规则扩展
+public string? Methods { get; set; }           // GET,POST,PUT
+public string? Hosts { get; set; }             // api.example.com
+
+// 策略配置
+public string? LoadBalancingPolicy { get; set; }  // RoundRobin, WeightedRoundRobin
+public string? AuthorizationPolicy { get; set; }   // 授权策略
+public string? RateLimiterPolicy { get; set; }     // 限流策略
+public string? CorsPolicy { get; set; }            // CORS 策略
+
+// 转换规则 (JSON)
+public string? Transforms { get; set; }         // 请求/响应转换
+
+// 会话亲和
+public bool SessionAffinityEnabled { get; set; }
+public string? SessionAffinityPolicy { get; set; }  // Cookie, Header
+public string? SessionAffinityKeyName { get; set; }
+```
+
+**GwServiceInstance 新增:**
+
+```csharp
+// 健康检查
+public string? HealthCheckPath { get; set; }   // /health
+public int? HealthCheckInterval { get; set; }  // 秒
+
+// 主动健康检查端点
+public string? HealthEndpoint { get; set; }    // http://host:port/health
+```
+
+---
+
+## 9. 参考资源
+
+- [YARP 官方文档](https://microsoft.github.io/reverse-proxy/)
+- [YARP GitHub 仓库](https://github.com/microsoft/reverse-proxy)
+- [配置提供程序示例](https://github.com/microsoft/reverse-proxy/tree/main/samples)
+- [Yarp.EfCore.Configuration](https://github.com/microsoft/reverse-proxy/tree/main/samples/Yarp.EfCore.Configuration) - EF Core 数据库配置示例