网关概述

在微服务架构中，不同的服务一般会有不同的网络地址，如果让客户端直接与各个微服务通信，会产生以下问题：

  • 客户端需要多次请求不同的微服务，增加客户端复杂性
  • 存在跨域请求处理问题
  • 认证分散，每个服务都需要独立认证
  • 微服务重构时客户端需要同步修改
  • 部分微服务使用内部通信协议（RPC/TCP），外部无法直接访问

网关作为介于客户端和微服务集群之间的中间层，统一处理认证、限流、监控、路由等横切关注点，业务微服务专注于业务逻辑本身。

gateway1.png

silky 网关的设计

silky 的普通微服务默认使用 TCP 协议（RPC 默认端口 2200）与集群内其他服务通信，通过 rpc.token 保证外部无法直接访问 RPC 端口。

silky 网关的职责：

  • 接收外部 HTTP 请求
  • 通过 WebAPI + HTTP 方法 在路由表中定位对应的服务条目
  • 通过 RPC 与服务提供者通信，将结果封装返回给前端
  • 提供认证授权、限流、Dashboard 监控等能力

v3.x 特性：网关无需逐个引用各微服务应用接口层的 NuGet 包，只需与业务微服务接入同一服务注册中心，即可自动获取所有服务的路由信息并生成聚合 Swagger 文档。

构建网关应用

步骤一：安装包并构建主机

安装 Silky.Agent.Host 包，在 Program.cs 中构建网关主机：

using Microsoft.Extensions.Hosting;

var hostBuilder = Host.CreateDefaultBuilder(args)
    .ConfigureSilkyGatewayDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    });

await hostBuilder.Build().RunAsync();

步骤二：在 Startup.cs 中配置服务和中间件

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services
            .AddSilkyHttpCore()        // Silky HTTP 核心（必须）
            .AddRouting()
            .AddSwaggerDocuments()     // 聚合 Swagger 文档
            .AddSilkyIdentity()        // 统一身份认证（可选）
            .AddSilkyMiniProfiler();   // 性能分析面板（可选）
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            app.UseSwaggerDocuments();
            app.UseMiniProfiler();
        }

        app.UseRouting();
        app.UseSilkyIdentity();         // 统一身份认证
        app.UseSilkyWebSocketsProxy();  // WebSocket 代理（可选）

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapSilkyRpcServices();      // 映射 RPC 服务路由
            endpoints.MapSilkyDashboardServices(); // 映射 Dashboard（可选）
        });
    }
}

步骤三：配置文件

rpc:
  token: ypjdYOzNd4FwENJiEARMLWwK0v7QUHPW  # 集群统一 token，所有服务必须一致

registryCenter:
  type: Consul  # 支持 Zookeeper / Nacos / Consul
  connectionStrings: http://127.0.0.1:8500

distributedCache:
  redis:
    isEnabled: true
    configuration: 127.0.0.1:6379,defaultDatabase=0,password=qwe!P4ss

通过网关实现微服务集群的健康检查

silky 网关内置了对微服务实例的健康检查支持。通过在 Startup 中注册 Dashboard 服务，开发者可以在网关的管理端查看集群中各服务实例的健康状态，包括 CPU 使用率、连接状态等信息。

在 Startup.ConfigureServices 中引入健康检查：

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddSilkyHttpCore()
        .AddRouting()
        .AddSwaggerDocuments()
        .AddHealthChecks()           // 添加健康检查
        .AddSilkyRpc();              // 注册 RPC 健康检查探针
}

在路由中映射 Dashboard 端点：

app.UseEndpoints(endpoints =>
{
    endpoints.MapSilkyRpcServices();
    endpoints.MapSilkyDashboardServices(); // 开启 Dashboard 管理端
    endpoints.MapHealthChecks("/healthz"); // 健康检查端点
});

统一响应包装（ResponseWrapper）

silky 网关会对所有经过它转发的 RPC 响应进行统一包装，返回标准结构体：

{
  "data": { ... },          // 实际返回值（成功时）
  "errorMessage": null,     // 错误信息（失败时）
  "status": "200",
  "statusCode": "Success"
}

当 RPC 调用发生业务异常（如 UserFriendlyException）时，包装结构会携带错误信息：

{
  "data": null,
  "errorMessage": "订单不存在",
  "status": "500",
  "statusCode": "BusinessError"
}

跳过响应包装

以下情况会自动跳过包装：

  • 路径匹配 Gateway:IgnoreWrapperPathPatterns 中配置的正则（默认包含静态资源、健康检查路径）
  • 服务条目或服务条目描述符明确标记不需要包装

在配置文件中追加自定义免包装路径：

Gateway:
  IgnoreWrapperPathPatterns:
    - "\\/.*\\.(js|css|html|png|jpg|ico)"
    - "\\/(healthchecks|healthz)"
    - "\\/api\\/file\\/.*"     # 文件下载接口不包装

请求处理管道

一次外部 HTTP 请求在网关中的完整处理流水线：

外部 HTTP 请求
    │
    ▼
UseRouting()                    ← ASP.NET Core 路由中间件，匹配服务条目
    │
    ▼
UseCors()                       ← 跨域处理（可选）
    │
    ▼
UseSilkyIdentity()              ← JWT 身份认证与鉴权（可选）
    │
    ▼
UseClientRateLimiting()         ← 客户端限流（可选）
UseIpRateLimiting()             ← IP 限流（可选）
    │
    ▼
WrapperResponseMiddleware       ← 统一响应包装
    │
    ▼
UseEndpoints()
  └── MapSilkyRpcServices()     ← 找到服务条目，执行 RPC 调用
          │
          ▼
      本地执行 or 远程 RPC 调用（DotNetty TCP）
          │
          ▼
      返回结果 → 包装 → HTTP Response

微服务集群 Dashboard 管理端

silky 网关集成了 Dashboard 管理端，开发者可以通过 Dashboard 对微服务集群进行可视化管理。Dashboard 提供以下功能：

功能说明
服务实例监控查看当前注册中心中所有服务实例的状态、IP、端口、RPC 监控指标
服务条目查看浏览所有服务条目的路由、HTTP 方法、治理参数等元数据
端点健康状态查看各端点的健康状态、熔断状态、失败次数
手动下线端点将不健康的服务实例从路由表中临时移除

启用 Dashboard

在 Startup.Configure 中注册 Dashboard 路由：

app.UseEndpoints(endpoints =>
{
    endpoints.MapSilkyRpcServices();
    endpoints.MapSilkyDashboardServices(); // 注册 Dashboard 路由
});

Dashboard 的认证、登录接口、轮询间隔等行为通过 Dashboard 配置节点控制，详见配置文档。

WebSocket 代理

网关可以作为 WebSocket 请求的代理，将前端 WebSocket 连接透明转发到后端 WebSocket 微服务。

在 Startup.Configure 中添加 WebSocket 代理中间件：

app.UseRouting();
app.UseSilkyWebSocketsProxy();  // 必须在 UseRouting 之后
app.UseEndpoints(endpoints =>
{
    endpoints.MapSilkyRpcServices();
});

WebSocket 连接的路由规则与 HTTP 路由共用同一套服务条目路由表。

与其他模块的协作

模块网关中的用途
Silky.Http.Identity提供统一 JWT 身份认证，网关配置 Gateway:JwtSecret；业务微服务通过 RPC 附件传递用户信息
Silky.Http.CorsAccessor在网关层集中处理 CORS，避免业务微服务各自配置
Silky.Http.Swagger聚合所有微服务的 API 文档，网关无需引用各接口程序集
Silky.Http.RateLimit在网关层对外部 HTTP 请求进行 IP 和客户端维度的限流
Silky.Http.Auditing在网关层记录所有外部 HTTP 请求的审计日志
Silky.Http.MiniProfiler在 Swagger UI 嵌入请求耗时分析面板（仅开发环境）
Silky.Http.Dashboard提供微服务集群的可视化管理端
services.AddSilkyHttpCore()
    .AddSwaggerDocuments()
    .AddRouting();
// Dashboard 已内置在 SilkyHttpCore 中，无需额外注册

在路由中映射 Dashboard 端点：

app.UseEndpoints(endpoints =>
{
    endpoints.MapSilkyRpcServices();
    endpoints.MapSilkyDashboardServices(); // 开启 Dashboard 管理端
});

通过网关实现集群的统一认证与授权

silky 推荐在网关层统一进行身份认证与鉴权，各微服务专注业务逻辑，无需重复实现认证逻辑。

认证流程：

  1. 客户端携带 JWT Token 发起 HTTP 请求到网关
  2. 网关的认证中间件（UseSilkyIdentity()）对 Token 进行验证
  3. Token 合法后，将用户信息注入 RPC 调用上下文，转发给目标微服务
  4. 目标微服务通过 RPC 上下文获取当前用户信息（NullSession.Instance）

详细配置请参考 身份认证与授权 文档。

微服务集群 Dashboard 管理端

silky 网关集成了 Dashboard 管理端，开发者可以通过 Dashboard 对微服务集群进行可视化管理。Dashboard 提供以下功能：

  • 查看所有服务实例的状态（在线 / 离线）
  • 查看各服务条目的配置（路由、治理策略等）
  • 查看服务实例的实时性能指标（CPU、连接数等）
  • 手动下线不健康的服务实例