API & REST Tutorial پروژه عملی پایان دوره پروژه عملی سطح: سخت

پروژه پایانی — API فروشگاه کوچک با احراز، CORS و مستندات

پروژه پایانی دوره: یک REST API فروشگاه از صفر — محصولات عمومی، سبد و سفارش احرازدار با JWT، CORS درست، خطای منظم، صفحه‌بندی، rate limit و فایل OpenAPI — قابلیت تحویل مستقیم به تیم فرانت.

راه‌حل قدم‌به‌قدم پروژه

  1. ۱

    هدف پروژه

    ساخت API کامل با CRUD، احراز JWT، قالب خطای ثابت، rate limit و مستند OpenAPI.

  2. ۲

    الزامات و موارد موردنیاز

    Node.js + Express؛ آشنایی با JWT و SQLite/MySQL؛ Postman یا curl برای تست.

  3. ۳

    قدم ۱ — ساختار و منابع

    سه منبع: products (عمومی)، orders (احرازدار، مالکیت کاربر) و auth (ثبت‌نام/ورود). قالب پاسخ {data, meta, error} در یک helper ثابت.

  4. ۴

    قدم ۲ — احراز با JWT

    POST /auth/register و /auth/login با bcrypt؛ خروجی توکن ۱۵ دقیقه‌ای. middleware requireAuth با بستن alg و چک 401/403؛ /auth/refresh با توکن بلندتر در کوکی HttpOnly.

  5. ۵

    قدم ۳ — CRUD و قواعد

    GET /products با فیلتر و صفحه‌بندی meta؛ POST/PATCH/DELETE فقط ادمین. POST /orders با چک موجودی و محاسبه سمت سرور — قیمت هرگز از کلاینت پذیرفته نمی‌شود! GET /orders فقط سفارش‌های خود کاربر.

  6. ۶

    قدم ۴ — خطا، rate limit و CORS

    Error handler مرکزی با کدهای ماشینی؛ express-rate-limit روی /auth (۵ در دقیقه) و کل API (۱۰۰ در دقیقه) با 429؛ CORS whitelist دامنه‌ها.

  7. ۷

    قدم ۵ — OpenAPI و تست

    openapi.yaml با سه مسیر اصلی و اسکیماهای Product/Order/Error؛ تست دستی همه کدهای وضعیت در Postman و یک اسکریپت smoke-test curl که 2xx/4xx کلیدها را چک می‌کند.

نکات مهم

  • ◆ قبل از خواندن راه‌حل، خودتان حداقل ۳۰ دقیقه تلاش کنید؛ یادگیری واقعی در همین تلاش اتفاق می‌افتد.
  • ◆ راه‌حل را بعد از دیدن، عمداً تغییر دهید و دوباره اجرا کنید تا با هر خط آن آشنا شوید.
  • ◆ اگر جایی گیر کردید، فقط بخش مشکل را جستجو کنید، نه کل پروژه را — دامنه جستجوی کوچک یادگیری را عمیق‌تر می‌کند.

کد کامل راه‌حل پروژه

// app.js — API فروشگاه (اسکلت کامل)
const express = require("express");
const jwt = require("jsonwebtoken");
const bcrypt = require("bcryptjs");
const rateLimit = require("express-rate-limit");
const db = require("./db");
const app = express();
app.use(express.json());

const ok = (res, data, meta) => res.json({ data, ...(meta ? { meta } : {}) });
const fail = (res, status, code, message, fields) =>
  res.status(status).json({ error: { code, message, ...(fields ? { fields } : {}) } });

// rate limit
app.use("/auth", rateLimit({ windowMs: 60_000, max: 5 }));
app.use(rateLimit({ windowMs: 60_000, max: 100 }));

function requireAuth(req, res, next) {
  const t = (req.headers.authorization || "").replace("Bearer ", "");
  if (!t) return fail(res, 401, "no_token", "توکن ارسال نشده");
  try {
    req.user = jwt.verify(t, process.env.JWT_SECRET, { algorithms: ["HS256"] });
    next();
  } catch {
    fail(res, 401, "bad_token", "توکن نامعتبر یا منقضی");
  }
}

app.post("/auth/register", async (req, res) => {
  const email = String(req.body?.email || "").toLowerCase().trim();
  const pass = String(req.body?.password || "");
  if (!email.includes("@")) return fail(res, 422, "validation", "ایمیل نامعتبر", { email: "فرمت اشتباه" });
  if (pass.length < 8) return fail(res, 422, "validation", "رمز کوتاه است", { password: "حداقل ۸ نویسه" });
  const hash = bcrypt.hashSync(pass, 10);
  const info = db.prepare("INSERT INTO users (email, password_hash) VALUES (?, ?)").run(email, hash);
  ok(res, { id: info.lastInsertRowid }, undefined, 201);
});

app.post("/auth/login", (req, res) => {
  const u = db.prepare("SELECT * FROM users WHERE email = ?").get(String(req.body?.email || "").toLowerCase());
  if (!u || !bcrypt.compareSync(String(req.body?.password || ""), u.password_hash)) {
    return fail(res, 401, "bad_credentials", "ایمیل یا رمز اشتباه است");
  }
  ok(res, { token: jwt.sign({ sub: u.id, role: u.role }, process.env.JWT_SECRET, { expiresIn: "15m" }) });
});

app.get("/products", (req, res) => {
  const page = Math.max(1, Number(req.query.page) || 1);
  const per = Math.min(50, Number(req.query.per_page) || 20);
  const rows = db.prepare("SELECT id, name, price FROM products ORDER BY id LIMIT ? OFFSET ?").all(per, (page - 1) * per);
  const total = db.prepare("SELECT COUNT(*) AS c FROM products").get().c;
  ok(res, rows, { page, per_page: per, total });
});

app.post("/orders", requireAuth, (req, res) => {
  const itemId = Number(req.body?.item_id);
  const qty = Math.max(1, Math.min(10, Number(req.body?.qty) || 1));
  const item = db.prepare("SELECT id, price, stock FROM products WHERE id = ?").get(itemId);
  if (!item) return fail(res, 404, "not_found", "محصول یافت نشد");
  if (item.stock < qty) return fail(res, 409, "out_of_stock", "موجودی کافی نیست");
  const total = item.price * qty;      // قیمت سمت سرور!
  const info = db.prepare("INSERT INTO orders (user_id, item_id, qty, total) VALUES (?, ?, ?, ?)")
    .run(req.user.sub, itemId, qty, total);
  res.status(201).json({ data: { id: info.lastInsertRowid, total } });
});

app.use((err, req, res, next) => {
  console.error(err);
  fail(res, 500, "server", "خطای داخلی سرور");
});

app.listen(3000, () => console.log("Store API روی :3000"));

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

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

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

خروجی مورد انتظار

تست‌های مورد انتظار:
  GET /products → 200 با data و meta.total
  POST /auth/register با رمز کوتاه → 422 با fields.password
  POST /orders بدون توکن → 401
  POST /orders با توکن و qty>موجودی → 409
  تعداد بالا /auth → 429 بعد از ۵ تلاش در دقیقه
  کلاینت دامنه خارجی → پاسخ CORS با origin whitelist

چالش اضافه (اختیاری)

نسخه /v2 با فیلد جدید اضافه کنید و هدر Deprecated برای /v1 بگذارید؛ سپس اسکیمای OpenAPI کامل هر سه منبع را بنویسید.

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

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

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

کپچا

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