# YARP 网关技术栈文档

## 1. 语言和运行时

### .NET 版本
- **目标框架**: .NET 10.0
- **项目文件**: `src/YarpGateway.csproj`
- **SDK**: `Microsoft.NET.Sdk.Web`

```xml
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
```

## 2. 核心框架

### YARP (Yet Another Reverse Proxy)
- **包**: `Yarp.ReverseProxy`
- **用途**: 微服务 API 网关核心反向代理引擎
- **主要功能**:
  - 动态路由配置
  - 负载均衡策略
  - 健康检查
  - 请求转发

### ASP.NET Core
- **用途**: Web 应用宿主框架
- **特性**:
  - 依赖注入 (DI)
  - 中间件管道
  - 配置系统
  - 日志集成

## 3. 主要依赖包

### 数据访问
| 包名 | 用途 |
|------|------|
| `Npgsql.EntityFrameworkCore.PostgreSQL` | PostgreSQL Entity Framework Core 提供程序 |
| `Microsoft.EntityFrameworkCore.Design` | EF Core 设计时工具（迁移） |

### 缓存与分布式锁
| 包名 | 用途 |
|------|------|
| `StackExchange.Redis` | Redis 客户端，用于分布式锁和缓存 |

### 认证授权
| 包名 | 用途 |
|------|------|
| `Microsoft.AspNetCore.Authentication.JwtBearer` | JWT Bearer 认证支持 |

### 日志
| 包名 | 用途 |
|------|------|
| `Serilog.AspNetCore` | Serilog ASP.NET Core 集成 |
| `Serilog.Sinks.Console` | 控制台日志输出 |
| `Serilog.Sinks.File` | 文件日志输出 |

### 服务发现（自定义包）
| 包名 | 用途 |
|------|------|
| `Fengling.ServiceDiscovery.Core` | 服务发现核心接口 |
| `Fengling.ServiceDiscovery.Kubernetes` | Kubernetes 服务发现实现 |
| `Fengling.ServiceDiscovery.Static` | 静态配置服务发现 |

## 4. 配置文件

### 主配置文件
**位置**: `src/appsettings.json`

```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=...;Port=...;Database=...;Username=...;Password=..."
  },
  "Jwt": {
    "Authority": "https://your-auth-server.com",
    "Audience": "fengling-gateway",
    "ValidateIssuer": true,
    "ValidateAudience": true
  },
  "Redis": {
    "ConnectionString": "host:port",
    "Database": 0,
    "InstanceName": "YarpGateway"
  },
  "Cors": {
    "AllowedOrigins": ["http://localhost:5173"],
    "AllowAnyOrigin": false
  },
  "Kestrel": {
    "Endpoints": {
      "Http": { "Url": "http://0.0.0.0:8080" }
    }
  },
  "Serilog": {
    "MinimumLevel": "Information",
    "WriteTo": [
      { "Name": "Console" },
      { "Name": "File", "Args": { "path": "logs/gateway-.log", "rollingInterval": "Day" } }
    ]
  }
}
```

### 配置类
| 文件路径 | 类名 | 用途 |
|----------|------|------|
| `src/Config/JwtConfig.cs` | `JwtConfig` | JWT 认证配置 |
| `src/Config/RedisConfig.cs` | `RedisConfig` | Redis 连接配置 |
| `src/Config/ConfigNotifyChannel.cs` | `ConfigNotifyChannel` | PostgreSQL NOTIFY 通道常量 |

## 5. Docker 支持

### Dockerfile
**位置**: `Dockerfile`

```dockerfile
# 基础镜像
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
EXPOSE 8080
EXPOSE 8081

# 构建镜像
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
# 多阶段构建...

# 最终镜像
FROM base AS final
ENTRYPOINT ["dotnet", "YarpGateway.dll"]
```

### Docker 配置
- **默认目标 OS**: Linux
- **暴露端口**: 8080 (HTTP), 8081 (HTTPS)
- **工作目录**: `/app`

## 6. 项目结构

```
src/
├── Config/              # 配置类
│   ├── JwtConfig.cs
│   ├── RedisConfig.cs
│   ├── ConfigNotifyChannel.cs
│   ├── DatabaseRouteConfigProvider.cs
│   └── DatabaseClusterConfigProvider.cs
├── Data/                # 数据访问层
│   ├── GatewayDbContext.cs
│   └── GatewayDbContextFactory.cs
├── DynamicProxy/        # 动态代理配置
│   └── DynamicProxyConfigProvider.cs
├── LoadBalancing/       # 负载均衡策略
│   └── DistributedWeightedRoundRobinPolicy.cs
├── Middleware/          # 中间件
│   ├── JwtTransformMiddleware.cs
│   └── TenantRoutingMiddleware.cs
├── Models/              # 数据模型
│   ├── GwTenant.cs
│   ├── GwTenantRoute.cs
│   ├── GwServiceInstance.cs
│   └── GwPendingServiceDiscovery.cs
├── Services/            # 业务服务
│   ├── RouteCache.cs
│   ├── RedisConnectionManager.cs
│   ├── KubernetesPendingSyncService.cs
│   └── PgSqlConfigChangeListener.cs
├── Program.cs           # 应用入口
├── appsettings.json     # 配置文件
└── YarpGateway.csproj   # 项目文件
```

## 7. 中间件管道

请求处理管道顺序（`Program.cs`）：

1. **CORS** - 跨域请求处理
2. **JwtTransformMiddleware** - JWT 解析与转换
3. **TenantRoutingMiddleware** - 租户路由解析
4. **Controllers** - API 控制器
5. **ReverseProxy** - YARP 反向代理

## 8. 托管与部署

### Kestrel 配置
- 监听地址: `http://0.0.0.0:8080`
- 支持 Docker 容器化部署
- 支持 Kubernetes 集群部署