Khám Phá GraphQL trong ASP.NET Core với HotChocolate: Truy Vấn API Mạnh Mẽ Hơn trong Lộ Trình .NET

GraphQL không phải “REST nhưng tốt hơn”. Nó là một hợp đồng khác: client khai báo chính xác dữ liệu mình cần, server chịu trách nhiệm resolve từng field. Điều đó giải quyết over-fetching và under-fetching rất tốt — nhưng cũng chuyển toàn bộ bài toán N+1, phân quyền theo field và giới hạn tải từ client sang server. Nếu không xử lý ba việc đó, GraphQL sẽ chậm và nguy hiểm hơn REST.

Bài này cập nhật phần GraphQL trong lộ trình .NET cho năm 2026: HotChocolate 16, tích hợp EF Core 10, DataLoader, projections, phân quyền và các biện pháp chống truy vấn phá hoại. Mục tiêu là để bạn quyết định có nên dùng GraphQL hay không, và nếu dùng thì dựng đúng ngay từ đầu.

Cập nhật 2026: GraphQL trong .NET đã chín

  • HotChocolate 16.7.3 là lựa chọn chính cho ASP.NET Core; GraphQL.NET 8.3 vẫn tồn tại nhưng ít tính năng tự động hơn. Chọn HotChocolate nếu bạn muốn schema-first/code-first linh hoạt, filtering/sorting/projection có sẵn.
  • Tích hợp EF Core 10 qua HotChocolate.Data: projection, filtering, sorting chuyển thành LINQ, giảm việc viết resolver thủ công.
  • Persisted operations và cost analysis trở thành yêu cầu vận hành, không còn là “nice to have”: client gửi hash thay vì toàn bộ query, server giới hạn độ sâu/độ phức tạp trước khi thực thi.

Khi nào GraphQL thực sự đáng dùng?

GraphQL hợp lý khi:

  • Có nhiều client (web, mobile, đối tác) cần các tập field khác nhau trên cùng một domain.
  • Màn hình cần dữ liệu từ nhiều entity liên quan và bạn muốn giảm số round-trip.
  • Team frontend muốn tự tiến hóa query mà không chờ backend thêm endpoint.

GraphQL thường là lựa chọn sai khi:

  • API chỉ có một client, hình dạng dữ liệu cố định — REST đơn giản hơn và dễ cache hơn.
  • Team chưa có người chịu trách nhiệm schema, authorization và performance.
  • Dữ liệu chủ yếu là file/blob, upload/download — GraphQL không giải quyết tốt.
  • Bạn cần HTTP caching theo URL: GraphQL dùng một endpoint POST, cache CDN mất tác dụng trừ khi dùng persisted query + GET.

Schema, resolver và hợp đồng

GraphQL có ba loại operation: query (đọc), mutation (thay đổi), subscription (stream). Schema định nghĩa type và field; resolver là hàm trả về dữ liệu cho từng field. Điểm khác biệt cốt lõi: client chọn field, nên server không thể giả định “một request = một query cố định”.

type Order {
  id: ID!
  code: String!
  status: OrderStatus!
  total: Decimal!
  customer: Customer!
  items: [OrderItem!]!
}

type Query {
  order(id: ID!): Order
  orders(first: Int, after: String, status: OrderStatus): OrderConnection!
}

Hai chi tiết thiết kế dễ bỏ qua:

  • Nullable có chủ đích. Dấu ! không chỉ là “không null” — nó là cam kết. Nếu một field non-null lỗi, GraphQL có thể null toàn bộ object cha. Đừng đánh dấu ! cho mọi thứ chỉ vì type C# là non-nullable.
  • Connection cho danh sách. Trả về mảng trần ([Order!]!) rất khó phân trang và khó mở rộng. Dùng connection với edges/pageInfo (Relay-style) hoặc tối thiểu là items + nextCursor.

Dựng server với HotChocolate 16

// File: Program.cs
builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>()
    .AddMutationType<Mutation>()
    .AddProjections()
    .AddFiltering()
    .AddSorting()
    .AddAuthorization();

var app = builder.Build();
app.MapGraphQL("/graphql");

Query type dùng service injection và projection:

// File: GraphQL/Query.cs
public sealed class Query
{
    [UseProjection]
    [UseFiltering]
    [UseSorting]
    public IQueryable<Order> GetOrders([Service] AppDbContext db)
        => db.Orders.AsNoTracking();

    public async Task<Order?> GetOrderAsync(
        int id,
        [Service] OrderService service,
        CancellationToken ct)
        => await service.FindAsync(id, ct);
}

UseProjection là tính năng quan trọng nhất trong danh sách trên. Không có nó, server luôn load toàn bộ entity rồi mới lọc field ở tầng GraphQL — client xin 2 field nhưng DB đọc 20 cột. Với EF Core, projection dịch thành SELECT chỉ các cột cần thiết. Hãy kiểm tra SQL log để chắc chắn nó thực sự hoạt động, đừng tin cấu hình.

N+1 và DataLoader

Đây là lỗi GraphQL phổ biến nhất. Client query 50 order, mỗi order có customer. Nếu resolver Order.customer gọi DB một lần cho mỗi order, bạn có 51 query. Giải pháp là batch theo request:

// File: GraphQL/CustomerByIdDataLoader.cs
public sealed class CustomerByIdDataLoader : BatchDataLoader<int, Customer>
{
    private readonly AppDbContext _db;

    public CustomerByIdDataLoader(AppDbContext db, IBatchScheduler scheduler)
        : base(scheduler, new DataLoaderOptions { MaxBatchSize = 100 })
        => _db = db;

    protected override async Task<IReadOnlyDictionary<int, Customer>> LoadBatchAsync(
        IReadOnlyList<int> keys, CancellationToken ct)
    {
        var customers = await _db.Customers
            .Where(c => keys.Contains(c.Id))
            .AsNoTracking()
            .ToListAsync(ct);

        return customers.ToDictionary(c => c.Id);
    }
}

Resolver Order.customer dùng [Service] CustomerByIdDataLoader loader và await loader.LoadAsync(order.CustomerId, ct). DataLoader gom các key trong cùng một tick của request, nên 50 order tạo 1 query thay vì 50. Đây không phải cache toàn cục — nó chỉ batch trong phạm vi request, đúng với yêu cầu về tính nhất quán.

Với quan hệ nhiều-nhiều hoặc cần lọc theo parent, dùng GroupDataLoader hoặc BatchDataLoader với key là parent ID. Đừng dùng DataLoader để che giấu một resolver đang gọi API bên ngoài chậm; batch không làm cho external call nhanh hơn.

Phân quyền theo field

Trong REST, bạn bảo vệ endpoint. Trong GraphQL, client có thể chọn bất kỳ field nào trong schema, nên phân quyền phải ở cấp field hoặc cấp type:

public sealed class Order
{
    public int Id { get; init; }

    [Authorize("orders:read")]
    public decimal Total { get; init; }

    [Authorize("customers:read")]
    public Customer Customer { get; init; }
}

Ba lưu ý:

  • Không dựa vào việc client “không hỏi field nhạy cảm”. Kẻ tấn công luôn có thể hỏi.
  • Kiểm tra quyền sở hữu dữ liệu (tenant/user) trong resolver hoặc DataLoader, không chỉ role.
  • Ẩn field khỏi schema theo vai trò có thể hữu ích, nhưng làm schema khó đoán và khó cache; thường chỉ nên ẩn ở mức introspection, còn enforcement vẫn ở resolver.

Chống truy vấn phá hoại

GraphQL cho client quyền mô tả query, nên cần giới hạn tài nguyên:

  • Độ sâu tối đa và độ phức tạp tối đa: từ chối query lồng quá sâu hoặc có cost vượt ngưỡng trước khi execute. HotChocolate hỗ trợ cost analysis; hãy bật và đo cost thực tế của các query phổ biến.
  • Persisted operations: client gửi hash của query đã đăng ký; server từ chối query tùy ý. Điều này giảm bề mặt tấn công, giảm payload và cho phép cache theo hash.
  • Giới hạn danh sách: first tối đa 100, bắt buộc có cursor khi vượt ngưỡng; không trả toàn bộ bảng.
  • Timeout và cancellation: CancellationToken xuyên suốt; đặt execution timeout để query xấu không chiếm worker.
  • Tắt introspection ở production nếu không cần; đây là biện pháp giảm thông tin, không phải bảo mật thay thế authorization.

GraphQL trong pipeline HTTP

GraphQL thường dùng một endpoint POST /graphql. Vì vậy:

  • HTTP caching theo URL không hoạt động. Nếu cần CDN cache, dùng persisted query + GET /graphql?operationName=...&variables=... với Cache-Control phù hợp.
  • Rate limiting nên đặt ở tầng operation/cost, không chỉ theo số request — một request có thể chứa nhiều query hoặc query rất đắt.
  • Log cần ghi operation name, hash, cost, thời gian resolve theo field. Log access theo URL là vô nghĩa.
  • Lỗi GraphQL trả về HTTP 200 kèm errors[] theo spec. Đừng dùng status code để suy ra thành công/thất bại; hãy parse errors và đặt correlation ID trong extensions.

Schema-first hay code-first?

HotChocolate hỗ trợ cả hai. Code-first (dùng class C# và attribute) nhanh để bắt đầu và dễ tái sử dụng type nội bộ, nhưng schema là hệ quả của code — đổi class có thể vô tình đổi hợp đồng công khai. Schema-first (viết .graphql rồi bind resolver) đặt hợp đồng lên trước, phù hợp khi có nhiều team hoặc client bên ngoài, nhưng phải viết binding thủ công nhiều hơn.

Lời khuyên thực dụng: bắt đầu code-first cho sản phẩm nội bộ, nhưng trích schema ra file .graphql và review như API contract. Khi schema đã có client bên ngoài, chuyển sang schema-first hoặc ít nhất khóa schema bằng snapshot test trong CI — bất kỳ thay đổi breaking nào phải làm test fail trước khi merge.

Subscription: chỉ dùng khi thực sự cần

Subscription giữ một kết nối dài (thường WebSocket) và đẩy dữ liệu khi có sự kiện. Nó hữu ích cho thông báo, trạng thái đơn hàng, dashboard thời gian thực. Nó không hữu ích để thay thế polling đơn giản, và cũng không giải quyết bài toán scale-out: bạn vẫn cần một message bus (Redis pub/sub, Kafka, RabbitMQ) để phân phối sự kiện giữa các instance.

Nếu đã có SignalR trong hệ thống, đừng thêm GraphQL subscription chỉ vì “đủ bộ”. Hai cơ chế real-time cùng lúc thường tạo hai đường ống, hai cách xác thực và hai bộ metric — trả giá vận hành gấp đôi mà không thêm giá trị.

Lỗi và observability

GraphQL trả HTTP 200 kèm mảng errors, nên monitoring theo status code sẽ báo “thành công” cho một query thất bại toàn bộ. Hãy log và đo theo operation:

  • Tên operation, hash (nếu dùng persisted query), thời gian thực thi, cost.
  • Số field resolve, số query DB phát sinh (để bắt N+1), số lỗi theo path.
  • Correlation ID trong extensions của mỗi error để nối với log server.

Với lỗi nghiệp vụ (không tìm thấy, không có quyền), dùng error code ổn định trong extensions.code thay vì message tiếng Việt/tiếng Anh — client không nên parse message. Với lỗi hệ thống, trả message chung và log chi tiết ở server; đừng đưa stack trace vào GraphQL response.

So sánh nhanh: GraphQL, REST, OData, gRPC

Tiêu chí REST GraphQL OData gRPC
Client chọn field Không (trừ sparse fieldsets) Có Có ($select) Không (theo proto)
Hợp đồng OpenAPI Schema GraphQL EDM/metadata .proto
Cache HTTP Tốt Kém hơn (persisted query) Tốt Không
Hiệu năng nội bộ Trung bình Trung bình Trung bình Cao (binary/HTTP2)
Độ phức tạp vận hành Thấp Cao Trung bình Trung bình-cao

Đừng chọn GraphQL chỉ vì “nghe hiện đại”. Nếu team chưa có người sở hữu schema và cost control, REST với OpenAPI 3.1 sẽ ổn định hơn. Nếu bạn có nhiều client và domain giàu quan hệ, GraphQL là khoản đầu tư hợp lý — miễn là bạn xử lý N+1 và authorization ngay từ ngày đầu.

Checklist triển khai

  • Schema có naming nhất quán, nullable có chủ đích, list dùng connection.
  • Projection/filtering/sorting bật cho các field đọc từ EF Core; kiểm tra SQL thực tế.
  • Mọi quan hệ one-to-many/many-to-one dùng DataLoader, không resolver gọi DB trong vòng lặp.
  • Authorization ở cấp field + kiểm tra tenant trong resolver.
  • Cost analysis, độ sâu tối đa, persisted operations, timeout đều bật.
  • Log theo operation name/hash; dashboard có p95 latency theo field nóng.
  • Có test cho query đắt nhất và query độc hại nhất.

Bài liên quan trong series: RESTful API best practices để so sánh hợp đồng và status code; OData nếu bạn cần truy vấn linh hoạt nhưng muốn giữ mô hình HTTP; gRPC nếu client là service nội bộ và cần hiệu năng/contract chặt. Và đừng quên bài N+1 trong EF Core — GraphQL chỉ phóng đại vấn đề, không tạo ra nó.