movingsam 0cbb5a2c0e docs: map YARP gateway codebase

2026-02-28 15:44:16 +08:00

18 KiB

Raw Blame History

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 包引用

<!-- 核心框架 -->
<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 目标框架

<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 代码组织建议

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

18 KiB Raw Blame History Unescape Escape