تصنيف الأخطاء و Problem Details: شكل واحد لكل الـ errors

01 / ملخص الدرس

شجرة أخطاء الـ API (AppError ومشتقاته) مقابل الأخطاء الغير متوقعة. معيار RFC 9457: application/problem+json بـ type و title و status و detail و instance، و traceId للربط بالـ logs. تحويل أخطاء express.json و Zod و Postgres (23505 و 23503) لأكواد صح، و 404 كـ error، وإزاي ما تسرّبش stack ولا تفاصيل الـ database.

ضمن مسارباك إند Node.js للإنتاج — من تحت الصفر27 / 122

02 / شرح الدرس مكتوبًا

نص شرح المعلم والكود الذي كتبه ونتيجة تشغيله، بنفس ترتيب الدرس.

أهلًا بيك. لو كل route بيرد بالـ errors بشكل مختلف، مرة error، ومرة message، ومرة HTML، الـ frontend هيتعب، والـ mobile app هيتعب أكتر. الحل حاجتين: تصنيف واضح: كل خطأ متوقع ليه class بـ status و type. وشكل موحّد للرد، وفيه معيار رسمي اسمه Problem Details، RFC nine four five seven. errors dot js فيه AppError، و functions صغيرة بتعمل الأنواع المشهورة. problem dot js: الـ error handler الوحيد في الـ app. لو AppError: نحوّله لـ problem بالحقول الرسمية: type، و title، و status، و detail. لو JSON بايز من express dot json، ده error ليه type معروف: four hundred. غير كده: خطأ مش متوقع، يعني bug. نسجّله كامل في الـ logs، ونرد برسالة عامة بس. وفي الآخر instance: الـ path، و traceId: رقم الـ request، علشان الدعم الفني يلاقي الـ log. والـ content type: application problem plus json.

server dot js: request id. routes بترمي errors عادي بـ throw، ومن غير try. boom فيه bug حقيقي. وفي الآخر: أي route مش موجود بيعمل next بـ NotFound، فحتى الـ four oh four بيعدّي على نفس الـ handler. نشغّل.

server.js

import express from "express";
import crypto from "node:crypto";
import { NotFound, Conflict } from "./errors.js";
import { problemHandler } from "./problem.js";

const app = express();
app.use((req, res, next) => {
  req.id = crypto.randomUUID().slice(0, 8);
  next();
});
app.use(express.json());

const emails = new Set(["[email protected]"]);

app.get("/courses/:id", (req, res) => {
  throw NotFound(`الكورس ${req.params.id}`);
});
app.post("/users", (req, res) => {
  if (emails.has(req.body.email)) throw Conflict("الإيميل متسجل قبل كده");
  res.status(201).json({ ok: true });
});
app.get("/boom", async () => {
  const db = undefined;
  return db.query("select 1");
});

app.use((req, res, next) => next(NotFound(`${req.method} ${req.path}`)));
app.use(problemHandler);

app.listen(3000, () => console.log("http://localhost:3000"));

المخرجات

$ node server.js
http://localhost:3000

→ GET /courses/7
← 404 Not Found
  connection: keep-alive
  content-length: 179
  content-type: application/problem+json; charset=utf-8
  etag: W/"b3-DrUqfHWHPrcKFd7bHPFM1kwp2ZY"
  keep-alive: timeout=5
  x-powered-by: Express
{
  "type": "https://api.example.com/problems/not-found",
  "title": "مش موجود",
  "status": 404,
  "detail": "الكورس 7 مش موجود",
  "instance": "/courses/7",
  "traceId": "3681696a"
}

→ POST /users
  {"email":"[email protected]"}
← 409 Conflict
{
  "type": "https://api.example.com/problems/conflict",
  "title": "تعارض",
  "status": 409,
  "detail": "الإيميل متسجل قبل كده",
  "instance": "/users",
  "traceId": "8c73f907"
}

→ POST /users
  {"email": "oops
← 400 Bad Request
{
  "type": "https://api.example.com/problems/bad-json",
  "title": "JSON بايز",
  "status": 400,
  "instance": "/users",
  "traceId": "bfe69146"
}

→ GET /boom
[a720ebd7] TypeError: Cannot read properties of undefined (reading 'query') |     at file:///home/you/my-backend/server.js:24:13
← 500 Internal Server Error
{
  "type": "about:blank",
  "title": "حصلت مشكلة عندنا",
  "status": 500,
  "instance": "/boom",
  "traceId": "a720ebd7"
}

→ GET /nope
← 404 
…

الكورس: four oh four، والـ content type problem plus json، والـ type URL، والـ title والـ detail، والـ instance والـ traceId. الإيميل المكرر: four oh nine conflict. JSON مقطوع: four hundred. boom: الـ client شاف حصلت مشكلة عندنا بس، والـ log في الـ server فيه رقم الـ request والـ TypeError كامل. و nope: نفس الشكل. الـ type ده URL ممكن تعمله صفحة docs بتشرح الخطأ وحله، والـ clients بتقارن بيه بدل ما تقرا الرسالة.

قاعدتين أمان مهمين جدًّا هنا. عمرك ما ترجّع stack trace للـ client: بيكشف أسماء ملفات ومكتبات وإصدارات، والمهاجم بيبني عليها. ورسايل الـ database زي ما هي ممنوعة برضه. Postgres لما يرفض إيميل مكرر، الـ detail بتاعه بيقول اسم العمود والقيمة، يعني ممكن حد يعرف مين متسجل عندك. الصح: الـ log فيه كل حاجة، والـ response فيه اللي الـ client محتاجه بس. التحدي: كل error ليه مكان. ZodError: four twenty two، ومعاها list بالحقول. unique violation من Postgres، code اتنين تلاتة خمسة صفر خمسة: four oh nine، ومن غير ما الـ detail بتاع Postgres يتسرب. foreign key: four twenty two. body كبير: four thirteen. الشروط وحالات الاختبار في الكومنت.

تمرين

زوّد في problemHandler: ZodError ← 422 + errors، و 23505 ← 409، و 23503 ← 422، و entity.too.large ← 413، من غير تسريب تفاصيل.

الحل. نقلنا التحويل لـ function اسمها toProblem، بترجّع problem أو null. AppError زي ما هو. ZodError بالـ issues كـ field و message. الأكواد بتاعة Postgres بأرقامها. و entity too large. ولو null: يبقى bug، نسجّل ونرد five hundred. وفي server dot js: routes للتجربة، و express dot json بـ limit مِيّة byte على route واحد. نشغّل.

server.js

import express from "express";
import crypto from "node:crypto";
import { z } from "zod";
import { NotFound } from "./errors.js";
import { problemHandler } from "./problem.js";

const app = express();
app.use((req, res, next) => {
  req.id = crypto.randomUUID().slice(0, 8);
  next();
});

app.get("/zod", () => {
  z.object({ email: z.email() }).parse({ email: "x" });
});
app.get("/dup", () => {
  const e = new Error("duplicate key value violates unique constraint");
  e.code = "23505";
  e.detail = "Key (email)=([email protected]) already exists.";
  throw e;
});
app.post("/big", express.json({ limit: "100b" }), (req, res) => res.json({ ok: true }));

app.use((req, res, next) => next(NotFound(`${req.method} ${req.path}`)));
app.use(problemHandler);

app.listen(3000, () => console.log("http://localhost:3000"));

المخرجات

$ node server.js
http://localhost:3000

→ GET /zod
← 422 Unprocessable Entity
{
  "type": "https://api.example.com/problems/validation",
  "title": "البيانات مش صح",
  "status": 422,
  "errors": [
    {
      "field": "email",
      "message": "Invalid email address"
    }
  ],
  "instance": "/zod",
  "traceId": "c40bcfd8"
}

→ GET /dup
← 409 Conflict
{
  "type": "https://api.example.com/problems/conflict",
  "title": "متسجل قبل كده",
  "status": 409,
  "instance": "/dup",
  "traceId": "6db5fa1e"
}

→ POST /big
  {"text":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx …
← 413 Payload Too Large
{
  "type": "https://api.example.com/problems/too-large",
  "title": "الـ body كبير",
  "status": 413,
  "instance": "/big",
  "traceId": "61cf2369"
}

→ GET /nope
← 404 Not Found
{
  "type": "https://api.example.com/problems/not-found",
  "title": "مش موجود",
  "status": 404,
  "detail": "GET /nope مش موجود",
  "instance": "/nope",
  "traceId": "5e44f639"
}

zod: four twenty two بالحقل email. dup: four oh nine، ومفيش ولا كلمة من رسالة Postgres. big: four thirteen. nope: four oh four. الدرس الجاي: الـ CORS والـ cookies، وليه المتصفح بيرفض requests شغالة تمام في Postman.

problem.js

import { z } from "zod";
import { AppError } from "./errors.js";

const BASE = "https://api.example.com/problems/";

function toProblem(err) {
  if (err instanceof AppError) {
    return { type: BASE + err.type, title: err.title, status: err.status, detail: err.detail, ...err.extra };
  }
  if (err instanceof z.ZodError) {
    return {
      type: BASE + "validation",
      title: "البيانات مش صح",
      status: 422,
      errors: err.issues.map((i) => ({ field: i.path.join("."), message: i.message })),
    };
  }
  if (err.code === "23505") return { type: BASE + "conflict", title: "متسجل قبل كده", status: 409 };
  if (err.code === "23503") return { type: BASE + "invalid-reference", title: "مرجع مش موجود", status: 422 };
  if (err.type === "entity.parse.failed") return { type: BASE + "bad-json", title: "JSON بايز", status: 400 };
  if (err.type === "entity.too.large") return { type: BASE + "too-large", title: "الـ body كبير", status: 413 };
  return null;
}

export function problemHandler(err, req, res, next) {
  let p = toProblem(err);
  if (!p) {
    console.error(`[${req.id}] ${err.stack.split("\n").slice(0, 2).join(" | ")}`);
    p = { type: "about:blank", title: "حصلت مشكلة عندنا", status: 500 };
  }
  p.instance = req.originalUrl;
  p.traceId = req.id;
  res.status(p.status).type("application/problem+json").json(p);
}

03 / دروس المسار (122)