Phân trang con trỏ trong ASP.NET Core với EF Core
App mobile có màn hình lịch sử đơn hàng, cuộn tới đâu tải tới đó. API phía sau dùng Skip/Take, ai cũng viết vậy. Rồi bắt đầu có hai loại phàn nàn: khách nhiều đơn cuộn càng sâu càng chậm, và thỉnh thoảng cuộn xuống lại thấy một đơn vừa xem xong hiện lại lần nữa.
Lý thuyết vì sao OFFSET chậm dần và vì sao nó làm trùng, sót dòng, mình đã viết ở bài phân trang bằng con trỏ bên series SQL. Bài này là phần làm thật trong .NET: sửa cái endpoint đó qua từng commit, như một PR, từ Skip/Take tới cursor pagination với EF Core và SQL Server.
Điểm xuất phát: Skip/Take
app.MapGet("/api/customers/{customerId:int}/orders", async (
int customerId, int page, int pageSize, AppDbContext db, CancellationToken ct) =>
{
return await db.Orders
.AsNoTracking()
.Where(o => o.CustomerId == customerId)
.OrderByDescending(o => o.CreatedAt)
.Skip((page - 1) * pageSize)
.Take(pageSize)
.Select(o => new OrderListItem(o.Id, o.Total, o.CreatedAt))
.ToListAsync(ct);
});
Trên SQL Server, EF Core dịch Skip/Take thành OFFSET ... ROWS FETCH NEXT ... ROWS ONLY. Trang 500 thì SQL Server vẫn phải đi qua 499 trang trước rồi vứt đi. Chưa kể pageSize do client gửi lên, ai gửi pageSize=100000 thì cũng chiều.
Commit 1: thêm Id vào ORDER BY
Trước cả khi đổi cách phân trang, sửa cái lỗi trùng dòng đã:
.OrderByDescending(o => o.CreatedAt)
.ThenByDescending(o => o.Id) // phân định khi hai đơn trùng CreatedAt
Hai đơn tạo cùng một thời điểm thì thứ tự giữa chúng không xác định, SQL Server sắp kiểu nào cũng được, và hai lần gọi có thể ra hai thứ tự khác nhau. Cắt trang đúng giữa hai đơn đó là một đơn hiện hai lần, đơn kia biến mất. Thêm Id vào cuối ORDER BY thì thứ tự luôn xác định. Commit này nhỏ nhưng có giá trị ngay cả khi bạn không làm tiếp các bước sau.
Commit 2: thay Skip bằng điều kiện con trỏ
Thay vì "bỏ qua N dòng", client gửi lên CreatedAt và Id của dòng cuối cùng nó đã thấy, server lấy những dòng đứng sau dòng đó. Bên SQL thì viết được (created_at, id) < (@x, @y), nhưng LINQ không có cú pháp so sánh tuple, nên phải viết tách:
if (after is not null)
{
var c = after; // biến cục bộ để EF dịch thành tham số
query = query.Where(o =>
o.CreatedAt < c.CreatedAt ||
(o.CreatedAt == c.CreatedAt && o.Id < c.Id));
}
EF Core dịch ra đúng câu WHERE tương ứng. Đây là chỗ mình luôn mở actual execution plan trong SSMS để xem: thứ cần thấy là Index Seek trên index ở commit 5, không phải Index Scan. Nếu plan không seek, một mẹo hay dùng là thêm một điều kiện thừa về mặt logic nhưng giúp optimizer thấy rõ khoảng cần đọc:
query = query.Where(o =>
o.CreatedAt <= c.CreatedAt && // thừa về logic, nhưng cho SQL Server một khoảng để seek
(o.CreatedAt < c.CreatedAt || (o.CreatedAt == c.CreatedAt && o.Id < c.Id)));
Mẹo này có giúp hay không còn tuỳ data và phiên bản SQL Server, nên đừng thêm theo phản xạ: đo trước, thêm sau.
Commit 3: lấy dư một dòng để biết còn trang sau
Client cần biết còn gì để tải nữa không. Cách lười là đếm tổng, nhưng COUNT(*) trên bảng lớn có điều kiện lọc thì không rẻ, mà màn hình cuộn vô hạn chẳng cần con số tổng. Lấy dư một dòng là đủ:
var rows = await query
.OrderByDescending(o => o.CreatedAt)
.ThenByDescending(o => o.Id)
.Take(size + 1) // dư một dòng: có dòng này nghĩa là còn trang sau
.Select(o => new OrderListItem(o.Id, o.Total, o.CreatedAt))
.ToListAsync(ct);
var hasMore = rows.Count > size;
var items = hasMore ? rows.Take(size).ToList() : rows;
Commit 4: đóng gói con trỏ và contract của API
Không đưa createdAt và id ra query string dưới dạng hai tham số rời. Mình gói chúng thành một chuỗi mờ (opaque) để client chỉ việc gửi lại, không cần hiểu bên trong có gì, và sau này mình đổi cách sắp xếp thì không vỡ client.
using System.Diagnostics.CodeAnalysis;
using System.Text.Json;
using Microsoft.AspNetCore.WebUtilities;
public sealed record OrderCursor(DateTime CreatedAt, int Id);
public static class CursorCodec
{
public static string Encode(OrderCursor cursor) =>
WebEncoders.Base64UrlEncode(JsonSerializer.SerializeToUtf8Bytes(cursor));
public static bool TryDecode(string value, [NotNullWhen(true)] out OrderCursor? cursor)
{
cursor = null;
try
{
cursor = JsonSerializer.Deserialize<OrderCursor>(WebEncoders.Base64UrlDecode(value));
// Con trỏ do client gửi lên là input không tin được: kiểm tra trước khi dùng
return cursor is not null && cursor.Id > 0 && cursor.CreatedAt != default;
}
catch (Exception ex) when (ex is FormatException or JsonException)
{
return false;
}
}
}
Base64url thay vì base64 thường để chuỗi đặt thẳng vào URL được, không dính + hay /. System.Text.Json ghi DateTime với đủ 7 chữ số thập phân, khớp độ chính xác của cột datetime2, nên giá trị đi một vòng qua JSON vẫn y nguyên. Cột còn dùng kiểu datetime cũ thì độ chính xác chỉ khoảng 3 mili giây, nhưng vì con trỏ lấy từ giá trị đã đọc ra từ DB nên vẫn khớp.
Ai sửa được chuỗi base64 thì cũng tự chế được con trỏ. Với danh sách đơn của chính khách đó thì chẳng sao, tệ nhất họ tự nhảy tới một chỗ khác trong danh sách của mình. Nếu không muốn client đụng vào, thay WebEncoders bằng IDataProtector của ASP.NET Core: chuỗi được mã hoá và ký, sửa một ký tự là giải mã thất bại. Đổi lại phải cấu hình key ring dùng chung khi chạy nhiều instance.
Ghép tất cả vào endpoint:
public sealed record CursorPage<T>(IReadOnlyList<T> Items, string? NextCursor);
app.MapGet("/api/customers/{customerId:int}/orders", async (
int customerId, string? cursor, int? limit, AppDbContext db, CancellationToken ct) =>
{
// Server quyết định giới hạn, không để client đòi bao nhiêu cũng được
var size = Math.Clamp(limit ?? 20, 1, 100);
OrderCursor? after = null;
if (cursor is not null && !CursorCodec.TryDecode(cursor, out after))
return Results.Problem("Cursor không hợp lệ.", statusCode: StatusCodes.Status400BadRequest);
var query = db.Orders.AsNoTracking().Where(o => o.CustomerId == customerId);
if (after is not null)
{
var c = after;
query = query.Where(o =>
o.CreatedAt < c.CreatedAt ||
(o.CreatedAt == c.CreatedAt && o.Id < c.Id));
}
var rows = await query
.OrderByDescending(o => o.CreatedAt)
.ThenByDescending(o => o.Id)
.Take(size + 1)
.Select(o => new OrderListItem(o.Id, o.Total, o.CreatedAt))
.ToListAsync(ct);
var hasMore = rows.Count > size;
var items = hasMore ? rows.Take(size).ToList() : rows;
var last = items.Count > 0 ? items[items.Count - 1] : null;
var next = hasMore && last is not null
? CursorCodec.Encode(new OrderCursor(last.CreatedAt, last.Id))
: null;
return Results.Ok(new CursorPage<OrderListItem>(items, next));
});
Response trông thế này, nextCursor là null khi đã hết:
{
"items": [ { "id": 98213, "total": 450000, "createdAt": "2026-11-17T09:15:02.1234567" } ],
"nextCursor": "eyJDcmVhdGVkQXQiOiIyMDI2LTExLTE3VDA5OjE1OjAyLjEyMzQ1NjciLCJJZCI6OTgyMTN9"
}
Commit 5: index đúng thứ tự
Không có index phù hợp thì commit 2 cũng vô ích, SQL Server vẫn phải quét rồi sắp xếp. Index cần đi đúng thứ tự lọc rồi sắp xếp: CustomerId trước, rồi CreatedAt và Id giảm dần.
modelBuilder.Entity<Order>()
.HasIndex(o => new { o.CustomerId, o.CreatedAt, o.Id })
.IsDescending(false, true, true); // IsDescending có từ EF Core 7
Tạo migration xong, đọc lại file migration trước khi chạy trên prod: thêm index trên bảng lớn có thể giữ lock khá lâu. Chuyện migration trên bảng lớn mình đã viết ở bài schema và transaction bên series SQL. Riêng SQL Server bản Enterprise có ONLINE = ON để giảm thời gian chặn ghi, bản Standard thì không có.
Những thứ cố tình không nằm trong PR này
Trang trước. Màn hình cuộn vô hạn không cần. Nếu cần, đảo chiều so sánh và chiều sort (> và OrderBy tăng dần), lấy xong đảo lại thứ tự ở code.
Đổi bộ lọc giữa chừng. Con trỏ chỉ có nghĩa với đúng bộ lọc và cách sắp xếp đã tạo ra nó. Endpoint có nhiều bộ lọc thì mình đưa thêm một giá trị nhận diện bộ lọc vào con trỏ, decode ra mà không khớp với request hiện tại thì trả 400.
Export toàn bộ. Job cần kéo hết data thì đừng gọi API từng trang. Trả IAsyncEnumerable<T> từ endpoint, ASP.NET Core sẽ stream JSON ra dần thay vì gom hết vào RAM:
app.MapGet("/api/export/orders", (AppDbContext db) =>
db.Orders.AsNoTracking()
.OrderBy(o => o.Id)
.Select(o => new OrderListItem(o.Id, o.Total, o.CreatedAt))
.AsAsyncEnumerable());
Khi nào vẫn để Skip/Take. Trang admin vài trăm dòng, người dùng cần nhảy tới trang 7 và cần biết tổng số trang: cứ Skip/Take cho đơn giản. Commit 1 (thêm Id vào ORDER BY) thì vẫn nên làm.
Muốn thử ngay: tìm trong solution những chỗ .Skip( nằm trong endpoint mà app mobile hoặc job nội bộ hay gọi sâu. Làm commit 1 trước, mất năm phút. Rồi gọi thử trang đầu và một trang thật sâu, so actual execution plan của hai lần, xem chỗ nào đáng chuyển hẳn sang con trỏ.
Bài trước trong series là tối ưu EF Core, có phần Select ra DTO mà bài này dùng lại. Bài sau là concurrency và idempotency: khách bấm thanh toán hai lần thì sao. Còn bạn đang phân trang kiểu gì cho app mobile? Comment cho mình biết với.
P.S. Hàm CursorCodec là loại code rất hợp với property-based testing: thay vì viết vài case bằng tay, mình khẳng định "với mọi con trỏ hợp lệ, decode của encode phải ra lại đúng con trỏ đó", và "với mọi chuỗi rác, TryDecode trả false chứ không ném exception". Để nghĩ cho ra các tính chất kiểu này, mình dùng skill property-based-testing trong PrimeKit, bộ skill mình tự làm, chuyển thể từ bộ skill của Trail of Bits. Skill nhắm thẳng vào mấy thứ như cặp encode/decode và thứ tự sắp xếp, nhưng các framework nó nêu là của Python, JS, Rust, Java, Go, không có .NET, nên phần test mình tự viết bằng FsCheck. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:property-based-testing kèm code cần test.
All rights reserved