465 lines
18 KiB
Markdown
465 lines
18 KiB
Markdown
# 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/` |