ایجاد خطاهای استاندارد شرکت در MicroService Node.js (قسمت 1)

مقدمه

رسیدگی به خطا برای هر معماری میکروسرویس بسیار مهم است. یک قالب خطای مداوم به اشکال زدایی ، ورود به سیستم و بهبود پاسخ های API کمک می کند. در این سری دو قسمتی ، نحوه تنظیم خطاهای استاندارد شرکت را با استفاده از http-error-kit و @wthek/express-middleware کشف خواهیم کرد.

در قسمت 1 ، ما بر روی قالب بندی خطای جهانی تمرکز خواهیم کرد ، و اطمینان حاصل می کنیم که همه خطاها در یک میکروسرویس از یک ساختار یکپارچه پیروی می کنند. قسمت 2 قالب بندی خطای سطح نمونه را پوشش می دهد و به انواع مختلف خطای مختلف اجازه می دهد قالب های منحصر به فردی داشته باشند.

چرا خطاهای استاندارد اهمیت دارند

یک قالب خطای استاندارد ارائه می دهد:

• ثبات – هر API از همان ساختار پیروی می کند و ادغام را برای مشتری ها آسان می کند.

• خوانایی – توسعه دهندگان می توانند به سرعت جزئیات خطا را شناسایی کرده و زمان اشکال زدایی را کاهش دهند.

• سهولت اشکال زدایی – تجزیه و تحلیل و نظارت بر ورود آسانتر می شود و باعث افزایش مشاهده می شود.

• ادغام بهتر AI و API – خطاهای ساختاری به مدل های AI و مصرف کنندگان API کمک می کنند تا خرابی را بهتر انجام دهند.

دیدگاه های صنعت در مورد استاندارد سازی خطا

با توجه به مشخصات JSON API، استفاده از یک قالب ساختاری برای خطاها به حفظ سازگاری در پاسخ های API کمک می کند (مشخصات JSON API – خطاها). ارائه دهندگان پیشرو API مانند گوگلبا راه راه، و غیره بر پاسخ های خطای ساختاری به عنوان بهترین روش اصلی برای اکوسیستم های API مقیاس پذیر و قابل حفظ تأکید می کنند:

• راهنمای طراحی Google Cloud API نشان می دهد که پاسخ های خطا باید از یک ساختار مشترک پیروی کند تا خطای سمت مشتری آسانتر شود (راهنمای طراحی Google API).

• مستندات API Stripe یک قالب دقیق برای خطاها برای بهبود اشکال زدایی و راندمان ادغام (خطاهای API Stripe) اعمال می کند.

مشکل خطاهای متناقض

تصور کنید که با یک API ادغام شوید که در آن هر نقطه پایانی خطاهای مختلف را با فرمت دیگری برگرداند:

• دریافت /کاربران { "error": "User not found" }

• ارسال /سفارشات { "status": "error", "message": "Invalid order ID" }

• حذف /محصولات { "code": 400, "msg": "Product cannot be deleted" }

این ناسازگاری مشتری ها را وادار به نوشتن می کند منطق تجزیه سفارشی برای هر پاسخ API ، ادغام دردناک است. در عوض ، یک قالب خطای یکپارچه باعث می شود مشتری ها خطاها را به طور مداوم در تمام API ها انجام دهیدبشر

با این حال ، موارد معتبری وجود دارد که انواع خطای مختلف ممکن است به ساختارهای مختلفی احتیاج داشته باشند. به عنوان مثال ، اعتبار سنجی خطاها ممکن است به جزئیات خاص در زمینه نیاز داشته باشد ، در حالی که احراز هویت خطاها ممکن است به نکات آزمایش مجدد نیاز داشته باشد. نکته اصلی تعادل سازگاری جهانی با انعطاف پذیری خاص از نوع خطا است که در قسمت 2 به آن خواهیم رسید.

مرحله 1: تنظیم یک فرمت خطای جهانی

در http-error-kit بسته به ما اجازه می دهد تا ساختار خطای جهانی این در مورد همه خطاهای موجود در میکروسرویس ما صدق می کند. بیایید یک قالب استاندارد شرکت را برای خطاها تعریف کنیم.

import { Config } from "http-error-kit";

Config.setGlobalFormatter((statusCode, message, details) => ({
  errorCode: statusCode,
  errorMessage: message,
  errorDetails: details,
  timestamp: new Date().toISOString(),
}));

این فرمت تضمین می کند که هر پاسخ خطا در میکروسرویس ما از این ساختار پیروی می کند:

{
  "errorCode": 400,
  "errorMessage": "Invalid request",
  "errorDetails": { "field": "email" },
  "timestamp": "2025-03-10T12:00:00.000Z"
}

مرحله 2: ادغام @WTHEK/Express-Middleware

هنگامی که ما یک فرمت جهانی داریم ، باید اطمینان حاصل کنیم که بیان به طور خودکار تمام پاسخ های خطا را قالب بندی می کند. اینجاست @WTHEK/Express-Middleware وارد می شود

نصب

ابتدا بسته های مورد نیاز را نصب کنید:

npm install http-error-kit @wthek/express-middleware

استفاده از میان افزار در یک میکروسرویس اکسپرس

سرور اکسپرس خود را برای استفاده از میان افزار اصلاح کنید:

import express from "express";
import { KitHttpError } from "http-error-kit";
import { KitExpressMiddleware } from "@wthek/express-middleware";

const app = express();

// Example Route
app.get("/example", (req, res, next) => {
  next(new KitHttpError(400, "Invalid request", { field: "email" }));
});

// Error Handling Middleware
app.use(KitExpressMiddleware());

app.listen(3000, () => console.log("Server running on port 3000"));

اکنون ، هنگامی که خطایی رخ می دهد ، پاسخ از فرمت جهانی ما پیروی می کند:

{
  "errorCode": 400,
  "errorMessage": "Invalid request",
  "errorDetails": { "field": "email" },
  "timestamp": "2025-03-10T12:00:00.000Z"
}

خلاصه

با تنظیم یک قالب خطای جهانی و استفاده از @wthek/express-middleware، ما اطمینان حاصل کرده ایم که همه خطاهای موجود در میکروسرویس ما از یک ساختار استاندارد پیروی می کنند.

با این حال ، همه خطاها نباید دقیقاً از همان قالب پیروی کنند. در بسیاری از موارد ، انواع مختلف خطای – مانند خطاهای اعتبار سنجی ، خطاهای احراز هویت و خطاهای پایگاه داده – ضمن حفظ قوام در API ، به ساختار خود نیاز دارند.

چه چیزی بعدی؟

در قسمت 2 ، ما چگونگی گسترش را بررسی خواهیم کرد http-error-kit برای ایجاد کلاسهای خطای سفارشی با قالب های مختلف برای انواع خطای خاص. این به ما امکان می دهد تا بین استاندارد سازی و انعطاف پذیری به تعادل برسیم ، اطمینان حاصل کنیم که خطاهای مختلف ضمن حفظ قوام گسترده API ، ساختارهای مختلفی دارند.

🚀 برای مقاله بعدی که در آن خطایی را به سطح بعدی می رسانیم ، با ما همراه باشید!