API Gateway چیست و چرا به آن نیاز داریم؟

وقتی وارد دنیای معماری میکروسرویس (Microservices Architecture) می‌شوی، اولین چیزی که باهاش دست‌وپنجه نرم می‌کنی، مسئله‌ی ارتباط بین سرویس‌هاست. تصور کن ده‌ها سرویس مجزا داری که هر کدام روی پورت و آدرس جداگانه‌ای اجرا می‌شن. کلاینت‌ها (مرورگر، اپ موبایل و…) باید با کدوم سرویس صحبت کنن؟ اینجاست که API Gateway وارد ماجرا می‌شه.

API Gateway یک نقطه‌ی ورودی واحد (Single Entry Point) برای تمام درخواست‌های کلاینت‌هاست. به زبان ساده، یه دربان هوشمند که:

• درخواست‌ها را دریافت می‌کند
• آن‌ها را به سرویس مناسب هدایت (Route) می‌کند
• احراز هویت و اعتبارسنجی را مدیریت می‌کند
• Load Balancing انجام می‌دهد
• Rate Limiting اعمال می‌کند
• Caching را مدیریت می‌کند

Ocelot چیست؟ معرفی کامل این فریم‌ورک قدرتمند

Ocelot یک کتابخانه‌ی متن‌باز (Open Source) برای پیاده‌سازی API Gateway در اکوسیستم .NET و C# است. این ابزار توسط جامعه‌ی بزرگ دات‌نت توسعه یافته و به‌خاطر سادگی، انعطاف و قدرت بالایش، بین برنامه‌نویسان ایرانی و خارجی محبوبیت زیادی پیدا کرده.

مهم‌ترین ویژگی‌های Ocelot عبارتند از:

• Routing پیشرفته: هدایت درخواست‌ها بر اساس Path، Method، Header و…
• Authentication & Authorization: پشتیبانی از JWT، OAuth2 و IdentityServer
• Load Balancing: توزیع بار بین چند نمونه از یک سرویس
• Rate Limiting: محدود کردن تعداد درخواست‌ها برای جلوگیری از سوءاستفاده
• Caching: کش کردن پاسخ‌ها برای بهبود عملکرد
• Circuit Breaker: مدیریت خطاها با الگوی مدار شکن
• پشتیبانی از Consul و Service Discovery

پیش‌نیازها و محیط توسعه

قبل از اینکه شروع کنیم، مطمئن شو که موارد زیر را داری:

• .NET 6 یا .NET 8 (جدیدترین نسخه‌های LTS)
• Visual Studio 2022 یا VS Code
• آشنایی پایه با ASP.NET Core Web API
• آشنایی با مفهوم Microservices

آموزش گام به گام پیاده‌سازی API Gateway با Ocelot

گام اول: ساخت پروژه‌های میکروسرویس

فرض کن می‌خوایم یک سیستم ساده با دو میکروسرویس بسازیم:

• ProductService — مدیریت محصولات (پورت 5001)
• OrderService — مدیریت سفارشات (پورت 5002)
• ApiGateway — درگاه اصلی (پورت 5000)

با دستورات زیر سه پروژه جداگانه می‌سازیم:

dotnet new webapi -n ProductService

dotnet new webapi -n OrderService

dotnet new webapi -n ApiGateway

گام دوم: نصب Ocelot در پروژه ApiGateway

وارد پروژه‌ی ApiGateway شو و پکیج Ocelot را نصب کن:

cd ApiGateway

dotnet add package Ocelot

اگر می‌خوای از قابلیت‌های پیشرفته‌تر مثل Service Discovery با Consul استفاده کنی:

dotnet add package Ocelot.Provider.Consul

dotnet add package Ocelot.Cache.CacheManager

گام سوم: پیکربندی Ocelot — فایل ocelot.json

قلب تپنده‌ی Ocelot، فایل ocelot.json است. این فایل را در ریشه‌ی پروژه ApiGateway بساز:

{

“Routes”: [

{

“DownstreamPathTemplate”: “/api/products/{everything}”,

“DownstreamScheme”: “https”,

“DownstreamHostAndPorts”: [

{

“Host”: “localhost”,

“Port”: 5001

}

],

“UpstreamPathTemplate”: “/products/{everything}”,

“UpstreamHttpMethod”: [ “GET”, “POST”, “PUT”, “DELETE” ]

},

{

“DownstreamPathTemplate”: “/api/orders/{everything}”,

“DownstreamScheme”: “https”,

“DownstreamHostAndPorts”: [

{

“Host”: “localhost”,

“Port”: 5002

}

],

“UpstreamPathTemplate”: “/orders/{everything}”,

“UpstreamHttpMethod”: [ “GET”, “POST”, “PUT”, “DELETE” ]

}

],

“GlobalConfiguration”: {

“BaseUrl”: “https://localhost:5000”

}

}

درک ساختار این فایل بسیار مهم است:

• UpstreamPathTemplate: آدرسی که کلاینت می‌فرستد (مثلاً /products/1)
• DownstreamPathTemplate: آدرسی که Ocelot به سرویس واقعی می‌فرستد
• DownstreamHostAndPorts: آدرس و پورت سرویس مقصد
• UpstreamHttpMethod: متدهای HTTP مجاز

گام چهارم: پیکربندی Program.cs

حالا باید Ocelot را به برنامه معرفی کنیم. فایل Program.cs را به این شکل تنظیم کن:

using Ocelot.DependencyInjection;

using Ocelot.Middleware;

var builder = WebApplication.CreateBuilder(args);

// اضافه کردن فایل پیکربندی Ocelot

builder.Configuration.AddJsonFile(“ocelot.json”, optional: false, reloadOnChange: true);

// ثبت سرویس‌های Ocelot

builder.Services.AddOcelot(builder.Configuration);

var app = builder.Build();

// استفاده از Middleware ی Ocelot

await app.UseOcelot();

app.Run();

گام پنجم: پیاده‌سازی Load Balancing

یکی از قدرتمندترین ویژگی‌های Ocelot، Load Balancing داخلی آن است. فرض کن سرویس محصولات روی سه سرور اجرا می‌شه:

{

“DownstreamPathTemplate”: “/api/products/{everything}”,

“DownstreamScheme”: “https”,

“DownstreamHostAndPorts”: [

{ “Host”: “localhost”, “Port”: 5001 },

{ “Host”: “localhost”, “Port”: 5003 },

{ “Host”: “localhost”, “Port”: 5005 }

],

“LoadBalancerOptions”: {

“Type”: “RoundRobin”

},

“UpstreamPathTemplate”: “/products/{everything}”,

“UpstreamHttpMethod”: [ “GET”, “POST” ]

}

Ocelot از سه الگوریتم Load Balancing پشتیبانی می‌کند:

• RoundRobin: درخواست‌ها به‌ترتیب بین سرورها توزیع می‌شن
• LeastConnection: درخواست به سرور با کمترین اتصال فعال می‌ره
• NoLoadBalancer: بدون توزیع بار (پیش‌فرض)

گام ششم: پیاده‌سازی Rate Limiting

Rate Limiting از سوءاستفاده از API جلوگیری می‌کند. با Ocelot به‌راحتی تنظیم می‌شه:

{

“UpstreamPathTemplate”: “/products/{everything}”,

“RateLimitOptions”: {

“ClientWhitelist”: [],

“EnableRateLimiting”: true,

“Period”: “1s”,

“PeriodTimespan”: 1,

“Limit”: 10

}

}

این تنظیمات یعنی: هر کلاینت در هر ثانیه حداکثر 10 درخواست می‌تواند ارسال کند.

گام هفتم: احراز هویت با JWT

یکی از متداول‌ترین نیازها در پروژه‌های واقعی، احراز هویت با JWT در لایه Gateway است. ابتدا پکیج مورد نیاز را نصب کن:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

سپس در Program.cs احراز هویت را اضافه کن:

builder.Services.AddAuthentication(“Bearer”)

.AddJwtBearer(“Bearer”, options =>

{

options.Authority = “https://your-identity-server”;

options.TokenValidationParameters = new TokenValidationParameters

{

ValidateAudience = false

};

});

builder.Services.AddOcelot(builder.Configuration);

و در ocelot.json مشخص کن کدام Route نیاز به احراز هویت دارد:

{

“UpstreamPathTemplate”: “/orders/{everything}”,

“AuthenticationOptions”: {

“AuthenticationProviderKey”: “Bearer”,

“AllowedScopes”: []

}

}

گام هشتم: Caching در Ocelot

برای بهبود پرفورمنس، می‌تونی پاسخ‌ها را کش کنی. ابتدا پکیج را نصب کن:

dotnet add package Ocelot.Cache.CacheManager

و در Program.cs:

builder.Services.AddOcelot(builder.Configuration)

.AddCacheManager(x => x.WithDictionaryHandle());

و در ocelot.json:

{

“UpstreamPathTemplate”: “/products/{everything}”,

“FileCacheOptions”: {

“TtlSeconds”: 30,

“Region”: “products-region”

}

}

مقایسه Ocelot با سایر API Gateway ها

بازار ابزارهای API Gateway شلوغه. بیایید Ocelot را با رقبا مقایسه کنیم:

• Ocelot vs YARP: YARP (پروژه جدید مایکروسافت) عملکرد بهتری دارد اما Ocelot کانفیگ‌محورتر و ساده‌تر است.
• Ocelot vs Kong: Kong قدرتمندتر اما پیچیده‌تر و نیاز به زیرساخت جداگانه دارد.
• Ocelot vs AWS API Gateway: برای پروژه‌های Cloud-native AWS بهتر است، اما Ocelot Self-hosted و رایگان است.
• Ocelot vs Nginx: Nginx سطح پایین‌تر و در لایه Reverse Proxy کار می‌کند؛ Ocelot در لایه Application.

بهترین شیوه‌ها (Best Practices) در استفاده از Ocelot

• فایل ocelot.json را به چند فایل تقسیم کن: برای پروژه‌های بزرگ، Ocelot امکان استفاده از چند فایل پیکربندی را دارد.
• از Correlation ID استفاده کن: برای ردیابی درخواست‌ها در بین میکروسرویس‌ها.
• Logging را جدی بگیر: از Serilog یا NLog برای لاگ‌گیری دقیق استفاده کن.
• Health Check اضافه کن: وضعیت سرویس‌ها را مانیتور کن.
• از Circuit Breaker با Polly استفاده کن: برای مقاوم‌سازی در برابر خرابی سرویس‌ها.
• Timeout مناسب تنظیم کن: از انتظار بی‌پایان جلوگیری کن.

پیکربندی پیشرفته: Aggregation در Ocelot

یکی از ویژگی‌های جالب Ocelot، قابلیت Request Aggregation است؛ یعنی یک درخواست کلاینت را به چند سرویس می‌فرستد و جواب‌ها را ترکیب می‌کند:

{

“Aggregates”: [

{

“RouteKeys”: [ “ProductRoute”, “OrderRoute” ],

“UpstreamPathTemplate”: “/dashboard”

}

],

“Routes”: [

{

“UpstreamPathTemplate”: “/products”,

“Key”: “ProductRoute”,

…

},

{

“UpstreamPathTemplate”: “/orders”,

“Key”: “OrderRoute”,

…

}

]

}

استقرار (Deployment) در Docker

در دنیای واقعی، API Gateway را با Docker مستقر می‌کنیم. فایل Dockerfile برای پروژه ApiGateway:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base

WORKDIR /app

EXPOSE 5000

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build

WORKDIR /src

COPY [“ApiGateway.csproj”, “.”]

RUN dotnet restore

COPY . .

RUN dotnet build -c Release -o /app/build

FROM build AS publish

RUN dotnet publish -c Release -o /app/publish

FROM base AS final

WORKDIR /app

COPY --from=publish /app/publish .

ENTRYPOINT [“dotnet”, “ApiGateway.dll”]

رفع خطاهای رایج در Ocelot

• خطای 404 بعد از Route: مطمئن شو DownstreamPathTemplate با آدرس واقعی API مقصد مطابقت داشته باشد.
• خطای SSL: برای محیط توسعه، از http استفاده کن یا certificate validation را غیرفعال کن.
• خطای 401 Unauthorized: ترتیب میان‌افزارها در Program.cs را بررسی کن؛ Authentication باید قبل از UseOcelot باشد.
• مشکل Timeout: مقدار QoSOptions را در ocelot.json تنظیم کن.

جمع‌بندی

Ocelot یکی از بهترین انتخاب‌ها برای پیاده‌سازی API Gateway در اکوسیستم .NET است. با ترکیب سادگی پیکربندی، قابلیت‌های غنی مثل Rate Limiting، Load Balancing، Caching و JWT Authentication، و پشتیبانی قوی جامعه متن‌باز، این ابزار می‌تواند نیاز اکثر پروژه‌های میکروسرویس را برطرف کند.

برای پروژه‌های کوچک تا متوسط، Ocelot گزینه‌ی ایده‌آلی است. اگر پروژه‌ات در حال رشد سریع است و به عملکرد بالاتری نیاز داری، بررسی YARP (پروژه Microsoft) هم توصیه می‌شه.

سوالات متداول (FAQ)