ملخص للصفحة
جزء من قسم واجهات API بنمط REST في رحلة ASP.NET Core على Coddy. الدرس 19 من 20.
غالبًا ما تحتاج الصفحة إلى رقم لا تتضمنه القائمة، مثل "4 من 9 متوفرة في المخزون". يمكن للصفحة أن تحسب العدد، لكن سيتعين عليها تنزيل كل عنصر أولًا. أما نقطة النهاية الصغيرة المخصّصة للقراءة فقط، فتُرجع الأعداد بدلًا من ذلك.
app.MapGet("/api/products/stats", () => new
{
total = products.Count,
inStock = products.Count(p => p.InStock),
});ينشئ new { ... } كائنًا مجهولًا، ويكتبه ASP.NET Core بتنسيق JSON: { "total": 9, "inStock": 4 }. تُنفَّذ دالة لامبدا مع كل طلب، لذا تكون الأعداد محدّثة دائمًا. لا تتعارض /api/products/stats مع /api/products/{id:int}: إذ تتقدّم المقطوعة الثابتة على المَعلمة، كما أن stats ليست رقمًا على أي حال.
التحدي
سهلاعرض "1 of 3 done" فوق القائمة.
- في
Program.cs، عيّن مسارًا لـGET /api/tasks/summary. يستجيب بكائن يحتوي علىtotalوdoneوopen، ويُحسب عند وصول الطلب:{ "total": 3, "done": 1, "open": 2 } - في
wwwroot/index.html، أضف<p id="summary"></p>فوق القائمة. - اكتب
async function loadSummary()تجلب/api/tasks/summaryوتعيّنtextContentللفقرة إلى1 of 3 done، وتُنشئ النص منdoneوtotal. استدعها بعدloadTasks().
جرّب ذلك: اضغط على «تشغيل»: تعرض الصفحة 1 of 3 done فوق القائمة. أرسل GET /api/tasks/summary: ستحصل على JSON أعلاه. أرسل PATCH إلى /api/tasks/1 مع { "done": true }، ثم أرسل GET /: 2 of 3 done.
جرّب بنفسك
using System.ComponentModel.DataAnnotations;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
builder.Services.AddCors(options =>
{
options.AddPolicy("board", policy => policy
.WithOrigins("https://board.example.com")
.WithMethods("GET", "POST", "PUT", "PATCH", "DELETE")
.WithHeaders("Content-Type")
.WithExposedHeaders("X-Total-Count"));
});
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();
app.UseCors("board");
app.UseDefaultFiles();
app.UseStaticFiles();
var tasks = new List<TaskItem>
{
new(1, "Write the project brief", false, 1),
new(2, "Book the meeting room", true, 3),
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, int? priority, string? sort, HttpResponse response, int page = 1, int pageSize = 10) =>
{
var errors = new Dictionary<string, string[]>();
if (sort is not null && sort != "id" && sort != "title" && sort != "priority")
errors["sort"] = ["Sort by id, title or priority."];
if (priority is < 1 or > 3)
errors["priority"] = ["Priority is 1 to 3."];
if (page < 1)
errors["page"] = ["Page starts at 1."];
if (pageSize < 1 || pageSize > 50)
errors["pageSize"] = ["Page size is 1 to 50."];
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 (priority is not null) result = result.Where(t => t.Priority == priority);
if (sort == "title") result = result.OrderBy(t => t.Title);
if (sort == "priority") result = result.OrderBy(t => t.Priority);
var matching = result.ToList();
response.Headers["X-Total-Count"] = matching.Count.ToString();
return Results.Ok(matching.Skip((page - 1) * pageSize).Take(pageSize));
});
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, input.Priority);
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, input.Priority);
return Results.Ok(tasks[index]);
});
app.MapPatch("/api/tasks/{id:int}", (int id, TaskPatch patch) =>
{
var errors = Validation.Errors(patch);
if (errors is not null) return Results.ValidationProblem(errors);
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,
Priority = patch.Priority ?? task.Priority,
};
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.MapDelete("/api/tasks", (bool? done) =>
{
if (done != true)
{
return Results.ValidationProblem(new Dictionary<string, string[]>
{
["done"] = ["Add ?done=true to delete the done tasks."],
});
}
tasks.RemoveAll(t => t.Done);
return Results.NoContent();
});
app.Run();
record TaskItem(int Id, string Title, bool Done, int Priority = 2);
record TaskInput(
[property: Required(ErrorMessage = "Title is required."), StringLength(80)] string Title,
bool Done,
[property: Range(1, 3)] int Priority = 2);
record TaskPatch(string? Title, bool? Done, [property: Range(1, 3)] int? Priority);