LingAdmin/Backend/Services/ApiGateway/README.md

LingAdmin API Gateway

API 网关服务 - 负责请求路由、认证、限流、日志记录等功能。

服务信息

属性	值
端口	5000
Dapr App ID	api-gateway
Dapr HTTP Port	3500

核心功能

1. 请求路由 (YARP)

使用 YARP (Yet Another Reverse Proxy) 进行请求路由：

路由规则	目标服务	需要认证
/api/auth/*	identity-service	❌
/api/users/*	identity-service	✅
/api/roles/*	authorization-service	✅
/api/authorization/*	authorization-service	❌/✅
/api/permissions/*	authorization-service	✅

2. JWT 认证

• 验证所有带 Authorization: Bearer <token> 的请求
• 配置必须与 Identity Service 保持一致

3. 请求限流

• 基于 IP 地址限流
• 默认限制: 100 次请求/分钟
• 超限返回 429 状态码

4. 请求日志

• 记录请求开始和结束
• 记录响应状态码和耗时
• 添加请求追踪 ID (X-Request-Id)

API 端点

健康检查

方法	路径	描述
GET	/api/health	网关健康状态
GET	/api/health/services	所有服务健康状态

启动方式

独立启动

cd LingAdmin.ApiGateway
dotnet run

使用 Dapr 启动

dapr run --app-id api-gateway --app-port 5000 --dapr-http-port 3500 --resources-path ../dapr/components -- dotnet run

配置说明

appsettings.json

{
  "JwtSettings": {
    "SecretKey": "与其他服务相同的 JWT 密钥",
    "Issuer": "Token 发行者",
    "Audience": "Token 接收者"
  },
  "Services": {
    "IdentityService": {
      "BaseUrl": "http://localhost:5001",
      "DaprAppId": "identity-service"
    },
    "AuthorizationService": {
      "BaseUrl": "http://localhost:5002",
      "DaprAppId": "authorization-service"
    }
  },
  "ReverseProxy": {
    "Routes": { ... },
    "Clusters": { ... }
  }
}

路由配置

{
  "ReverseProxy": {
    "Routes": {
      "auth-route": {
        "ClusterId": "identity-cluster",
        "Match": {
          "Path": "/api/auth/{**catch-all}"
        }
      },
      "users-route": {
        "ClusterId": "identity-cluster",
        "AuthorizationPolicy": "default",
        "Match": {
          "Path": "/api/users/{**catch-all}"
        }
      }
    },
    "Clusters": {
      "identity-cluster": {
        "Destinations": {
          "identity-service": {
            "Address": "http://localhost:5001"
          }
        }
      }
    }
  }
}

添加新路由

要为新的微服务添加路由:

1. 在 Clusters 中添加新的集群配置
2. 在 Routes 中添加新的路由规则
3. 根据需要配置认证策略

示例:

{
  "ReverseProxy": {
    "Routes": {
      "new-service-route": {
        "ClusterId": "new-service-cluster",
        "AuthorizationPolicy": "default",
        "Match": {
          "Path": "/api/new-service/{**catch-all}"
        }
      }
    },
    "Clusters": {
      "new-service-cluster": {
        "Destinations": {
          "new-service": {
            "Address": "http://localhost:5003"
          }
        }
      }
    }
  }
}

自定义限流

修改 Program.cs 中的限流配置:

builder.Services.AddRateLimiter(options =>
{
    options.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(context =>
        RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: context.Connection.RemoteIpAddress?.ToString() ?? "anonymous",
            factory: _ => new FixedWindowRateLimiterOptions
            {
                PermitLimit = 100,        // 请求次数限制
                Window = TimeSpan.FromMinutes(1)  // 时间窗口
            }));
});

响应头

网关会添加以下响应头:

头名称	描述
X-Request-Id	请求唯一标识
X-Correlation-Id	关联 ID (从请求头传递或新生成)