199 lines
6.7 KiB
Markdown
199 lines
6.7 KiB
Markdown
# 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* |