GraphQL Federation — Xây dựng API Gateway thống nhất cho Microservices

Posted on: 4/25/2026 6:12:31 AM

Khi hệ thống microservices phát triển đến hàng chục, hàng trăm service — câu hỏi lớn nhất không còn là "dùng REST hay gRPC?" mà là: làm sao để frontend chỉ gọi một endpoint duy nhất mà vẫn truy cập được data từ tất cả services? REST API Gateway giải quyết được routing, nhưng không giải quyết được bài toán data composition — khi một trang cần dữ liệu từ 5-10 services khác nhau, frontend phải gọi nhiều API rồi tự ghép. GraphQL Federation sinh ra để giải quyết đúng vấn đề này: mỗi team sở hữu một subgraph, và router tự động compose thành một unified API duy nhất. Bài viết này phân tích sâu kiến trúc, triển khai trên .NET với HotChocolate, và các bài học production thực tế.

1. Vấn đề — Khi REST API Gateway không đủ

Hãy tưởng tượng một trang product detail trên e-commerce: cần thông tin sản phẩm (Product Service), giá và tồn kho (Inventory Service), đánh giá (Review Service), gợi ý sản phẩm (Recommendation Service), và thông tin người bán (Seller Service). Với REST, frontend phải:

sequenceDiagram
    participant FE as Frontend
    participant GW as API Gateway
    participant PS as Product Service
    participant IS as Inventory Service
    participant RS as Review Service
    participant RC as Recommendation
    participant SS as Seller Service
    FE->>GW: GET /products/123
    GW->>PS: GET /products/123
    PS-->>GW: Product data
    GW-->>FE: Product data
    FE->>GW: GET /inventory/product/123
    GW->>IS: GET /inventory/product/123
    IS-->>GW: Stock info
    GW-->>FE: Stock info
    FE->>GW: GET /reviews?productId=123
    GW->>RS: GET /reviews?productId=123
    RS-->>GW: Reviews
    GW-->>FE: Reviews
    FE->>GW: GET /recommendations/123
    GW->>RC: GET /recommendations/123
    RC-->>GW: Suggestions
    GW-->>FE: Suggestions
    FE->>GW: GET /sellers/456
    GW->>SS: GET /sellers/456
    SS-->>GW: Seller info
    GW-->>FE: Seller info

5 round-trips tu frontend den gateway, moi request phai doi request truoc hoan thanh (waterfall). Voi GraphQL Federation:

sequenceDiagram
    participant FE as Frontend
    participant RT as GraphQL Router
    participant PS as Product Subgraph
    participant IS as Inventory Subgraph
    participant RS as Review Subgraph
    participant RC as Recommendation Subgraph
    participant SS as Seller Subgraph
    FE->>RT: query { product(id:123) { name, price, stock, reviews { ... }, recommendations { ... }, seller { ... } } }
    RT->>PS: Resolve product
    RT->>IS: Resolve stock
    RT->>RS: Resolve reviews
    RT->>RC: Resolve recommendations
    PS-->>RT: Product data
    IS-->>RT: Stock info
    RS-->>RT: Reviews
    RC-->>RT: Suggestions
    RT->>SS: Resolve seller (from product.sellerId)
    SS-->>RT: Seller info
    RT-->>FE: Unified response

2. Cac khai niem cot loi

GraphQL Federation xoay quanh 3 thanh phan chinh:

graph TB
    subgraph "Team A: Product"
        SG1["Product Subgraph
type Product @key(fields: id)"]
    end
    subgraph "Team B: Inventory"
        SG2["Inventory Subgraph
extend type Product
  stock: Int"]
    end
    subgraph "Team C: Reviews"
        SG3["Review Subgraph
extend type Product
  reviews: [Review]"]
    end
    subgraph "Supergraph"
        ROUTER["GraphQL Router
(Apollo Router / Cosmo / HotChocolate Fusion)"]
    end
    SG1 --> ROUTER
    SG2 --> ROUTER
    SG3 --> ROUTER
    CLIENT["Frontend Client"] --> ROUTER
    style ROUTER fill:#e94560,stroke:#fff,color:#fff
    style SG1 fill:#4CAF50,stroke:#fff,color:#fff
    style SG2 fill:#2196F3,stroke:#fff,color:#fff
    style SG3 fill:#ff9800,stroke:#fff,color:#fff
    style CLIENT fill:#2c3e50,stroke:#fff,color:#fff

3. Federation v2 — Nhung cai tien quan trong

Federation v2 (phien ban hien tai: v2.11) mang den nhieu cai tien so voi v1:

# Product Subgraph — Team Product so huu
# schema.graphql

extend schema @link(
  url: "https://specs.apollo.dev/federation/v2.11"
  import: ["@key", "@shareable", "@override"]
)

type Product @key(fields: "id") {
  id: ID!
  name: String!
  description: String
  price: Float!
  weight: Float
  sellerId: ID!
  seller: Seller
  createdAt: DateTime!
}

type Query {
  product(id: ID!): Product
  products(first: Int = 10, after: String): ProductConnection!
}

# Inventory Subgraph — Team Inventory so huu
# schema.graphql

extend schema @link(
  url: "https://specs.apollo.dev/federation/v2.11"
  import: ["@key", "@external", "@requires"]
)

type Product @key(fields: "id") {
  id: ID!
  stock: Int!
  warehouse: String!
  weight: Float @external
  shippingCost: Float @requires(fields: "weight")
}

# Review Subgraph — Team Review so huu
# schema.graphql

extend schema @link(
  url: "https://specs.apollo.dev/federation/v2.11"
  import: ["@key"]
)

type Product @key(fields: "id") {
  id: ID!
  reviews: [Review!]!
  averageRating: Float
  reviewCount: Int!
}

type Review {
  id: ID!
  author: User!
  rating: Int!
  comment: String
  createdAt: DateTime!
}

4. Chon Router — Apollo vs Cosmo vs HotChocolate

Router la thanh phan quan trong nhat trong Federation. Lua chon phu hop anh huong truc tiep den hieu nang va developer experience:

5. Trien khai tren .NET voi HotChocolate

Voi team .NET, HotChocolate v14 la lua chon production-grade duy nhat. Ho tro ca Apollo Federation v2 spec va he sinh thai Fusion rieng cua ChilliCream:

5.1. Tao Product Subgraph

// ProductSubgraph/Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddGraphQLServer()
    .AddApolloFederation() // Enable Federation v2
    .AddQueryType<ProductQuery>()
    .AddType<ProductType>()
    .AddFiltering()
    .AddSorting()
    .RegisterDbContext<ProductDbContext>();

var app = builder.Build();
app.MapGraphQL();
app.Run();

// ProductSubgraph/Types/ProductType.cs
[Key("id")] // Federation @key directive
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = default!;
    public string? Description { get; set; }
    public decimal Price { get; set; }
    public float? Weight { get; set; }
    public int SellerId { get; set; }
    public DateTime CreatedAt { get; set; }
}

public class ProductQuery
{
    [UseDbContext(typeof(ProductDbContext))]
    [UseFiltering]
    [UseSorting]
    public IQueryable<Product> GetProducts(
        [ScopedService] ProductDbContext context)
        => context.Products;

    public async Task<Product?> GetProductById(
        int id,
        ProductByIdDataLoader loader)
        => await loader.LoadAsync(id);
}

// DataLoader — batch N+1 queries
public class ProductByIdDataLoader : BatchDataLoader<int, Product>
{
    private readonly IDbContextFactory<ProductDbContext> _factory;

    public ProductByIdDataLoader(
        IDbContextFactory<ProductDbContext> factory,
        IBatchScheduler scheduler)
        : base(scheduler)
    {
        _factory = factory;
    }

    protected override async Task<IReadOnlyDictionary<int, Product>>
        LoadBatchAsync(IReadOnlyList<int> keys, CancellationToken ct)
    {
        await using var ctx = await _factory.CreateDbContextAsync(ct);
        return await ctx.Products
            .Where(p => keys.Contains(p.Id))
            .ToDictionaryAsync(p => p.Id, ct);
    }
}

5.2. Inventory Subgraph — extend Product

// InventorySubgraph/Types/ProductExtension.cs

[ExtendServiceType] // Extend type tu subgraph khac
public class ProductExtension
{
    [Key("id")]
    public int Id { get; set; }

    public async Task<int> GetStock(
        [Parent] Product product,
        InventoryService service)
        => await service.GetStockAsync(product.Id);

    public async Task<string> GetWarehouse(
        [Parent] Product product,
        InventoryService service)
        => await service.GetWarehouseAsync(product.Id);

    [Requires("weight")]
    public decimal GetShippingCost(
        [Parent] Product product)
        => product.Weight.HasValue
            ? product.Weight.Value * 2.5m + 5.0m
            : 10.0m;
}

5.3. Gateway voi HotChocolate Fusion

// Gateway/Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddGraphQLServer()
    .AddApolloFederationGateway()
    .AddServiceEndpoint(
        "products", new Uri("http://product-service/graphql"))
    .AddServiceEndpoint(
        "inventory", new Uri("http://inventory-service/graphql"))
    .AddServiceEndpoint(
        "reviews", new Uri("http://review-service/graphql"))
    .AddServiceEndpoint(
        "sellers", new Uri("http://seller-service/graphql"));

var app = builder.Build();
app.MapGraphQL();
app.Run();

6. Hieu nang — Federation co cham hon REST?

Mot lo ngai pho bien: "them 1 lop Router co lam cham khong?" Cau tra loi ngan: latency tang nhe o Router, nhung tong thoi gian end-to-end thuong giam nho parallel fan-out va loai bo waterfall tu frontend.

graph LR
    subgraph "REST Pattern"
        R1["Call 1: 90ms"] --> R2["Call 2: 85ms"]
        R2 --> R3["Call 3: 95ms"]
        R3 --> R4["Call 4: 80ms"]
        R4 --> R5["Call 5: 100ms"]
    end
    subgraph "Federation Pattern"
        Q["Query: 5ms planning"]
        Q --> F1["Fan-out 1: 90ms"]
        Q --> F2["Fan-out 2: 85ms"]
        Q --> F3["Fan-out 3: 95ms"]
        Q --> F4["Fan-out 4: 80ms"]
        F1 --> M["Merge: 2ms"]
        F2 --> M
        F3 --> M
        F4 --> M
        M --> F5["Fan-out 5: 100ms"]
        F5 --> M2["Final: 2ms"]
    end
    style Q fill:#e94560,stroke:#fff,color:#fff
    style M fill:#4CAF50,stroke:#fff,color:#fff
    style M2 fill:#4CAF50,stroke:#fff,color:#fff

7. Caching — Thach thuc lon nhat cua GraphQL

Diem yeu noi tieng cua GraphQL: CDN caching kho. REST dung GET + Cache-Control header rat de cache. GraphQL dung POST, moi query la body khac nhau.

// Apollo Router — cau hinh Entity Caching voi Redis
// router.yaml

supergraph:
  introspection: false

preview_entity_cache:
  enabled: true
  redis:
    urls: ["redis://cache-redis:6379"]
    ttl: 300s
  subgraph:
    products:
      enabled: true
      ttl: 600s
    inventory:
      enabled: true
      ttl: 30s  # stock thay doi thuong xuyen
    reviews:
      enabled: true
      ttl: 300s

8. Apollo Connectors — Tich hop REST vao Federation

Mot tinh nang dot pha cua Apollo Router v2: Connectors cho phep bien REST API thanh subgraph ma khong can viet code. Chi can khai bao trong schema:

# Bien REST endpoint thanh GraphQL subgraph
# Khong can server rieng — Router tu goi REST API

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.11", import: ["@key"])
  @link(url: "https://specs.apollo.dev/connect/v0.4", import: ["@source", "@connect"])
  @source(name: "legacy", http: { baseURL: "https://api.legacy.com/v1" })

type Product @key(fields: "id") {
  id: ID!
  name: String!
  legacyData: LegacyProductData
    @connect(
      source: "legacy"
      http: { GET: "/products/{$this.id}" }
      selection: """
        sku
        category: categoryName
        tags: labels
      """
    )
}

type LegacyProductData {
  sku: String
  category: String
  tags: [String]
}

9. Best Practices cho Production

9.1. Schema Design

# DO: Dinh nghia entity ro rang voi @key
type Product @key(fields: "id") {
  id: ID!
  name: String!
}

# DO: Dung @shareable cho computed fields
type Product @key(fields: "id") {
  id: ID!
  displayPrice: String @shareable # nhieu subgraph co the resolve
}

# DON'T: Khong tao "God subgraph" chua qua nhieu type
# Moi subgraph nen focus vao 1 bounded context (DDD)

9.2. Observability

# Apollo Router — OpenTelemetry config
# router.yaml

telemetry:
  instrumentation:
    spans:
      router:
        attributes:
          graphql.document: true
      subgraph:
        attributes:
          subgraph.name: true
          subgraph.graphql.document: true
  exporters:
    tracing:
      otlp:
        enabled: true
        endpoint: http://otel-collector:4317
        protocol: grpc

9.3. Error Handling

// HotChocolate — Error filter cho Federation
public class GraphQLErrorFilter : IErrorFilter
{
    public IError OnError(IError error)
    {
        return error.WithCode(error.Exception switch
        {
            NotFoundException => "NOT_FOUND",
            UnauthorizedException => "UNAUTHORIZED",
            ValidationException => "VALIDATION_ERROR",
            _ => "INTERNAL_ERROR"
        })
        .RemoveExtension("stackTrace"); // khong leak stack trace
    }
}

10. Khi nao nen dung Federation?

11. So sanh tong quan cac approach

12. Ket luan

GraphQL Federation giai quyet bai toan ma REST API Gateway khong lam duoc: tu dong compose du lieu tu nhieu microservices thanh 1 response duy nhat, trong khi van giu cho moi team quyen tu chu voi subgraph rieng. Voi Apollo Router (Rust, 10x nhanh hon gateway cu), HotChocolate Fusion (tich hop sau voi .NET 10), va cac tinh nang nhu Connectors (tich hop REST khong can code), Federation da san sang cho production tai quy mo lon.

Tuy nhien, Federation khong phai cho moi du an. Neu he thong cua ban chi co 2-3 services va 1 frontend — REST + BFF don gian hon nhieu. Federation phat huy gia tri thuc su khi ban co 5+ services, nhieu team, va frontend can data tu nhieu nguon. Hay bat dau voi 1-2 subgraph, validate gia tri, roi mo rong dan — dung co migrate toan bo he thong cung luc.

Nguon tham khao

• Introduction to Apollo Federation — Apollo GraphQL Docs
• What's New in GraphOS Router v2.x — Apollo GraphQL Docs
• GraphQL Federation Gateways Performance Benchmark — The Guild
• Hot Chocolate vs graphql-dotnet in .NET 2026 — Coding Droplets
• GraphQL vs REST: 18 Claims Fact-Checked — WunderGraph
• GraphQL vs REST 2026: Performance Tested — Tech Insider
• GraphQL vs REST vs gRPC: 2026 Decision Framework — Fordel Studios
• Federating .NET GraphQL APIs with Fusion — Medium