API & REST Tutorial فصل ۳ — امنیت و نسخه‌بندی درس آموزشی

نسخه‌بندی، CORS و مدیریت خطای منظم

API زنده یعنی تغییر می‌کند؛ نسخه‌بندی (/v1/) اجازه تغییر بدون شکستن کلاینت‌ها می‌دهد. CORS قرارداد مرورگر برای درخواست‌های بین‌دامنه است — پیکربندی غلطش بزرگ‌ترین گلوگاه توسعه است. و خطاها باید منظم باشند: کد ماشینی + پیام انسانی + جزئیات اعتبارسنجی.

مراحل قدم‌به‌قدم

  1. ۱

    نسخه‌بندی عملی

    در مسیر: /v1/ و /v2/ موازی؛ تغییر ناسازگار (حذف فیلد، تغییر معنا) یعنی نسخه جدید؛ تغییر سازگار (فیلد جدید اضافه) در نسخه فعلی مجاز. اعلام تاریخ_EOL برای نسخه‌های قدیمی و هدر هشدار برای کلاینت‌های نزدیک به منقضی.

  2. ۲

    CORS درست

    مرورگر پیش از درخواست بین‌دامنه‌ای با هدر سفارشی، OPTIONS می‌پرسد (preflight). پاسخ سرور: Access-Control-Allow-Origin با دامنه دقیق (هرگز * برای API احرازدار)، Allow-Methods و Allow-Headers مناسب. در Express پکیج cors با whitelist.

  3. ۳

    قالب خطای منظم

    { error: { code: 'validation', message: 'پیام فارسی', fields: { email: 'ایمیل نامعتبر' } } } — کد ماشینی برای منطق کلاینت، message برای نمایش، fields برای فرم. یک Error Handler مرکزی همه خطاها را به این قالب می‌ریزد.

  4. ۴

    مستندسازی OpenAPI

    فایل openapi.yaml قلب مستندات: مسیرها، متدها، اسکیمای ورودی/خروجی و کدهای وضعیت. از آن، UI تعاملی (Swagger UI/Scalar) و حتی تست‌های قراردادی تولید می‌شود. مستندِ به‌روز = قرارداد قابل اعتماد؛ مستند دستی منقضی = فریب.

نکات مهم

  • ◆ تغییر ناسازگار = نسخه جدید؛ فیلد حذف‌شده بدون نسخه جدید، کلاینت‌ها را می‌شکند.
  • ◆ CORS با دامنه‌های صریح؛ * فقط برای APIهای عمومی بدون احراز.
  • ◆ خطا همیشه یک قالب؛ fields برای فرم‌ها حیاتی است.

کد یا مسیر نمونه

const cors = require("cors");

app.use(cors({
  origin: ["https://radikalwp.ir", "http://localhost:3000"],
  methods: ["GET", "POST", "PATCH", "DELETE"],
  allowedHeaders: ["Content-Type", "Authorization"],
  credentials: true,
}));

// خطای مرکزی:
app.use((err, req, res, next) => {
  if (err.name === "ValidationError") {
    return res.status(422).json({
      error: { code: "validation", message: "داده ارسالی نامعتبر است", fields: err.fields },
    });
  }
  console.error(err);
  res.status(500).json({ error: { code: "server", message: "خطای داخلی سرور" } });
});

// openapi.yaml (خلاصه):
// paths:
//   /v1/orders:
//     post:
//       security: [ bearerAuth: [] ]
//       requestBody: { $ref: '#/components/schemas/OrderInput' }
//       responses:
//         '201': { description: 'ساخته شد' }
//         '422': { description: 'اعتبارسنجی ناموفق' }

اجرای زنده کد JavaScript

editor.html
در حال آماده‌سازی زمین بازی…

کد را ویرایش کنید و «اجرای کد» را بزنید — خروجی واقعی مرورگر همین‌جا رندر می‌شود؛ مثل آزمایشگاه w3schools.

پرسش و پاسخ این درس (۰)

هنوز دیدگاهی ثبت نشده؛ اولین نفر باشید!

دیدگاه خود را بنویسید

کپچا

دیدگاه شما پس از تأیید مدیر نمایش داده می‌شود.