التنقّل بين الصفحات
جزء من قسم واجهات API بنمط REST في رحلة ASP.NET Core على Coddy. الدرس 13 من 20.
لا يمكن لواجهة API للطلبات التي تضم 10,000 طلب أن تعرضها كلها دفعة واحدة. يتيح تقسيم الصفحات عرض شريحة واحدة: GET /api/orders?page=3&pageSize=20 هي الطلبات من 41 إلى 60. يحتاج العميل أيضًا إلى العدد الإجمالي لعرض «الصفحة 3 من 500»، وينقله ترويسٌ من دون تغيير بنية المتن.
app.MapGet("/api/orders", (HttpResponse response, int page = 1, int pageSize = 20) =>
{
var matching = orders.ToList();
response.Headers["X-Total-Count"] = matching.Count.ToString();
return Results.Ok(matching.Skip((page - 1) * pageSize).Take(pageSize));
});تجعل القيمة الافتراضية مَعلمة الاستعلام اختيارية. تمثل مَعلمة HttpResponse الاستجابة الجاري إعدادها، لذا يمكنك تعيين ترويسة قبل إرجاعها. يحصي X-Total-Count الطلبات المطابقة لعوامل التصفية، قبل تقسيمها إلى صفحات. ارفض أي صفحة رقمها أقل من 1، وحدد حدًا أقصى لحجم الصفحة، حتى لا يتمكن أي عميل من طلب كل شيء دفعة واحدة.
التحدي
متوسطأجب عن المهام صفحةً واحدةً في كل مرة، واذكر عددها الإجمالي.
- أضف ثلاثة معاملات إلى دالة lambda الخاصة بـ
GET /api/tasks، بعدsort:HttpResponse responseوint page = 1وint pageSize = 10. - في قاموس الأخطاء، أضف
Page starts at 1.تحتpageعندما تكون قيمةpageأقل من 1، وأضفPage size is 1 to 50.تحتpageSizeعندما تكون قيمةpageSizeخارج النطاق من 1 إلى 50. - بعد التصفية والترتيب، حوّل النتيجة إلى قائمة. عيّن قيمة الرأس
X-Total-Countإلى عدد عناصرها، ثم أجب عن الصفحة فقط: تخطَّ(page - 1) * pageSizeمن المهام وخذpageSize.
يعرض GET /api/tasks?page=2&pageSize=2 المهمة 3 فقط، مع X-Total-Count: 3. الصفحة التي تتجاوز النهاية تعرض 200 و[].
جرّب ذلك: اضغط على «تشغيل» وأرسل GET /api/tasks?page=2&pageSize=2: المهمة 3، وتعرض علامة التبويب Headers القيمة X-Total-Count: 3. أرسل GET /api/tasks?done=false&pageSize=1: المهمة 1 وX-Total-Count: 2. أرسل GET /api/tasks?page=0&pageSize=99: تظهر استجابة 400 مع كلا الخطأين.
جرّب بنفسك
using System.ComponentModel.DataAnnotations;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();
var tasks = new List<TaskItem>
{
new(1, "Write the project brief", false),
new(2, "Book the meeting room", true),
new(3, "Send the invoice", false),
};
var nextId = 4;
bool TitleTaken(string title, int exceptId) =>
tasks.Any(t => t.Id != exceptId && string.Equals(t.Title, title, StringComparison.OrdinalIgnoreCase));
app.MapGet("/api/tasks", (bool? done, string? search, string? sort) =>
{
var errors = new Dictionary<string, string[]>();
if (sort is not null && sort != "id" && sort != "title")
errors["sort"] = ["Sort by id or title."];
if (errors.Count > 0) return Results.ValidationProblem(errors);
IEnumerable<TaskItem> result = tasks;
if (done is not null) result = result.Where(t => t.Done == done);
if (!string.IsNullOrWhiteSpace(search))
result = result.Where(t => t.Title.Contains(search, StringComparison.OrdinalIgnoreCase));
if (sort == "title") result = result.OrderBy(t => t.Title);
return Results.Ok(result);
});
app.MapGet("/api/tasks/{id:int}", (int id) =>
{
var task = tasks.Find(t => t.Id == id);
return task is null ? Results.NotFound() : Results.Ok(task);
});
app.MapPost("/api/tasks", (TaskInput input) =>
{
var errors = Validation.Errors(input);
if (errors is not null) return Results.ValidationProblem(errors);
if (TitleTaken(input.Title, 0))
return Results.Problem(title: "A task with this title already exists.", statusCode: 409);
var task = new TaskItem(nextId++, input.Title, input.Done);
tasks.Add(task);
return Results.Created($"/api/tasks/{task.Id}", task);
});
app.MapPut("/api/tasks/{id:int}", (int id, TaskInput input) =>
{
var errors = Validation.Errors(input);
if (errors is not null) return Results.ValidationProblem(errors);
var index = tasks.FindIndex(t => t.Id == id);
if (index == -1) return Results.NotFound();
if (TitleTaken(input.Title, id))
return Results.Problem(title: "A task with this title already exists.", statusCode: 409);
tasks[index] = new TaskItem(id, input.Title, input.Done);
return Results.Ok(tasks[index]);
});
app.MapPatch("/api/tasks/{id:int}", (int id, TaskPatch patch) =>
{
var index = tasks.FindIndex(t => t.Id == id);
if (index == -1) return Results.NotFound();
if (patch.Title is not null && TitleTaken(patch.Title, id))
return Results.Problem(title: "A task with this title already exists.", statusCode: 409);
var task = tasks[index];
tasks[index] = task with
{
Title = patch.Title ?? task.Title,
Done = patch.Done ?? task.Done,
};
return Results.Ok(tasks[index]);
});
app.MapDelete("/api/tasks/{id:int}", (int id) =>
{
var removed = tasks.RemoveAll(t => t.Id == id);
return removed == 0 ? Results.NotFound() : Results.NoContent();
});
app.Run();
record TaskItem(int Id, string Title, bool Done);
record TaskInput(
[property: Required(ErrorMessage = "Title is required."), StringLength(80)] string Title,
bool Done);
record TaskPatch(string? Title, bool? Done);
يتضمن هذا الدرس اختبارًا قصيرًا. ابدأ الدرس للإجابة عليه وتتبّع تقدمك.