Express দিয়ে REST API — একটি অনলাইন দোকানের ব্যাকএন্ড

১ · REST API — ডেটাকে ঠিকানা দেওয়া

পর্ব ৩৫-এ আপনি ব্রাউজার থেকে fetch দিয়ে সার্ভারের কাছে অনুরোধ পাঠিয়েছিলেন। এবার টেবিলের অন্য পাশে বসার পালা। ধরুন “চালডাল”-ধাঁচের একটি অনলাইন মুদি দোকান বানাচ্ছেন। ওয়েবসাইট, Android অ্যাপ আর দোকানের অ্যাডমিন প্যানেল — তিনটিই একই পণ্যের তালিকা দেখায়, একই অর্ডার নেয়। তিনটির জন্য তিনটি আলাদা ডেটার উৎস রাখা পাগলামি। দরকার একটি সার্ভার প্রোগ্রাম, যে ডেটা পাহারা দেয় আর সবাইকে একই নিয়মে ডেটা দেয়। এমন প্রোগ্রামকে বলে API.

সবচেয়ে প্রচলিত ধাঁচের নাম REST. এর মূল চিন্তা খুব সহজ: সার্ভারের প্রতিটি জিনিস একটি resource — পণ্য, অর্ডার, ব্যবহারকারী। প্রতিটি resource-এর একটি স্থায়ী ঠিকানা (URL) আছে। কী করতে চান, তা বলে HTTP method. আর সার্ভার ফল জানায় status code আর JSON body দিয়ে। প্রতিটি “method + ঠিকানা” জোড়া একটি endpoint.

২ · node:http থেকে Express — framework কেন লাগে

পর্ব ৪৯-এ দেখেছেন, Node.js-এর built-in node:http module দিয়েই একটি server চালানো যায়। প্রতিটি অনুরোধে Node আপনার function-কে দুটি object দেয়: req (অনুরোধ — method, url, header, আর body-র stream) আর res (উত্তর লেখার খাতা)। res.writeHead(status, headers) দিয়ে status আর header, res.end(text) দিয়ে body পাঠিয়ে শেষ:

const http = require("node:http");
http.createServer((req, res) => {
  if (req.method === "GET" && req.url === "/api/products") {
    res.writeHead(200, { "Content-Type": "application/json" });
    return res.end(JSON.stringify([{ id: 1, name: "চাল" }]));
  }
  // GET /api/products/42 ? ঠিকানা কেটে id বের করো, ?category=rice আলাদা করো,
  // POST হলে body-র টুকরো জোড়া দাও, JSON.parse-এ ভুল হলে 400, বড় body ঠেকাও,
  // প্রতিটি অনুরোধ log করো, লগইন যাচাই করো, কোথাও throw হলে 500 ... সব হাতে!
  res.writeHead(404).end();
}).listen(3000);

মন্তব্যগুলোই সমস্যার তালিকা। দশটি endpoint হলে দশটি if, প্রতিটিতে একই body-পড়া, একই error-সামলানো, একই log-লেখা। এই পুনরাবৃত্তি থেকে মুক্তি দিতেই Express. এটি ছোট, জনপ্রিয় একটি framework — বিশাল কিছু নয়, মূলত দুটি জিনিস যোগ করে:

• Routing: “এই method আর এই ঠিকানার জন্য এই function” — এমন নিয়ম ঘোষণা করা, ঠিকানার ভেতরের অংশ (:id) নিজে থেকে বের করা।
• Middleware pipeline: প্রতিটি request কয়েকটি function-এর শিকল পেরিয়ে যায়; প্রতিটি function অনুরোধ পড়তে পারে, বদলাতে পারে, উত্তর দিয়ে দিতে পারে, অথবা পরের জনের হাতে দিতে পারে।

প্রথম Express অ্যাপ

Express একটি npm package (পর্ব ৪৬), তাই আগে ইনস্টল। পাতার ভেতরের রানারে npm package চলে না, তাই নিচের Express কোডগুলো নিজের কম্পিউটারে চালাবেন — প্রত্যাশিত আউটপুট সাথে দেওয়া আছে।

mkdir shop-api && cd shop-api
npm init -y
npm pkg set type=module        # import/export (পর্ব ৪৫)
npm i express

import express from "express";

const app = express();
app.use(express.json());                       // JSON body পড়ে req.body-তে রাখে

const products = [
  { id: 42, name: "মিনিকেট চাল ৫ কেজি", category: "rice", price: 420 },
  { id: 43, name: "মসুর ডাল ১ কেজি", category: "dal", price: 160 },
];

app.get("/api/products", (req, res) => {
  const { category } = req.query;              // ?category=rice → "rice"
  res.json(category ? products.filter((p) => p.category === category) : products);
});

app.get("/api/products/:id", (req, res) => {
  const product = products.find((p) => p.id === Number(req.params.id));  // params সবসময় string
  if (!product) return res.status(404).json({ error: { code: "NOT_FOUND", message: "পণ্যটি পাওয়া যায়নি" } });
  res.json(product);                           // status না দিলে 200
});

app.delete("/api/products/:id", (req, res) => {
  // ... মুছে ফেলার কাজ ...
  res.sendStatus(204);                         // সফল, কিন্তু body নেই
});

app.listen(process.env.PORT ?? 3000, () => console.log("API চলছে"));

$ curl -i "http://localhost:3000/api/products?category=rice"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[{"id":42,"name":"মিনিকেট চাল ৫ কেজি","category":"rice","price":420}]

$ curl -i http://localhost:3000/api/products/99
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"error":{"code":"NOT_FOUND","message":"পণ্যটি পাওয়া যায়নি"}}

৩ · Middleware — প্রতিটি request-এর পাইপলাইন

Express-এর হৃদয় middleware. একটি middleware হলো তিন প্যারামিটারের একটি function — (req, res, next). এর সামনে চারটি পথ খোলা: req পড়া, req-এ কিছু যোগ করা (যেমন req.user), নিজেই উত্তর দিয়ে শিকল থামিয়ে দেওয়া, অথবা next() ডেকে পরের জনের হাতে তুলে দেওয়া। আর next(err) ডাকলে মাঝের সব ধাপ বাদ দিয়ে সোজা error handler-এ।

নিচের ডায়াগ্রামে একটি POST /api/orders অনুরোধ শিকল ধরে এগোচ্ছে। প্রতিটি ধাপে req-এর অবস্থা খেয়াল করুন — আর শেষ ধাপে দেখুন একটি error কীভাবে লাফিয়ে চলে যায়:

method:  "POST"
url:     "/api/orders"
headers: { "content-type": "application/json",
           authorization: "Bearer demo-token-123" }
body:    (এখনো পড়া হয়নি — stream-এ ভাসছে)

const start = performance.now();
res.on("finish", () => console.log(/* method, url, status, সময় */));
next();   // এগিয়ে যান

body: { phone: "01712345678",
        items: [{ productId: 42, qty: 2 }] }
// body ১০০ KB-র বেশি হলে → next(413 error)
// ভাঙা JSON হলে          → next(400 error)

user: { id: "u1", role: "customer" }
// token না থাকলে বা ভুল হলে এখানেই
// res.status(401).json(...) — handler পর্যন্ত যাওয়াই হয় না

res.status(201)
   .location("/api/orders/A-101")
   .json({ id: "A-101", status: "pending", ... });
// এখানে next() ডাকা হয় না — উত্তর দেওয়া মানেই শিকল শেষ

POST /api/orders 201 12.4ms
// উত্তর পাঠানো শেষ হলে logger-এর রেখে যাওয়া listener চলল

handler:  throw new Error("connection refused")
          ↓ Express 5 নিজে ধরে next(err) ডাকে
          ↓ মাঝের সাধারণ middleware সব বাদ
error handler → 500
{ "error": { "code": "INTERNAL",
             "message": "সার্ভারে একটি সমস্যা হয়েছে" } }
// আসল বার্তা আর stack trace শুধু সার্ভারের log-এ

তিন রকম middleware

// শুধু শেখার জন্য নকল token — আসল অ্যাপে session বা JWT (অংশ ৭)
const TOKENS = { "demo-token-123": { id: "u1", role: "customer" },
                 "admin-token-9":  { id: "a1", role: "admin" } };

export function requireAuth(req, res, next) {
  const [scheme, token] = (req.get("authorization") ?? "").split(" ");
  const user = scheme === "Bearer" ? TOKENS[token] : undefined;
  if (!user) return res.status(401).json({ error: { code: "UNAUTHENTICATED", message: "আগে লগইন করুন" } });
  req.user = user;                              // পরের সবার জন্য
  next();
}

export const requireRole = (role) => (req, res, next) =>   // middleware বানানোর function
  req.user?.role === role ? next()
    : res.status(403).json({ error: { code: "FORBIDDEN", message: "এই কাজের অনুমতি আপনার নেই" } });

ক্রমই নিয়ম। app.use(express.json()) যদি route-গুলোর পরে লেখেন, route চলার সময় req.body খালি থাকবে। requireAuth যদি express.static-এর আগে বসান, ছবি দেখতেও লগইন লাগবে। Express উপর থেকে নিচে পড়ে, প্রথম যে উত্তর দেয় সেখানেই থামে।

৪ · Routing আর Router — আর Express-এর ভেতরে উঁকি

Express কীভাবে বোঝে GET /api/products/42 কোন handler-এর? প্রতিটি route-এর ঠিকানা-ছাঁচ (/api/products/:id) ভেতরে একটি regular expression-এ বদলে যায়। অনুরোধ এলে Express route-গুলো ঘোষণার ক্রমে একে একে মিলিয়ে দেখে — method আর path দুটোই মিললে থামে, আর :id-এর জায়গায় যা ছিল তা রাখে req.params-এ:

1app.get("/api/products", list);2app.post("/api/products", create);3app.get("/api/products/:id", getOne);4app.delete("/api/products/:id", remove);

express.Router — প্রতিটি resource-এর জন্য আলাদা ফাইল

সব route এক ফাইলে রাখলে কয়েক মাসেই হাজার লাইন। express.Router() একটি “ছোট অ্যাপ” বানায় — নিজস্ব route আর middleware-সহ — যাকে মূল অ্যাপের একটি ঠিকানায় বসানো (mount) যায়:

import { Router } from "express";
export const productsRouter = Router();

productsRouter.get("/", listProducts);          // GET  /api/products
productsRouter.get("/:id", getProduct);         // GET  /api/products/:id
productsRouter.post("/", requireAuth, requireRole("admin"), createProduct);  // শুধু এই route-এ

app.use("/api/products", productsRouter);       // "/api/products" + "/:id"
app.use("/api/orders", requireAuth, ordersRouter);  // orders-এর সব route-এ লগইন লাগবে

Router-এর ভেতরে ঠিকানা লেখা হয় mount-এর তুলনায় — "/" মানে /api/products. খেয়াল করুন, middleware তিন স্তরে বসানো যায়: পুরো অ্যাপে (app.use(fn)), একটি router-এ (app.use("/api/orders", requireAuth, ...)), বা একটি route-এ (post("/", requireAuth, handler)).

নিজে বানিয়ে দেখুন — Express-এর ভেতরে কী আছে

Express-এর জাদু আসলে কয়েক ডজন লাইনের ধারণা। নিচের প্রোগ্রামটি Node 20-এ চলে, কোনো package ছাড়া — শুধু node:http. এতে আছে use() আর route(), :id-কে regex-এর named group-এ বদলে মেলানো, আকার-সীমাসহ JSON parser, logger, 404 আর একটি error handler. তারপর একই প্রোগ্রাম fetch দিয়ে নিজের কাছেই ছয়টি অনুরোধ পাঠায় (port 0 মানে “যেকোনো খালি port”):

const http = require("node:http");
const chain = [], routes = [], use = (fn) => chain.push(fn);
const route = (method, path, fn) => routes.push({ method, fn, re: RegExp(`^${path.replace(/:(\w+)/g, "(?<$1>[^/]+)")}$`) });
const db = new Map([[1, { id: 1, name: "চাল", price: 420 }], [2, { id: 2, name: "ডাল", price: 160 }]]);
const notFound = { status: 404, message: "পণ্যটি নেই" };
use((req, res, next) => { console.log("→", req.method, req.url); next(); });                 // ১. logger
use(async (req, res, next) => {                                                               // ২. JSON parser
  let raw = ""; for await (const c of req) if ((raw += c).length > 1000) return next({ status: 413, message: "body খুব বড়" });
  try { req.body = raw ? JSON.parse(raw) : {}; next(); } catch { next({ status: 400, message: "ভাঙা JSON" }); }
});
use((req, res, next) => {                                                                     // ৩. router
  const r = routes.find((r) => r.method === req.method && r.re.test(req.url));
  if (!r) return next({ status: 404, message: "এই ঠিকানা নেই" });
  req.params = { ...req.url.match(r.re).groups }; return r.fn(req, res, next);
});
route("GET", "/api/products", (req, res) => res.json(200, [...db.values()]));
route("GET", "/api/products/:id", (req, res, next) => db.has(+req.params.id) ? res.json(200, db.get(+req.params.id)) : next(notFound));
route("DELETE", "/api/products/:id", (req, res, next) => db.delete(+req.params.id) ? res.writeHead(204).end() : next(notFound));
route("POST", "/api/products", (req, res, next) => {
  const { name, price } = req.body;
  if (!name || !(price > 0)) return next({ status: 422, message: "name আর ধনাত্মক price দরকার" });
  const p = { id: Math.max(0, ...db.keys()) + 1, name, price }; db.set(p.id, p);
  res.setHeader("Location", `/api/products/${p.id}`); res.json(201, p);
});
const server = http.createServer((req, res) => {
  res.json = (s, d) => res.writeHead(s, { "Content-Type": "application/json" }).end(JSON.stringify(d));
  let i = 0;
  const next = (err) => err ? res.json(err.status ?? 500, { error: err.status ? err.message : "সার্ভারে সমস্যা" }) // ৪. error handler
    : Promise.resolve().then(() => chain[i++](req, res, next)).catch(next);
  next();
}).listen(0, "127.0.0.1", async () => {
  for (const [method, path, body] of [["GET", "/api/products/2"], ["POST", "/api/products", { name: "তেল", price: 190 }],
    ["POST", "/api/products", { name: "" }], ["DELETE", "/api/products/1"], ["GET", "/api/products"], ["GET", "/api/orders"]]) {
    const res = await fetch(`http://127.0.0.1:${server.address().port}${path}`, { method, body: body && JSON.stringify(body) });
    console.log(`   ${res.status} ${await res.text()} ${res.headers.get("location") ?? ""}`.trimEnd());
  }
  server.close();
});

৫ · REST নকশা — নাম, method, status আর error-এর এক ছাঁচ

Express আপনাকে যেকোনো ঠিকানা আর যেকোনো status ব্যবহার করতে দেয় — GET /deleteOrder?id=5 লিখলেও আটকাবে না। ভালো API-র শৃঙ্খলা আসে নিয়ম থেকে, framework থেকে নয়। ভালো API “অনুমানযোগ্য” — একটি endpoint দেখলে বাকিগুলো আন্দাজ করা যায়।

নামকরণ — বহুবচন নামপদ, ক্রিয়া নয়

• Resource-এর নাম বহুবচন নামপদ: /api/products, /api/orders — /api/getProducts বা /api/product/create নয়। কাজ বলে method.
• একটির ঠিকানা: /api/products/42. সম্পর্ক: /api/users/u1/orders (u1-এর অর্ডারগুলো)। দুই স্তরের বেশি গভীর না করাই ভালো।
• যে কাজ সহজ CRUD-এ পড়ে না (অর্ডারের অবস্থা বদল), সেটিকেও resource-এর অংশ ভাবুন: PATCH /api/orders/A-101/status, body-তে { "status": "shipped" }.
• ঠিকানায় ছোট হাতের অক্ষর আর হাইফেন (/api/delivery-zones); JSON-এর key-তে একটি রীতি বেছে সবখানে মানুন (JavaScript-জগতে সাধারণত camelCase).

Method আর idempotency

পর্ব ৩৫-এর idempotent ধারণা এখন আপনার দায়িত্ব। GET কখনো কিছু বদলাবে না (crawler আর prefetch নিশ্চিন্তে GET পাঠায় — GET /api/orders/5/cancel থাকলে কোনো একদিন বট আপনার অর্ডার বাতিল করে দেবে)। PUT পুরো resource বদলে বসায়, DELETE মুছে — দুটোই দশবার পাঠালেও ফল এক, তাই client নিশ্চিন্তে আবার চেষ্টা করতে পারে। POST idempotent নয় — দুবার এলে দুটি অর্ডার; পেমেন্টের মতো জায়গায় Idempotency-Key header নিয়ে সার্ভারে আগের key মনে রাখা হয়। PATCH শুধু দেওয়া অংশ বদলায়।

প্রতিটি কাজের সঠিক status code

সবচেয়ে বড় পাপ: সবকিছুতে 200, আর body-তে { "success": false }. তখন client-এর res.ok (পর্ব ৩৫), ব্রাউজারের cache, monitoring-এর error গণনা, retry-র যুক্তি — সব মিথ্যা তথ্য পায়। Status code হলো HTTP-র সাধারণ ভাষা; যে প্রোগ্রাম আপনার কোড পড়েনি, সেও এটি বোঝে।

Error-এর এক ছাঁচ

এক endpoint { "msg": "..." }, আরেকটি { "error": "..." }, তৃতীয়টি সাদা লেখা ফেরত দিলে front-end-কে প্রতিটির জন্য আলাদা কোড লিখতে হয়। একটি error envelope ঠিক করে সবখানে মানুন:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "কিছু তথ্য ঠিক নেই",
    "fields": { "phone": "১১ অঙ্কের সঠিক মোবাইল নম্বর দিন", "items.0.qty": "পরিমাণ ১ থেকে ২০" }
  }
}

code প্রোগ্রামের জন্য — স্থির, ইংরেজি, কখনো বদলায় না (front-end এটি দেখে সিদ্ধান্ত নেয়); message মানুষের জন্য — বাংলায়, বদলাতে পারে; fields ফর্মের কোন ঘরে কী সমস্যা। চাইলে একটি আন্তর্জাতিক মানও আছে: RFC 9457-এর “Problem Details” (application/problem+json). কোনটি বাছলেন তার চেয়ে গুরুত্বপূর্ণ, সব endpoint একই ছাঁচ মানছে কি না।

৬ · ইনপুট যাচাই, pagination, filter আর sort

পর্ব ৩৯-এ ফর্মের যাচাই শিখেছেন আর দেখেছেন কেন ব্রাউজারের যাচাই শুধু সুবিধার জন্য; পর্ব ৪৩-এর নীতিও একই — প্রতিটি সিদ্ধান্ত সার্ভারে আবার যাচাই। এখন সেই নিয়মের অন্য প্রান্ত: সার্ভারে আসা প্রতিটি byte শত্রুর পাঠানো ধরে নিন। আপনার সুন্দর ফর্ম বাদ দিয়েও যে কেউ curl, Postman বা DevTools থেকে সরাসরি অনুরোধ পাঠাতে পারে — qty: -5, price: 1, role: "admin", দশ লাখ item. তাই server-side validation ঐচ্ছিক নয়।

POST /api/orders
Authorization: Bearer demo-token-123
Content-Type: application/json

{ "phone": "0171234",
  "items": [{ "productId": 42, "qty": 0, "price": 1 }] }

phone  "0171234"  /^01[3-9]\d{8}$/  ✗ ১১ অঙ্ক নয়
items  array, ১টি               ✓
items.0.qty  0   ১–২০?          ✗
items.0.price    — পড়াই হয় না, দাম আসে ডেটাবেস থেকে

HTTP/1.1 422 Unprocessable Content

{ "error": { "code": "VALIDATION_FAILED",
    "message": "কিছু তথ্য ঠিক নেই",
    "fields": { "phone": "১১ অঙ্কের সঠিক মোবাইল নম্বর দিন",
                "items.0.qty": "পরিমাণ ১ থেকে ২০" } } }

{ "phone": "01712345678",
  "items": [{ "productId": 42, "qty": 2 }] }

validateOrder → null (কোনো ভুল নেই)
orderService.create(req.user.id, body)
  → দাম: ডেটাবেস থেকে ৪২০ × ২ = ৮৪০

HTTP/1.1 201 Created
Location: /api/orders/A-101
Content-Type: application/json; charset=utf-8

{ "id": "A-101", "status": "pending", "total": 840,
  "items": [{ "productId": 42, "qty": 2, "unitPrice": 420 }] }

GET /api/orders/A-101       → 200
GET /api/orders/A-102       → 404  (অন্যের অর্ডার — ৪০৩ নয়, কেন? অংশ ৭)

Express-এ ব্যবহার এমন দেখায় — যাচাইয়ের function আলাদা রাখলে সেটি টেস্ট করাও সহজ:

ordersRouter.post("/", async (req, res) => {
  const invalid = validateOrder(req.body);
  if (invalid) return res.status(422).json({ error: invalid.error });
  const { phone, items } = req.body;            // শুধু চেনা field
  const order = await orderService.create(req.user.id, { phone, items });
  res.status(201).location(`/api/orders/${order.id}`).json(order);
});

ordersRouter.patch("/:id/status", requireRole("admin"), async (req, res) => {
  const allowed = ["pending", "packed", "shipped", "delivered", "cancelled"];
  if (!allowed.includes(req.body?.status))
    return res.status(422).json({ error: { code: "VALIDATION_FAILED", message: "অবস্থাটি অজানা",
                                           fields: { status: `এর একটি দিন: ${allowed.join(", ")}` } } });
  res.json(await orderService.setStatus(req.params.id, req.body.status));  // না পেলে service 404 ছোড়ে
});

হাতে লেখা যাচাই ছোট API-তে চলে, কিন্তু field বাড়লে ঝামেলা বাড়ে। তখন একটি schema library ব্যবহার করুন — JavaScript-জগতে সবচেয়ে জনপ্রিয় Zod: z.object({ phone: z.string().regex(...), items: z.array(...).min(1) }) লিখে schema.safeParse(req.body) ডাকলে যাচাই, অজানা field বাদ দেওয়া আর TypeScript-এর type (পর্ব ৪৭) — তিনটিই এক জায়গা থেকে আসে। Fastify-র মতো framework JSON Schema দিয়ে একই কাজ নিজেই করে।

Pagination, filter আর sort

দোকানে দশ হাজার পণ্য হলে GET /api/products একবারে সব পাঠালে মোবাইল ডেটা আর সার্ভার — দুটোই কাঁদবে। তাই তালিকা আসে পাতায় পাতায় (pagination), আর query দিয়ে ছাঁকা ও সাজানো হয়: /api/products?category=rice&page=2&limit=5&sort=-price (“-” মানে বেশি থেকে কম)। প্রতিটি query মান string আর পুরোপুরি client-এর হাতে, তাই এখানেও যাচাই — আর সীমা:

1function paginate(list, q) {2  const page = Math.max(1, parseInt(q.page) || 1);3  const limit = Math.min(50, Math.max(1, parseInt(q.limit) || 10));4  const offset = (page - 1) * limit;5  const data = list.slice(offset, offset + limit);6  return { data, page, limit, total: list.length,7           totalPages: Math.ceil(list.length / limit) };8}

এবার যাচাই আর pagination-এর আসল function দুটি চালিয়ে দেখুন। এগুলো সাধারণ JavaScript, তাই ব্রাউজারেই চলে — আর ঠিক এই function-ই Express-এর handler থেকে ডাকা হবে:

const BD_PHONE = /^01[3-9]\d{8}$/;
function validateOrder(body) {
  const fields = {};
  if (!BD_PHONE.test(body?.phone ?? "")) fields.phone = "১১ অঙ্কের সঠিক মোবাইল নম্বর দিন";
  if (!Array.isArray(body?.items) || body.items.length === 0) fields.items = "অন্তত একটি পণ্য দিন";
  else body.items.forEach((it, i) => {
    if (!Number.isInteger(it?.qty) || it.qty < 1 || it.qty > 20) fields[`items.${i}.qty`] = "পরিমাণ ১ থেকে ২০";
  });
  if (Object.keys(fields).length === 0) return null;
  return { status: 422, error: { code: "VALIDATION_FAILED", message: "কিছু তথ্য ঠিক নেই", fields } };
}
function paginate(list, q) {
  const page = Math.max(1, parseInt(q.page) || 1);
  const limit = Math.min(50, Math.max(1, parseInt(q.limit) || 10));
  const sorted = q.sort === "-price" ? list.toSorted((a, b) => b.price - a.price) : list;
  const data = sorted.slice((page - 1) * limit, page * limit).map((p) => p.id);
  return { data, page, limit, total: list.length, totalPages: Math.ceil(list.length / limit) };
}
console.log(JSON.stringify(validateOrder({ phone: "0171234", items: [{ id: 7, qty: 0 }] })));
console.log(validateOrder({ phone: "01712345678", items: [{ id: 7, qty: 2 }] }));
const rice = Array.from({ length: 23 }, (_, i) => ({ id: i + 1, price: 50 + ((i * 37) % 60) }));
console.log(JSON.stringify(paginate(rice, { page: "2", limit: "5", sort: "-price" })));
const { data, ...meta } = paginate(rice, { page: "abc", limit: "1000" });
console.log(data.length, meta);

৭ · Error middleware, async error আর নিরাপত্তার মূল নিয়ম

চার প্যারামিটারের error handler

Express একটি middleware-কে error handler হিসেবে চেনে শুধু তার প্যারামিটারের সংখ্যা দেখে — ঠিক চারটি: (err, req, res, next). ব্যবহার না করলেও next লিখতে হবে, নইলে Express এটিকে সাধারণ middleware ভাববে। এটি বসে সব route-এর পরে, একদম শেষে:

export class HttpError extends Error {          // পর্ব ২৯-এর custom error
  constructor(status, code, message, fields) {
    super(message);
    Object.assign(this, { status, code, fields });
  }
}

export function notFound(req, res) {            // কোনো route মেলেনি
  res.status(404).json({ error: { code: "NOT_FOUND", message: "এই ঠিকানায় কিছু নেই" } });
}

export function errorHandler(err, req, res, next) {
  if (res.headersSent) return next(err);        // উত্তর অর্ধেক গেছে — Express-কে দিন
  const status = err.status ?? err.statusCode ?? 500;
  if (status >= 500) console.error(err);        // পুরো বিবরণ শুধু সার্ভারের log-এ
  res.status(status).json({ error: {
    code: err.code ?? (status >= 500 ? "INTERNAL" : "BAD_REQUEST"),
    message: status >= 500 ? "সার্ভারে একটি সমস্যা হয়েছে, একটু পরে চেষ্টা করুন" : err.message,
    ...(err.fields && { fields: err.fields }),
  } });
}

// app.js-এর একদম শেষে:  app.use(notFound);  app.use(errorHandler);

Async error — Express 5 বনাম Express 4

Handler সাধারণত async function — ডেটাবেসের জন্য অপেক্ষা করে। Async function-এর ভেতরে throw হলে সেটি আসলে একটি rejected Promise. Express 5 handler-এর ফেরত দেওয়া Promise reject হলে নিজেই next(err) ডাকে — উপরের কোড তাই নিরাপদ। Express 4 এটি করে না: rejected Promise কেউ ধরে না, client-এর অনুরোধ ঝুলে থাকে, আর Node একটি unhandled rejection দেখায় — Node 15 থেকে যার ডিফল্ট ফল পুরো process বন্ধ হয়ে যাওয়া। Express 4-এর পুরোনো প্রজেক্টে তাই প্রতিটি async handler মোড়াতে হয়:

// শুধু Express 4-এ দরকার
const wrap = (fn) => (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
router.get("/:id", wrap(async (req, res) => { /* ... */ }));
// অথবা একবারে: import "express-async-errors";  (Express-কে patch করে)

AI আর পুরোনো টিউটোরিয়াল প্রায়ই Express 4-এর যুগের কোড দেয় — npm i body-parser আর app.use(bodyParser.json()). Express 4.16 (২০১৭) থেকেই express.json() built-in, আলাদা package লাগে না। এমন কোড দেখলে বুঝবেন উৎসটি পুরোনো, তাই async error সামলানোর দিকেও আলাদা নজর দিন।

নিরাপত্তার মূল নিয়ম — শুরু থেকেই

import express from "express";
import helmet from "helmet";
import cors from "cors";
import { rateLimit } from "express-rate-limit";

export const app = express();
app.set("trust proxy", 1);                    // Nginx/হোস্টিং-এর proxy-র পেছনে থাকলে — আসল IP
app.use(helmet());                            // নিরাপত্তা header, X-Powered-By বাদ
app.use(cors({ origin: ["https://shop.example.com"], credentials: true }));  // নির্দিষ্ট origin
app.use("/api", rateLimit({ windowMs: 15 * 60 * 1000, limit: 300 }));      // ১৫ মিনিটে ৩০০
app.use(express.json({ limit: "10kb" }));     // অর্ডারের body এর চেয়ে বড় হয় না
app.use(logger);
app.use("/api/products", productsRouter);
app.use("/api/orders", requireAuth, ordersRouter);
app.use(notFound);
app.use(errorHandler);

• helmet: এক লাইনে একগুচ্ছ security header বসায় (Strict-Transport-Security, X-Content-Type-Options, Content-Security-Policy…) আর Express-এর X-Powered-By: Express header সরিয়ে দেয়, যাতে আপনার প্রযুক্তি ঢাক পিটিয়ে জানানো না হয়।
• CORS: শুধু আপনার নিজের front-end-এর origin-কে অনুমতি দিন। cors() একা দিলে Access-Control-Allow-Origin: * যায় — প্রকাশ্য, লগইনহীন API-র জন্য ঠিক আছে। কিন্তু cookie বা credentials লাগলে ব্রাউজার * মানে না, আর তখন “যে origin চাইছে তাকেই অনুমতি” (origin: true) দেওয়া মানে যেকোনো সাইটকে আপনার ব্যবহারকারীর পরিচয়ে আপনার API পড়তে দেওয়া। বিস্তারিত পর্ব ৪৩-এ।
• Rate limit: একটি IP নির্দিষ্ট সময়ে কতটি অনুরোধ পাঠাতে পারবে; বেশি হলে 429. লগইন আর OTP পাঠানোর endpoint-এ আরও কড়া সীমা দিন (যেমন ১৫ মিনিটে ৫ বার) — পাসওয়ার্ড অনুমানের আক্রমণ আর আপনার SMS বিল দুটোই বাঁচবে।
• Body size limit: ডিফল্ট ১০০ KB, আপনার দরকার অনুযায়ী আরও কমান; বেশি হলে 413. ফাইল আপলোড আলাদা route-এ, আলাদা সীমায়।
• Error-এ গোপন তথ্য নয়: stack trace, SQL, ফাইলের path, library-র version — কিছুই উত্তরে নয়। Log-এও পাসওয়ার্ড, token বা পুরো কার্ড নম্বর লিখবেন না।

Authentication এক নজরে

“আপনি কে” প্রমাণ করা authentication; “আপনি কী করতে পারেন” ঠিক করা authorization. Express-এ লগইনের দুটি প্রধান পথ:

যে পথই নিন, পাসওয়ার্ড কখনো সাধারণ লেখায় বা সাধারণ hash-এ (MD5, SHA-256) নয় — রাখুন ধীর, salt-যুক্ত password hashing দিয়ে: Argon2id, bcrypt, বা Node-এর built-in crypto.scrypt. ডেটাবেস ফাঁস হলেও তখন পাসওয়ার্ডগুলো উল্টে বের করা অত্যন্ত ব্যয়বহুল। পূর্ণ auth ব্যবস্থা (রেজিস্ট্রেশন, ইমেইল যাচাই, পাসওয়ার্ড রিসেট, OAuth দিয়ে “Google দিয়ে লগইন”) এই পর্বের বাইরে; বাস্তবে অনেক দল এর জন্য পরীক্ষিত library বা সেবা ব্যবহার করে।

৮ · পেশাদার প্রজেক্ট — config, গঠন, টেস্ট, ডক আর বিকল্প

পরিবেশ-নির্ভর config

Port, ডেটাবেসের ঠিকানা, গোপন key — এগুলো কোডে লেখা যায় না; আপনার ল্যাপটপ আর প্রোডাকশন সার্ভারে মান আলাদা, আর গোপন মান git-এ গেলে চিরকালের মতো ফাঁস। এগুলো আসে environment variable থেকে: process.env.PORT. স্থানীয়ভাবে একটি .env ফাইলে রেখে Node 20.6 থেকে node --env-file=.env server.js দিয়ে চালানো যায় (আগে এর জন্য dotenv package লাগত)। .env অবশ্যই .gitignore-এ, আর রিপোজিটরিতে থাকে শুধু মানহীন একটি .env.example. বেশিরভাগ হোস্টিং প্ল্যাটফর্ম নিজেই PORT ঠিক করে দেয়, তাই process.env.PORT ?? 3000. শুরুতেই প্রয়োজনীয় মানগুলো যাচাই করে না পেলে অ্যাপ চালু হতে দেবেন না — মাঝরাতে অর্ধেক-কাজ-করা সার্ভারের চেয়ে চালু না হওয়া সার্ভার ভালো।

প্রজেক্টের গঠন — স্তরে স্তরে

shop-api/
├── src/
│   ├── app.js              # middleware আর router জোড়া — listen নয় (টেস্টের জন্য)
│   ├── server.js           # app.listen(process.env.PORT)
│   ├── routes/             # ঠিকানা → controller  (orders.js, products.js)
│   ├── controllers/        # req পড়া, যাচাই, status আর JSON
│   ├── services/           # ব্যবসার নিয়ম: দাম, স্টক, অর্ডারের অবস্থা
│   ├── repositories/       # ডেটাবেসের সাথে কথা (পর্ব ৫২)
│   └── middleware/         # auth, errors, logger
├── test/
├── .env.example
└── package.json

এই layered architecture-এর মূল নিয়ম: প্রতিটি স্তর শুধু ঠিক নিচের স্তরকে চেনে। Service জানে না HTTP কী — সে শুধু “অর্ডার তৈরি করো, স্টক না থাকলে ConflictError” জানে। ফলে একই service কাল একটি CLI টুল বা queue worker থেকেও ডাকা যায়, আর ডেটাবেস বদলালে শুধু repository বদলায়। এই পর্বে ডেটা রাখা হয়েছে মেমরিতে (একটি Map বা array) — সার্ভার বন্ধ হলেই সব হারায়। পর্ব ৫২-এ repository-র পেছনে আসল ডেটাবেস বসবে, বাকি স্তরগুলো না বদলেই।

API টেস্ট — supertest আর Vitest

পর্ব ৪৮-এর Vitest দিয়েই API টেস্ট করা যায়। supertest library Express app-কে সরাসরি নিয়ে নকল HTTP অনুরোধ পাঠায় — কোনো port খুলতে হয় না। এজন্যই app.js আর server.js আলাদা:

import request from "supertest";
import { describe, it, expect } from "vitest";
import { app } from "../src/app.js";

const auth = { Authorization: "Bearer demo-token-123" };

describe("POST /api/orders", () => {
  it("লগইন ছাড়া 401", async () => {
    await request(app).post("/api/orders").send({}).expect(401);
  });
  it("ভুল ফোন নম্বরে 422 আর field-এর error", async () => {
    const res = await request(app).post("/api/orders").set(auth)
      .send({ phone: "123", items: [{ productId: 42, qty: 1 }] });
    expect(res.status).toBe(422);
    expect(res.body.error.fields).toHaveProperty("phone");
  });
  it("ঠিক অর্ডারে 201 আর Location", async () => {
    const res = await request(app).post("/api/orders").set(auth)
      .send({ phone: "01712345678", items: [{ productId: 42, qty: 2 }] });
    expect(res.status).toBe(201);
    expect(res.headers.location).toMatch(/^\/api\/orders\//);
  });
});

$ npx vitest run
 ✓ test/orders.test.js (3 tests)
   ✓ POST /api/orders > লগইন ছাড়া 401
   ✓ POST /api/orders > ভুল ফোন নম্বরে 422 আর field-এর error
   ✓ POST /api/orders > ঠিক অর্ডারে 201 আর Location
 Test Files  1 passed (1)
      Tests  3 passed (3)

প্রত্যাশিত আউটপুট উপরে (সময়ের লাইন বাদ)। Happy path-এর চেয়ে error-এর পথগুলোর টেস্ট বেশি জরুরি: ৪০১, ৪০৩, ৪২২, অন্যের অর্ডার চাইলে ৪০৪, খুব বড় body-তে ৪১৩।

ডকুমেন্টেশন আর versioning

Front-end-এর সহকর্মী বা অন্য কোম্পানি আপনার API ব্যবহার করবে কীভাবে? প্রচলিত মান হলো OpenAPI (আগের নাম Swagger): একটি YAML/JSON ফাইলে প্রতিটি endpoint, প্যারামিটার, body-র গঠন আর সম্ভাব্য status লেখা থাকে। সেখান থেকে Swagger UI-এর মতো টুল চেষ্টা করে দেখার মতো পাতা বানায়, আর client-এর কোডও তৈরি করা যায়। Zod-এর schema থেকে OpenAPI বানানোর library-ও আছে — তাহলে যাচাই আর ডক একই উৎস থেকে আসে, কখনো অমিল হয় না।

একবার মোবাইল অ্যাপ বাজারে গেলে আপনি আর পুরোনো API ভাঙতে পারবেন না — হাজারো ফোনে পুরোনো সংস্করণ চলছে। তাই API versioning: app.use("/api/v1/orders", ...). নতুন field যোগ করা ভাঙন নয়; field সরানো, নাম বদলানো বা অর্থ বদলানো ভাঙন — তখন /api/v2, আর পুরোনোটি কিছুকাল চালু রেখে ধীরে ধীরে বন্ধ।

Express-এর বিকল্প

ধারণাগুলো — routing, middleware, যাচাই, error handler, status code — সবগুলোতে একই। Express-এ যা শিখলেন, তা যেকোনোটিতে নিয়ে যেতে পারবেন।

৯ · AI-এর যুগে — AI-এর লেখা API যাচাই

“Express দিয়ে একটি অর্ডার API বানাও” — AI এক মিনিটে চল্লিশ লাইন দেবে, Postman-এ সব সবুজ। কারণ ডেমোতে কেউ দুষ্টু ইনপুট পাঠায় না, ডেটাবেস কখনো ভাঙে না, আর একজনই ব্যবহারকারী। AI-এর লেখা ব্যাকএন্ডে বারবার যে সমস্যাগুলো দেখা যায়:

AI-এর লেখা API — যাচাইয়ের চেকলিস্ট

• প্রতিটি body, query আর param সার্ভারে যাচাই হয়; শুধু চেনা field নেওয়া হয়, দাম বা মালিক client থেকে নয়
• প্রতিটি endpoint সঠিক status দেয় (২০১ + Location, ২০৪, ৪০০, ৪০১, ৪০৩, ৪০৪, ৪২২), আর সব error এক ছাঁচের JSON
• চার প্যারামিটারের error handler সবার শেষে; ৫০০-তে stack trace বা আসল বার্তা নেই; NODE_ENV=production
• Async error ধরা পড়ে — Express 5, নয়তো প্রতিটি handler মোড়ানো
• প্রতিটি object-এ মালিকানা বা ভূমিকা যাচাই আছে, শুধু লগইন নয়
• পাসওয়ার্ড Argon2id/bcrypt-এ hash; গোপন মান .env-এ, git-এ নয়
• helmet, নির্দিষ্ট origin-এর CORS, rate limit, body-র আকারে সীমা, pagination-এ limit-এর উপরের সীমা আছে
• Error-এর পথগুলোর টেস্ট আছে, আর curl দিয়ে নিজে দুষ্টু অনুরোধ পাঠিয়ে দেখেছি