[特殊字符] .NET 微服务网关（Ocelot）实战手册

🚀 .NET 微服务网关（Ocelot）实战手册

一站式路由、认证与服务治理指南

📚 目录导航

1. 网关概述：核心价值

1.1 Ocelot 是什么？

Ocelot 是 .NET 生态专属的开源 API 网关，基于 ASP.NET Core 构建，专为微服务架构设计，已成为 .NET 微服务项目的事实标准网关方案。

1.2 解决的核心痛点

微服务拆分后，Ocelot 解决了以下 .NET 项目的典型问题：

1.3 .NET 微服务架构中的网关定位

flowchart TD
    subgraph 客户端层
        前端[Web前端<br>(Vue/React)]
        APP[移动端APP]
    end
    
    subgraph 网关层
        网关[Ocelot Gateway<br>https://api.example.com]
    end
    
    subgraph 服务层
        认证服务[AuthService<br>.NET 8]
        商品服务[ProductService<br>.NET 8]
        订单服务[OrderService<br>.NET 8]
    end
    
    subgraph 数据层
        数据库1[(SQL Server<br>用户库)]
        数据库2[(SQL Server<br>商品库)]
        数据库3[(SQL Server<br>订单库)]
    end

    前端 --> 网关
    APP --> 网关
    网关 --> 认证服务
    网关 --> 商品服务
    网关 --> 订单服务
    认证服务 --> 数据库1
    商品服务 --> 数据库2
    订单服务 --> 数据库3

2. 环境搭建：从零开始

2.1 项目创建

1. 创建网关项目
   打开 Visual Studio → 新建项目 → 选择 “ASP.NET Core 空” → 命名为 OcelotGateway。

2. 安装依赖包
   通过 NuGet 包管理器安装以下核心依赖：

   # 核心网关包
   dotnet add package Ocelot --version 18.0.0
   # 服务发现（Consul 集成）
   dotnet add package Ocelot.Provider.Consul --version 18.0.0
   # Swagger 文档聚合
   dotnet add package Swashbuckle.AspNetCore.Ocelot --version 6.5.0
   # JWT 认证
   dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer --version 8.0.0
   

2.2 项目目录结构

OcelotGateway/
├── config/                      # 配置文件目录
│   ├── ocelot.development.json  # 开发环境路由配置
│   └── ocelot.production.json   # 生产环境路由配置
├── Properties/
│   └── launchsettings.json      # 启动配置
├── appsettings.json             # 全局配置
├── appsettings.Development.json # 开发环境配置
├── Program.cs                   # 启动类
└── OcelotGateway.csproj         # 项目文件

2.3 启动配置（launchsettings.json）

确保网关端口固定（便于微服务对接）：

{
  "profiles": {
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "https://localhost:5000;http://localhost:5001",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

3. 核心配置：ocelot.json 详解

Ocelot 的所有路由和特性都通过 ocelot.json 配置，以下是 .NET 项目的典型配置：

3.1 基础路由配置

// config/ocelot.development.json
{
  "Routes": [
    // 认证服务路由（登录/注册）
    {
      "Key": "AuthService",
      "DownstreamPathTemplate": "/api/auth/{everything}",
      "DownstreamScheme": "https",
      "DownstreamHostAndPorts": [
        { "Host": "localhost", "Port": 7059 } // AuthService 端口
      ],
      "UpstreamPathTemplate": "/api/auth/{everything}",
      "UpstreamHttpMethod": ["GET", "POST"],
      "Timeout": 30000,
      "RateLimitOptions": {
        "EnableRateLimiting": true,
        "Period": "1m",
        "Limit": 100,
        "Message": "请求过于频繁，请1分钟后再试"
      }
    },
    // 商品服务路由
    {
      "Key": "ProductService",
      "DownstreamPathTemplate": "/api/products/{everything}",
      "DownstreamScheme": "https",
      "DownstreamHostAndPorts": [
        { "Host": "localhost", "Port": 7060 } // ProductService 端口
      ],
      "UpstreamPathTemplate": "/api/products/{everything}",
      "UpstreamHttpMethod": ["GET", "PUT", "DELETE"],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer", // 启用 JWT 认证
        "AllowedScopes": []
      }
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "https://localhost:5000", // 网关对外地址
    "RequestIdKey": "X-Request-Id",
    "ServiceDiscoveryProvider": {
      "Type": "Consul", // 启用 Consul 服务发现
      "Host": "localhost",
      "Port": 8500
    }
  }
}

3.2 配置字段说明

4. 集成流程：ASP.NET Core 联动

4.1 启动类配置（Program.cs）

这是网关与 ASP.NET Core 集成的核心，中间件顺序至关重要：

var builder = WebApplication.CreateBuilder(args);

// 1. 加载 Ocelot 配置（按环境区分）
builder.Configuration.AddJsonFile(
    path: $"config/ocelot.{builder.Environment.EnvironmentName}.json",
    optional: false,
    reloadOnChange: true
);

// 2. 注册 Ocelot 服务
builder.Services.AddOcelot(builder.Configuration)
    .AddConsul(); // 集成 Consul 服务发现

// 3. 注册 Swagger 文档（聚合所有微服务接口）
builder.Services.AddSwaggerForOcelot(builder.Configuration, opt =>
{
    opt.GenerateDocsForGatewayItSelf = true;
    opt.SwaggerDocConfig = config =>
    {
        config.Title = "Ocelot 网关 API 文档";
        config.Version = "v1";
        config.Description = "聚合 AuthService、ProductService 等微服务接口";
    };
});

// 4. 配置 JWT 认证（网关层统一验证）
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidateAudience = true,
            ValidAudience = builder.Configuration["Jwt:Audience"],
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Secret"]!))
        };
    });

// 5. 配置跨域（允许前端访问）
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowFrontend", policy =>
    {
        policy.WithOrigins(builder.Configuration["Cors:AllowedOrigins"]!.Split(','))
              .AllowAnyHeader()
              .AllowAnyMethod()
              .AllowCredentials();
    });
});

var app = builder.Build();

// 6. 中间件顺序（严格按此执行）
if (app.Environment.IsDevelopment())
{
    app.UseSwaggerForOcelotUI(opt =>
    {
        opt.PathToSwaggerGenerator = "/swagger/docs";
        opt.DocumentTitle = "Ocelot 网关文档";
    });
}

app.UseHttpsRedirection();       // 1. HTTPS 重定向
app.UseCors("AllowFrontend");    // 2. 跨域（必须在认证前）
app.UseAuthentication();         // 3. 认证（验证 JWT）
app.UseAuthorization();          // 4. 授权（验证权限）
await app.UseOcelot();           // 5. 启动 Ocelot 网关

app.Run();

4.2 全局配置（appsettings.json）

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Ocelot": "Information", // 启用 Ocelot 日志
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Jwt": {
    "Issuer": "https://localhost:5000",
    "Audience": "https://localhost:5173",
    "Secret": "your-32-character-strong-secret-key-here",
    "ExpiresHours": 24
  },
  "Cors": {
    "AllowedOrigins": "https://localhost:5173,http://localhost:3000"
  }
}

5. 功能实战：企业级特性

5.1 JWT 认证授权

5.1.1 配置说明

1. 网关层启用认证：在 ocelot.json 中为需要保护的路由添加 AuthenticationOptions。
2. 服务层信任网关：微服务无需重复验证 JWT，直接从网关传递的 Claims 中获取用户信息。

5.1.2 微服务中获取用户信息

// ProductService 中的控制器
[ApiController]
[Route("api/products")]
[Authorize] // 信任网关传递的认证信息
public class ProductController : ControllerBase
{
    [HttpGet]
    public IActionResult GetProducts()
    {
        // 从网关传递的 Claims 中获取用户 ID
        var userId = User.FindFirstValue(JwtRegisteredClaimNames.Sub);
        // 业务逻辑...
        return Ok();
    }
}

5.2 Consul 服务发现

当微服务动态扩容时，网关自动发现新实例，无需手动修改配置：

1. 启动 Consul：本地开发可通过 Docker 启动：

   docker run -d -p 8500:8500 --name consul consul:1.15.0
   

2. 微服务注册到 Consul：在每个微服务的 Program.cs 中添加：

   builder.Services.AddConsul(option =>
   {
       option.Address = new Uri("http://localhost:8500");
   }).AddConsulServiceRegistration(option =>
   {
       option.ID = "ProductService-" + Guid.NewGuid();
       option.Name = "ProductService";
       option.Address = "localhost";
       option.Port = 7060;
       option.Check = new AgentServiceCheck
       {
           HTTP = "https://localhost:7060/health",
           Interval = TimeSpan.FromSeconds(10)
       };
   });
   

5.3 限流与熔断

5.3.1 限流配置

"RateLimitOptions": {
  "EnableRateLimiting": true,
  "Period": "1m",          // 限流周期（1分钟）
  "Limit": 100,            // 周期内最大请求数
  "Message": "请求过于频繁，请稍后再试",
  "ClientIdHeader": "X-Client-Id" // 客户端标识头
}

5.3.2 熔断配置

"QoSOptions": {
  "ExceptionsAllowedBeforeBreaking": 5, // 允许的异常次数
  "DurationOfBreak": 30,                // 熔断时间（秒）
  "TimeoutValue": 5000                  // 请求超时时间（毫秒）
}

6. 问题排查：避坑指南

6.1 常见错误及解决方案

6.2 日志排查

启用 Ocelot 详细日志，快速定位问题：

// appsettings.Development.json
"Logging": {
  "LogLevel": {
    "Ocelot": "Debug", // 启用调试日志
    "Ocelot.DownstreamRouteFinder": "Debug",
    "Ocelot.DownstreamUrlCreator": "Debug"
  }
}

7. 最佳实践：生产级建议

7.1 配置管理

1. 环境分离：开发/测试/生产环境使用不同的 ocelot.{env}.json。
2. 敏感信息加密：JWT Secret、数据库连接字符串等通过 Azure Key Vault 或 HashiCorp Vault 存储。
3. 动态配置：结合 Consul/K8s ConfigMap 实现配置热更新，无需重启网关。

7.2 监控与可观测性

7.3 高可用部署

1. 网关集群：部署多个网关实例，通过 Nginx 做负载均衡。
2. 健康检查：配置 Consul 健康检查，自动剔除故障网关实例。
3. 熔断降级：对非核心服务配置熔断，保障核心服务可用。

文档版本：v1.0.0 | 适用 Ocelot 版本：18.0.0 | 适用 .NET 版本：.NET 6/8