fengling-platform/.planning/phases/03-/03-CONTEXT.md

Phase 3: 调整网关部分的需求 - Context

Gathered: 2026-03-03 Status: Ready for planning

## Phase Boundary

调整 Gateway 模块的实体结构和 YARP 集成方式，包括：

• 重构实体模型（删除 GwTenant 和 GwServiceInstance，新增 GwCluster）
• 扩展 GwTenantRoute 的匹配和转换能力
• 实现与 YARP 配置模型的完整对接

## 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 数组
• 示例:

  [
    {"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
• 错误处理和验证逻辑

## Specific Ideas

• 会话亲和 Header 名称: X-Session-Key
• 健康检查默认路径: /health
• 负载均衡默认策略: PowerOfTwoChoices (YARP 推荐)
• Header 匹配采用 JSON 格式，支持运行时动态配置

<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 Ideas

• 被动健康检查 (Passive Health Check) - 可在后续版本添加
• 限流策略配置 (RateLimiterPolicy) - 可在后续版本添加
• 授权策略配置 (AuthorizationPolicy) - 可在后续版本添加
• CORS 策略配置 (CorsPolicy) - 可在后续版本添加

---

Phase: 03- Context gathered: 2026-03-03