# YARP Gateway 目录结构文档

## 1. 目录布局

```
fengling-gateway/
├── .planning/                          # 规划文档目录
│   └── codebase/                       # 代码库分析文档
│       ├── ARCHITECTURE.md             # 架构文档
│       └── STRUCTURE.md                # 本文档
│
├── src/                                # 源代码目录
│   ├── Config/                         # 配置类和提供者
│   ├── Controllers/                    # API 控制器
│   ├── Data/                           # 数据访问层
│   ├── DynamicProxy/                   # YARP 动态代理
│   ├── LoadBalancing/                  # 负载均衡策略
│   ├── Migrations/                     # 数据库迁移
│   ├── Metrics/                        # 监控指标
│   ├── Middleware/                     # 中间件
│   ├── Models/                         # 数据模型
│   ├── Properties/                     # 项目属性
│   ├── Services/                       # 业务服务
│   ├── Program.cs                      # 程序入口
│   ├── YarpGateway.csproj              # 项目文件
│   ├── appsettings.json                # 配置文件
│   └── appsettings.Development.json    # 开发环境配置
│
└── (根目录其他文件)
```

---

## 2. 详细目录说明

### 2.1 Config/ - 配置层

**路径**: `src/Config/`

**用途**: 存放配置模型和配置提供者

| 文件 | 行数 | 用途 |
|------|------|------|
| `JwtConfig.cs` | 10 | JWT 认证配置模型，包含 Authority、Audience 等属性 |
| `RedisConfig.cs` | 9 | Redis 连接配置模型，包含连接字符串、数据库索引等 |
| `ConfigNotifyChannel.cs` | 7 | PostgreSQL NOTIFY 通道名称常量定义 |
| `DatabaseRouteConfigProvider.cs` | 84 | 从数据库加载路由配置，转换为 YARP RouteConfig |
| `DatabaseClusterConfigProvider.cs` | 100 | 从数据库加载集群配置，管理服务实例列表 |

**设计特点**:
- 配置类使用 POCO 模型，通过 Options 模式注入
- Provider 类使用单例模式，支持热重载

---

### 2.2 Controllers/ - 控制器层

**路径**: `src/Controllers/`

**用途**: RESTful API 端点

| 文件 | 行数 | 路由前缀 | 用途 |
|------|------|----------|------|
| `GatewayConfigController.cs` | 489 | `/api/gateway` | 网关配置管理 API |
| `PendingServicesController.cs` | 210 | `/api/gateway/pending-services` | 待处理服务管理 API |

**GatewayConfigController 端点**:

| 方法 | 路由 | 功能 |
|------|------|------|
| GET | `/tenants` | 获取租户列表（分页） |
| GET | `/tenants/{id}` | 获取单个租户 |
| POST | `/tenants` | 创建租户 |
| PUT | `/tenants/{id}` | 更新租户 |
| DELETE | `/tenants/{id}` | 删除租户 |
| GET | `/routes` | 获取路由列表（分页） |
| GET | `/routes/global` | 获取全局路由 |
| GET | `/routes/tenant/{tenantCode}` | 获取租户路由 |
| POST | `/routes` | 创建路由 |
| PUT | `/routes/{id}` | 更新路由 |
| DELETE | `/routes/{id}` | 删除路由 |
| GET | `/clusters` | 获取集群列表 |
| GET | `/clusters/{clusterId}` | 获取集群详情 |
| POST | `/clusters` | 创建集群 |
| DELETE | `/clusters/{clusterId}` | 删除集群 |
| GET | `/clusters/{clusterId}/instances` | 获取实例列表 |
| POST | `/clusters/{clusterId}/instances` | 添加实例 |
| DELETE | `/instances/{id}` | 删除实例 |
| POST | `/config/reload` | 重载配置 |
| GET | `/config/status` | 获取配置状态 |
| GET | `/config/versions` | 获取版本信息 |
| GET | `/stats/overview` | 获取统计概览 |

**PendingServicesController 端点**:

| 方法 | 路由 | 功能 |
|------|------|------|
| GET | `/` | 获取待处理服务列表 |
| GET | `/{id}` | 获取待处理服务详情 |
| POST | `/{id}/assign` | 分配服务到集群 |
| POST | `/{id}/reject` | 拒绝服务 |
| GET | `/clusters` | 获取可用集群列表 |

---

### 2.3 Data/ - 数据访问层

**路径**: `src/Data/`

**用途**: Entity Framework Core 数据库上下文

| 文件 | 行数 | 用途 |
|------|------|------|
| `GatewayDbContext.cs` | 142 | EF Core 数据库上下文，包含实体配置和变更通知 |
| `GatewayDbContextFactory.cs` | 23 | 设计时 DbContext 工厂，用于迁移命令 |

**DbContext 特性**:
- 自动检测配置变更
- 集成 PostgreSQL NOTIFY 机制
- 支持软删除（IsDeleted 标记）
- 版本号追踪（Version 字段）

---

### 2.4 DynamicProxy/ - 动态代理层

**路径**: `src/DynamicProxy/`

**用途**: YARP 动态配置提供

| 文件 | 行数 | 用途 |
|------|------|------|
| `DynamicProxyConfigProvider.cs` | 79 | 实现 IProxyConfigProvider，整合路由和集群配置 |

**核心职责**:
- 实现 YARP 配置提供接口
- 协调 Route 和 Cluster 配置
- 提供配置变更通知（通过 CancellationToken）

---

### 2.5 LoadBalancing/ - 负载均衡层

**路径**: `src/LoadBalancing/`

**用途**: 自定义负载均衡策略

| 文件 | 行数 | 用途 |
|------|------|------|
| `DistributedWeightedRoundRobinPolicy.cs` | 244 | 基于 Redis 的分布式加权轮询策略 |

**策略特点**:
- 策略名称: `DistributedWeightedRoundRobin`
- 支持实例权重配置
- Redis 分布式状态存储
- 降级策略（锁获取失败时）

---

### 2.6 Migrations/ - 数据库迁移

**路径**: `src/Migrations/`

**用途**: Entity Framework Core 迁移文件

| 文件 | 用途 |
|------|------|
| `20260201120312_InitialCreate.cs` | 初始数据库创建 |
| `20260201133826_AddIsGlobalToTenantRoute.cs` | 添加 IsGlobal 字段 |
| `20260222134342_AddPendingServiceDiscovery.cs` | 添加待处理服务发现表 |
| `*ModelSnapshot.cs` | 当前模型快照 |
| `*.Designer.cs` | 设计器生成文件 |

---

### 2.7 Metrics/ - 监控指标

**路径**: `src/Metrics/`

**用途**: OpenTelemetry 指标定义

| 文件 | 行数 | 用途 |
|------|------|------|
| `GatewayMetrics.cs` | 31 | 定义网关监控指标 |

**指标列表**:
- `gateway_requests_total` - 请求总数计数器
- `gateway_request_duration_seconds` - 请求延迟直方图

---

### 2.8 Middleware/ - 中间件层

**路径**: `src/Middleware/`

**用途**: ASP.NET Core 中间件

| 文件 | 行数 | 用途 |
|------|------|------|
| `JwtTransformMiddleware.cs` | 84 | JWT Token 解析，提取租户信息注入请求头 |
| `TenantRoutingMiddleware.cs` | 64 | 租户路由解析，根据路径查找目标集群 |

**中间件执行顺序**:
```
CORS -> JwtTransformMiddleware -> TenantRoutingMiddleware -> YARP
```

---

### 2.9 Models/ - 数据模型层

**路径**: `src/Models/`

**用途**: 实体类定义

| 文件 | 行数 | 用途 |
|------|------|------|
| `GwTenant.cs` | 16 | 租户实体 |
| `GwTenantRoute.cs` | 20 | 路由配置实体 |
| `GwServiceInstance.cs` | 19 | 服务实例实体 |
| `GwPendingServiceDiscovery.cs` | 28 | 待处理服务发现实体 + 状态枚举 |

**实体通用字段**:
- `Id` - 主键（雪花 ID 格式）
- `Status` - 状态（1=启用）
- `CreatedBy/UpdatedBy` - 操作人
- `CreatedTime/UpdatedTime` - 时间戳
- `IsDeleted` - 软删除标记
- `Version` - 版本号（乐观锁）

---

### 2.10 Services/ - 服务层

**路径**: `src/Services/`

**用途**: 业务逻辑和后台服务

| 文件 | 行数 | 类型 | 用途 |
|------|------|------|------|
| `RouteCache.cs` | 139 | Singleton | 路由缓存，支持租户路由和全局路由 |
| `RedisConnectionManager.cs` | 139 | Singleton | Redis 连接管理，分布式锁实现 |
| `PgSqlConfigChangeListener.cs` | 223 | HostedService | PostgreSQL 配置变更监听 |
| `KubernetesPendingSyncService.cs` | 162 | HostedService | Kubernetes 服务发现同步 |

**服务生命周期**:
- Singleton: RouteCache, RedisConnectionManager（状态服务）
- HostedService: PgSqlConfigChangeListener, KubernetesPendingSyncService（后台任务）

---

## 3. 关键文件位置

### 3.1 入口文件

| 文件 | 路径 | 用途 |
|------|------|------|
| `Program.cs` | `src/Program.cs` | 应用程序入口，服务注册和中间件配置 |

### 3.2 配置文件

| 文件 | 路径 | 用途 |
|------|------|------|
| `appsettings.json` | `src/appsettings.json` | 生产环境配置 |
| `appsettings.Development.json` | `src/appsettings.Development.json` | 开发环境配置 |
| `YarpGateway.csproj` | `src/YarpGateway.csproj` | 项目文件，包引用 |

### 3.3 数据库相关

| 文件 | 路径 | 用途 |
|------|------|------|
| `GatewayDbContext.cs` | `src/Data/GatewayDbContext.cs` | 数据库上下文 |
| `GatewayDbContextFactory.cs` | `src/Data/GatewayDbContextFactory.cs` | 迁移工具工厂 |

---

## 4. 命名约定

### 4.1 文件命名

| 类型 | 命名规则 | 示例 |
|------|----------|------|
| 实体类 | `Gw` 前缀 + PascalCase | `GwTenant.cs`, `GwTenantRoute.cs` |
| 配置类 | `*Config` 后缀 | `JwtConfig.cs`, `RedisConfig.cs` |
| 提供者 | `*Provider` 后缀 | `DatabaseRouteConfigProvider.cs` |
| 中间件 | `*Middleware` 后缀 | `JwtTransformMiddleware.cs` |
| 控制器 | `*Controller` 后缀 | `GatewayConfigController.cs` |
| 服务 | 功能描述 + 类型 | `RouteCache.cs`, `PgSqlConfigChangeListener.cs` |
| 策略 | `*Policy` 后缀 | `DistributedWeightedRoundRobinPolicy.cs` |

### 4.2 命名空间

```
YarpGateway                    # 根命名空间
├── Config                     # 配置相关
├── Controllers                # API 控制器
├── Data                       # 数据访问
├── DynamicProxy               # 动态代理
├── LoadBalancing              # 负载均衡
├── Metrics                    # 监控指标
├── Middleware                 # 中间件
├── Models                     # 数据模型
└── Services                   # 业务服务
```

### 4.3 接口命名

| 类型 | 命名规则 | 示例 |
|------|----------|------|
| 服务接口 | `I` 前缀 | `IRouteCache`, `IRedisConnectionManager` |
| DTO 类 | `*Dto` 后缀 | `CreateTenantDto`, `CreateRouteDto` |
| 请求类 | `*Request` 后缀 | `AssignServiceRequest` |

---

## 5. 模块组织

### 5.1 分层架构

```
┌─────────────────────────────────────────────────────────────┐
│                    Presentation Layer                        │
│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
│  │   Middleware    │    │         Controllers             │ │
│  │  - JWT 解析     │    │  - GatewayConfigController      │ │
│  │  - 租户路由     │    │  - PendingServicesController    │ │
│  └─────────────────┘    └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Business Logic Layer                      │
│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
│  │    Services     │    │       DynamicProxy              │ │
│  │  - RouteCache   │    │  - DynamicProxyConfigProvider   │ │
│  │  - RedisManager │    │                                 │ │
│  │  - ConfigListen │    └─────────────────────────────────┘ │
│  └─────────────────┘                                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Data Access Layer                         │
│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
│  │     Models      │    │            Data                 │ │
│  │  - GwTenant     │    │  - GatewayDbContext             │ │
│  │  - GwRoute      │    │  - GatewayDbContextFactory      │ │
│  │  - GwInstance   │    │                                 │ │
│  └─────────────────┘    └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 Infrastructure Layer                         │
│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
│  │     Config      │    │       LoadBalancing             │ │
│  │  - JwtConfig    │    │  - WeightedRoundRobinPolicy     │ │
│  │  - RedisConfig  │    │                                 │ │
│  │  - Providers    │    └─────────────────────────────────┘ │
│  └─────────────────┘                                         │
└─────────────────────────────────────────────────────────────┘
```

### 5.2 模块依赖关系

```
Program.cs
    │
    ├── Config/
    │   ├── JwtConfig ◄── appsettings.json
    │   ├── RedisConfig ◄── appsettings.json
    │   ├── DatabaseRouteConfigProvider ◄── Data/GatewayDbContext
    │   └── DatabaseClusterConfigProvider ◄── Data/GatewayDbContext
    │
    ├── DynamicProxy/
    │   └── DynamicProxyConfigProvider ◄── Config/*
    │
    ├── Services/
    │   ├── RouteCache ◄── Data/GatewayDbContext, Models/*
    │   ├── RedisConnectionManager ◄── Config/RedisConfig
    │   ├── PgSqlConfigChangeListener ◄── DynamicProxy, Services/RouteCache
    │   └── KubernetesPendingSyncService ◄── Data/GatewayDbContext
    │
    ├── Middleware/
    │   ├── JwtTransformMiddleware ◄── Config/JwtConfig
    │   └── TenantRoutingMiddleware ◄── Services/RouteCache
    │
    └── Controllers/
        ├── GatewayConfigController ◄── Config/*, Services/RouteCache
        └── PendingServicesController ◄── Data/GatewayDbContext
```

---

## 6. 项目依赖

### 6.1 NuGet 包引用

```xml
<!-- 核心框架 -->
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" />
<PackageReference Include="Yarp.ReverseProxy" />

<!-- 数据库 -->
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" />
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" />

<!-- 缓存 -->
<PackageReference Include="StackExchange.Redis" />

<!-- 日志 -->
<PackageReference Include="Serilog.AspNetCore" />
<PackageReference Include="Serilog.Sinks.Console" />
<PackageReference Include="Serilog.Sinks.File" />

<!-- 服务发现 -->
<PackageReference Include="Fengling.ServiceDiscovery.Core" />
<PackageReference Include="Fengling.ServiceDiscovery.Kubernetes" />
<PackageReference Include="Fengling.ServiceDiscovery.Static" />
```

### 6.2 目标框架

```xml
<TargetFramework>net10.0</TargetFramework>
```

---

## 7. 文件统计

| 目录/文件 | 文件数 | 总行数 | 主要用途 |
|-----------|--------|--------|----------|
| `Config/` | 5 | ~210 | 配置模型和提供者 |
| `Controllers/` | 2 | ~700 | REST API 端点 |
| `Data/` | 2 | ~165 | 数据库上下文 |
| `DynamicProxy/` | 1 | ~79 | YARP 配置集成 |
| `LoadBalancing/` | 1 | ~244 | 负载均衡策略 |
| `Migrations/` | 6 | ~500+ | 数据库迁移 |
| `Metrics/` | 1 | ~31 | 监控指标 |
| `Middleware/` | 2 | ~148 | 请求处理中间件 |
| `Models/` | 4 | ~83 | 数据实体 |
| `Services/` | 4 | ~665 | 业务服务 |
| `Program.cs` | 1 | 135 | 应用入口 |
| **总计** | **29** | **~2900+** | - |

---

## 8. 扩展建议

### 8.1 建议新增目录

| 目录 | 用途 |
|------|------|
| `Extensions/` | 扩展方法 |
| `Constants/` | 常量定义 |
| `Exceptions/` | 自定义异常 |
| `Validators/` | 输入验证器 |
| `Dtos/` | 数据传输对象（从 Controllers 提取） |

### 8.2 代码组织建议

1. 将 Controller 中的 DTO 类提取到独立的 `Dtos/` 目录
2. 添加 `Extensions/` 存放 IServiceCollection 扩展方法
3. 考虑将配置验证逻辑提取到 `Validators/`