فصل ۱ — مبانی API و HTTP
HTTP برای API — متد، کد وضعیت و هدرفصل ۲ — طراحی REST
منابع، آدرسها و ساختار REST درستفصل ۳ — امنیت و نسخهبندی
احراز API: API Key، JWT و OAuth 2 نسخهبندی، CORS و مدیریت خطای منظمفصل ۴ — مصرف API و کیفیت
مصرف API از فرانت: fetch، retry و حالتهای UIپروژه عملی پایان دوره
پروژه پایانی — API فروشگاه کوچک با احراز، CORS و مستنداتپروژه پایانی — API فروشگاه کوچک با احراز، CORS و مستندات
پروژه پایانی دوره: یک REST API فروشگاه از صفر — محصولات عمومی، سبد و سفارش احرازدار با JWT، CORS درست، خطای منظم، صفحهبندی، rate limit و فایل OpenAPI — قابلیت تحویل مستقیم به تیم فرانت.
راهحل قدمبهقدم پروژه
-
۱
هدف پروژه
ساخت API کامل با CRUD، احراز JWT، قالب خطای ثابت، rate limit و مستند OpenAPI.
-
۲
الزامات و موارد موردنیاز
Node.js + Express؛ آشنایی با JWT و SQLite/MySQL؛ Postman یا curl برای تست.
-
۳
قدم ۱ — ساختار و منابع
سه منبع: products (عمومی)، orders (احرازدار، مالکیت کاربر) و auth (ثبتنام/ورود). قالب پاسخ {data, meta, error} در یک helper ثابت.
-
۴
قدم ۲ — احراز با JWT
POST /auth/register و /auth/login با bcrypt؛ خروجی توکن ۱۵ دقیقهای. middleware requireAuth با بستن alg و چک 401/403؛ /auth/refresh با توکن بلندتر در کوکی HttpOnly.
-
۵
قدم ۳ — CRUD و قواعد
GET /products با فیلتر و صفحهبندی meta؛ POST/PATCH/DELETE فقط ادمین. POST /orders با چک موجودی و محاسبه سمت سرور — قیمت هرگز از کلاینت پذیرفته نمیشود! GET /orders فقط سفارشهای خود کاربر.
-
۶
قدم ۴ — خطا، rate limit و CORS
Error handler مرکزی با کدهای ماشینی؛ express-rate-limit روی /auth (۵ در دقیقه) و کل API (۱۰۰ در دقیقه) با 429؛ CORS whitelist دامنهها.
-
۷
قدم ۵ — 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
کد را ویرایش کنید و «اجرای کد» را بزنید — خروجی واقعی مرورگر همینجا رندر میشود؛ مثل آزمایشگاه 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 کامل هر سه منبع را بنویسید.
پرسش و پاسخ این درس (۰)
هنوز دیدگاهی ثبت نشده؛ اولین نفر باشید!