OData là giao thức cho phép client tự tạo truy vấn trên API: chọn cột, lọc, sắp xếp, mở rộng quan hệ, phân trang — tất cả qua query string. Nghe rất hấp dẫn cho dashboard và tích hợp dữ liệu. Nhưng OData cũng là cách nhanh nhất để biến database của bạn thành một endpoint có thể bị quét cạn bởi một query string do người khác viết.
Bài này cập nhật phần OData trong lộ trình .NET 2026: cách dựng đúng với Microsoft.AspNetCore.OData 9.5 trên .NET 10, cách nó dịch sang EF Core 10, và những giới hạn bắt buộc phải đặt trước khi cho client truy vấn tự do.
Mục lục
Cập nhật 2026: OData vẫn sống, nhưng cách dùng đã khác
- Microsoft.AspNetCore.OData 9.5 hỗ trợ .NET 8/10; đây là package chính thức duy nhất cho ASP.NET Core. OData .NET 8/9 đã cũ, đừng trộn.
- OData v4 là chuẩn hiện hành, dùng JSON theo OData JSON Format và metadata EDMX qua
$metadata. Đừng nhầm với OData v3 (Atom/XML) trong các bài viết cũ. - Tích hợp EF Core 10 qua
IQueryable:$filter,$orderby,$select,$expandđược dịch thành LINQ rồi SQL. Điều này mạnh, nhưng cũng có nghĩa là client ảnh hưởng trực tiếp đến query plan.
OData giải quyết bài toán gì?
Với REST thông thường, mỗi nhu cầu lọc/sắp xếp cần một endpoint hoặc một tập query parameter tự định nghĩa. OData chuẩn hóa việc đó: client dùng cùng cú pháp trên mọi entity, server công bố metadata để client biết entity nào có field nào.
Ví dụ, một client BI có thể tự lấy dữ liệu mà không cần team backend thêm endpoint:
GET /odata/Orders?$filter=status eq 'Paid' and total gt 100
&$select=id,code,total,createdAt
&$expand=customer($select=id,name)
&$orderby=createdAt desc
&$top=50
Điều này hữu ích khi:
- Có nhiều client phân tích dữ liệu (Power BI, Excel, Tableau) cần tự do truy vấn.
- API nội bộ phục vụ nhiều team với nhu cầu cắt dữ liệu khác nhau.
- Bạn muốn chuẩn hóa phân trang/lọc thay vì mỗi team tự viết một kiểu.
Nó thường là lựa chọn sai khi:
- API công khai cho mobile/web với hợp đồng cố định — REST + OpenAPI dễ kiểm soát hơn.
- Dữ liệu nhạy cảm hoặc multi-tenant phức tạp, nơi mỗi field cần quy tắc phân quyền riêng.
- Team không có người hiểu OData và không có kế hoạch giới hạn truy vấn.
Dựng OData với ASP.NET Core 10
dotnet add package Microsoft.AspNetCore.OData --version 9.5.0
// File: Program.cs
using Microsoft.AspNetCore.OData;
using Microsoft.OData.ModelBuilder;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var modelBuilder = new ODataConventionModelBuilder();
modelBuilder.EntitySet<Order>("Orders");
modelBuilder.EntitySet<Customer>("Customers");
builder.Services.AddOData(options => options
.AddRouteComponents("odata", modelBuilder.GetEdmModel())
.Select()
.Filter()
.OrderBy()
.Expand()
.Count()
.SetMaxTop(100));
var app = builder.Build();
app.MapControllers();
app.Run();
Controller dùng [EnableQuery] và trả IQueryable:
// File: Controllers/OrdersController.cs
using Microsoft.AspNetCore.OData.Query;
using Microsoft.AspNetCore.OData.Routing.Controllers;
[Route("odata/Orders")]
public sealed class OrdersController : ODataController
{
private readonly AppDbContext _db;
public OrdersController(AppDbContext db) => _db = db;
[HttpGet]
[EnableQuery(MaxTop = 100, PageSize = 50, MaxExpansionDepth = 2)]
public IQueryable<Order> Get()
=> _db.Orders.AsNoTracking();
}
Điểm quan trọng: trả IQueryable, không trả List. Nếu materialize trước khi OData áp query option, toàn bộ bảng được load rồi mới lọc trong bộ nhớ — vừa chậm vừa dễ OOM. AsNoTracking() là mặc định đúng cho endpoint chỉ đọc.
Các query option cần biết
| Option | Chức năng | Lưu ý |
|---|---|---|
$filter |
Lọc theo biểu thức | Có thể dịch thành SQL; cảnh giác với cột không index |
$select |
Chọn field | Giảm payload; vẫn cần kiểm soát field nhạy cảm |
$expand |
Mở rộng navigation | Nguồn gốc của N+1/cuồng bùng nổ dữ liệu |
$orderby |
Sắp xếp | Thiếu index sẽ sort toàn bộ |
$top/$skip |
Phân trang offset | Luôn đặt MaxTop |
$count |
Trả tổng số bản ghi | Tốn query đếm; hạn chế ở bảng lớn |
$search |
Tìm kiếm full-text | Phải bật riêng; không thay thế search engine |
$apply |
Aggregate/group | Rất đắt trên bảng lớn; bật có chọn lọc |
Chỉ bật những option bạn thực sự cần. Mặc định của AddOData không bật tất cả; mỗi lần gọi .Filter(), .Expand(), .Count() là một quyết định về bề mặt tấn công.
Bảo mật và hiệu năng: những giới hạn bắt buộc
OData không tự bảo vệ bạn. Một client có thể gửi $expand=Customer/Orders/Customer/Orders... hoặc $filter trên cột không index để ép database quét toàn bộ. Các biện pháp tối thiểu:
MaxTopvàPageSize: chặn client lấy toàn bộ bảng.MaxToplà giới hạn cứng;PageSizelà kích thước trang mặc định.MaxExpansionDepth: giới hạn độ sâu$expand, thường 1–2. Không có nó, một query có thể join nhiều tầng và trả về payload khổng lồ.- Index theo nhu cầu thực tế: xem query plan của các
$filter/$orderbyphổ biến. OData không tạo index. - Whitelist field: không expose navigation property hoặc cột nội bộ. Với EF Core, dùng DTO hoặc
Selectđể giới hạn. - Phân quyền theo entity và field:
[EnableQuery]không kiểm tra quyền. Bạn cần lọcIQueryabletheo tenant/user trước khi trả về, và kiểm tra từng navigation nếu nó nhạy cảm. - Tắt
$batchnếu không dùng: batch làm tăng bề mặt và khó rate limit theo request. - Rate limit và timeout: OData query có thể chạy lâu; đặt timeout và giới hạn cost ở tầng middleware.
Với multi-tenant, đừng tin tenantId trong query string. Lấy tenant từ token và áp vào IQueryable gốc; nếu không, $filter có thể đọc dữ liệu tenant khác.
OData và EF Core 10
OData dịch query option thành biểu thức LINQ trên IQueryable. Với EF Core 10, điều này có nghĩa là:
$filter→WHERE;$orderby→ORDER BY;$select→ projection;$expand→JOIN/Includetùy cấu hình.$countphát sinh queryCOUNT(*)riêng; trên bảng lớn, đây là chi phí thật.- Navigation property ảo (không map) sẽ không dịch được; kiểm tra log SQL thay vì giả định.
- Nếu dùng
AsSplitQuery, kết quả$expandcó thể khác thứ tự; cần test.
Một lựa chọn an toàn hơn là expose DTO thay vì entity. Bạn vẫn có OData nhưng kiểm soát được field nào tồn tại trong EDM, tránh lộ cột nội bộ và giảm rủi ro thay đổi schema DB phá client.
OData so với REST và GraphQL
| Tiêu chí | REST | OData | GraphQL |
|---|---|---|---|
| Client tự truy vấn | Hạn chế, tự định nghĩa | Có, chuẩn hóa | Có, linh hoạt nhất |
| Hợp đồng | OpenAPI | EDM/$metadata | Schema GraphQL |
| Cache HTTP | Tốt | Tốt (GET + URL) | Kém hơn |
| Kiểm soát tải | Do bạn thiết kế | Cần MaxTop/MaxExpansionDepth | Cần cost analysis |
| Độ phức tạp | Thấp | Trung bình | Cao |
Nếu client chính là Power BI/Excel hoặc hệ thống cần chuẩn dữ liệu mở, OData là lựa chọn tốt. Nếu client là app mobile với 5 màn hình cố định, REST + OpenAPI đơn giản hơn và ít rủi ro hơn. GraphQL nằm giữa: linh hoạt hơn OData nhưng cần đầu tư vận hành cao hơn.
OData trong thực tế: Power BI, Excel và tích hợp dữ liệu
Đây là kịch bản OData thực sự tỏa sáng. Power BI và Excel có connector OData native: người dùng chỉ cần nhập URL https://api.example.com/odata, chọn entity, kéo field và tự xây báo cáo. Không cần team backend thêm endpoint cho từng biểu đồ.
Nhưng để kịch bản này không phản tác dụng:
- Công bố
$metadataổn định, có mô tả field. Client dựa vào đó để build query; đổi tên field làm báo cáo gãy. - Expose entity read-only cho báo cáo, tách khỏi endpoint ghi. Đừng cho Power BI quyền
POST/PATCH. - Dữ liệu lớn nên có view/materialized table phía sau, không join trực tiếp trên bảng giao dịch nóng.
- Đặt giới hạn theo tenant và theo user; báo cáo “xem tất cả” thường là yêu cầu hợp lý nhưng phải kiểm soát quyền.
Với Excel, OData giúp người dùng tải dữ liệu trực tiếp mà không cần export CSV thủ công. Đổi lại, bạn phải chịu được các query lặp lại, không tối ưu, chạy đúng giờ — hãy chuẩn bị cache hoặc read replica cho các endpoint này.
Những lỗi OData hay gặp
$expandkhông giới hạn: client mở rộng nhiều tầng, payload phình to, DB join nặng. ĐặtMaxExpansionDepthvà test bằng query sâu.$filtertrên cột không index: query chạy full scan. Xem execution plan, thêm index hoặc từ chối field đó trong EDM.$counttrên bảng lớn: mỗi lần lấy trang đều đếm toàn bộ. Cân nhắc bỏ$counthoặc dùng ước lượng.- Trả
Listthay vìIQueryable: OData không đẩy được điều kiện xuống SQL; toàn bộ bảng được load. - Quên
AsNoTracking: change tracker giữ mọi entity, tăng RAM và chậm. - Dùng OData cho API public: bề mặt tấn công lớn, khó versioning, client khó hiểu hơn REST thường.
Nên expose entity hay DTO?
Entity EF Core có navigation property, cột audit, khóa ngoại và vòng tham chiếu. Expose thẳng entity qua OData nghĩa là client có thể $expand vào những quan hệ bạn không muốn công khai, và schema EDM thay đổi mỗi khi schema DB đổi. DTO là hợp đồng ổn định hơn.
[HttpGet]
[EnableQuery(MaxTop = 100, MaxExpansionDepth = 2)]
public IQueryable<OrderDto> Get([FromServices] AppDbContext db)
=> db.Orders
.AsNoTracking()
.Select(o => new OrderDto
{
Id = o.Id,
Code = o.Code,
Status = o.Status,
Total = o.Total,
CustomerName = o.Customer.Name
});
Lưu ý: Select vẫn trả IQueryable, nên OData vẫn đẩy được $filter/$orderby xuống SQL — miễn là biểu thức map được. Nhưng $expand chỉ hoạt động trên navigation property có trong EDM; nếu DTO làm phẳng quan hệ, client mất khả năng expand. Đây là đánh đổi có chủ đích: hợp đồng rõ ràng và an toàn hơn, nhưng kém linh hoạt hơn.
Với hệ thống nội bộ, nơi client tin cậy và cần truy vấn sâu, expose entity có thể chấp nhận được nếu bạn kiểm soát quyền và index. Với API ra ngoài, DTO là mặc định.
Checklist trước khi bật OData
- Chỉ bật các query option cần thiết; mặc định tắt phần còn lại.
MaxTop,PageSize,MaxExpansionDepthđược đặt và có test.- Entity/DTO được whitelist; không expose cột nội bộ hay navigation nhạy cảm.
- Tenant/user filter nằm trong
IQueryablegốc, không đến từ query string. - Đã đo query plan cho các
$filter/$orderbyphổ biến và thêm index cần thiết. - Rate limit, timeout và log query chậm đều bật.
- Có test cho query độc hại: expand sâu, filter trên cột không index, top lớn.
Bài liên quan: RESTful API best practices để so sánh hợp đồng; GraphQL với HotChocolate nếu cần client chọn field linh hoạt hơn; các chiến lược loading trong EF Core để hiểu chi phí của $expand.



