Menu
CoddyTech

تفاصيل المشكلة

جزء من قسم واجهات API بنمط REST في رحلة ASP.NET Core على Coddy. الدرس 8 من 20.

يترك جسم استجابة 404 الفارغ العميل في حيرة بشأن ما حدث. تفاصيل المشكلة (RFC 9457) هي البنية القياسية بصيغة JSON للأخطاء، وتُرسل مع نوع المحتوى application/problem+json. تستخدم استجابات 400 لديك هذه البنية بالفعل. في واجهة برمجة تطبيقات للطلبات، تجعل ثلاثة أسطر جميع الأخطاء تتبع البنية نفسها:

builder.Services.AddProblemDetails();
var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();

الآن، يجيب GET /api/orders/7 عن طلب يتضمن طلبًا غير موجود باستجابة 404 تحتوي على:

{ "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found", "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00" }

يسجّل AddProblemDetails الخدمة التي تكتب هذه البنية. يضيف UseStatusCodePages جسمًا يصف المشكلة إلى كل استجابة خطأ لا يتضمن جسمًا، سواء صدرت عن Results.NotFound() أو عن مسار لا يطابق أي مسار معرّف. يحوّل UseExceptionHandler الاستثناء غير المعالَج إلى مشكلة 500. تكون قيمة traceId جديدة مع كل طلب؛ وهي تربط الاستجابة بسجلات الخادم.

challenge icon

التحدي

سهل

اجعل أخطاء متتبّع المهام تتخذ شكلًا واحدًا، كي يقرأ العميل كل إخفاق بالطريقة نفسها.

  1. في Program.cs، أضف builder.Services.AddProblemDetails(); في السطر الذي يسبق builder.Build().
  2. أضف app.UseExceptionHandler(); مباشرةً بعد builder.Build()، ثم أضف app.UseStatusCodePages();، قبل أي نقطة نهاية.

لا تغيّر أي شيء آخر: ستواصل نقاط النهاية الإجابة باستخدام Results.NotFound()، وتتولى البرمجية الوسيطة ملء المحتوى. عندئذٍ، ستجيب GET /api/tasks/99 بالرمز 404، مع نوع المحتوى application/problem+json و:

{ "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "title": "Not Found", "status": 404, "traceId": "..." }

جرّب ذلك: اضغط على «تشغيل» وأرسل GET /api/tasks/99: ستحصل على استجابة 404 أعلاه. أرسل GET /api/projects، وهو مسار بلا مسار مطابق: ستحصل على الشكل نفسه. أرسل POST { "title": "" } إلى /api/tasks: سيحتفظ ردّك 400 بـ errors، وسيُضاف إليه traceId.

جرّب بنفسك

using System.ComponentModel.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

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;

app.MapGet("/api/tasks", () => tasks);

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);
    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();
    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();
    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);
quiz iconاختبر نفسك

يتضمن هذا الدرس اختبارًا قصيرًا. ابدأ الدرس للإجابة عليه وتتبّع تقدمك.

جميع دروس واجهات API بنمط REST