Middleware

Controller များတွင် auth၊ permission နှင့် audit middleware ကို တပ်ဆင်အသုံးပြုရပါသည်။ Plugin တစ်ခုလုံးအတွက် @Module ၏ globalFilter / globalExceptionsFilter ဖြင့် မှတ်ပုံတင်နိုင်ပြီး၊ @Middleware ဖြင့် ကိုယ်ပိုင် middleware လည်း ရေးနိုင်ပါသည်။

အသုံးပြုပုံ

Controller class တစ်ခုလုံး (route အားလုံး) သို့မဟုတ် method တစ်ခုတည်းတွင် decorate လုပ်ရပါသည်။ Middleware များကို အလုပ်လုပ်စေလိုသော အစဉ်အတိုင်း စီရပါသည် — admin API များတွင် auth ကို permission မတိုင်မီ အရင် တပ်လေ့ရှိပါသည်။ App တစ်ခုလုံး၏ request တိုင်းတွင် လိုအပ်ပါက root @Module ၏ globalFilter ကို အသုံးပြုရပါသည်။

TSXusage

import {
  AuditLogMiddleware,
  AuthenticatedUserOnly,
  CheckAPIPermission,
  Controller,
  Get,
  ResponseDto,
} from "@quan-erp/shared-backend-core";

@Controller("/admin-dashboard")
export class AdminDashboardController {
  @Get("/stats")
  @AuthenticatedUserOnly()
  @CheckAPIPermission()
  @AuditLogMiddleware((req) => `View stats`)
  async getStats() {
    return ResponseDto.ok(data);
  }
}

Builtin middleware

@AuthenticatedUserOnly() — အကောင့်မဝင်သော caller ကို 401 ဖြင့် ငြင်းပယ်ပါသည် — login လိုအပ်သော endpoint တိုင်းတွင် အသုံးပြုရပါသည်
@CheckAPIPermission() — လက်ရှိ method နှင့် URL အတွက် အသုံးပြုသူ၏ အခန်းကဏ္ဍ ခွင့်ပြု API ကို စစ်ဆေးပါသည် — admin route တွင် @AuthenticatedUserOnly နှင့် တွဲသုံးရပါသည်
@AuditLogMiddleware(action) — static string သို့မဟုတ် (req) => string ဖြင့် ထိခိုက်လွယ်သော လုပ်ဆောင်ချက်များ၏ audit မှတ်တမ်း ရေးပါသည်

TSXaudit

import {
  AuditLogMiddleware,
  Controller,
  Get,
  Put,
} from "@quan-erp/shared-backend-core";

@Controller("/branch")
export class BranchController {
  @AuditLogMiddleware("View all branches")
  @Get("/")
  async getAll() { /* … */ }

  @AuditLogMiddleware((req) => `Update branch ${req.params.id}`)
  @Put("/:id")
  async update() { /* … */ }
}

Global middleware (module)

Root @Module တွင် filter များကို မှတ်ပုံတင်ပါက controller တစ်ခုတည်းမဟုတ်ဘဲ request တိုင်းတွင် အလုပ်လုပ်ပါသည်။ Request အတွက် globalFilter၊ အမှားကိုင်တွယ်ရန် globalExceptionsFilter ကို အသုံးပြုရပါသည်။ Plugin ကို uninstall လုပ်သောအခါ core က ၎င်းတို့ကို အလိုအလျောက် ဖြုတ်ပေးပါသည်။

globalFilter: { position, handler }[] — app တစ်ခုလုံးအတွက် request middleware
globalExceptionsFilter: handler[] — app တစ်ခုလုံးအတွက် exception middleware (IExceptionMiddleware)
MiddlewarePosition.BEFORE_ROOT_ROUTE — plugin root route မတိုင်မီ အလုပ်လုပ်ပါသည် (auth / resolve-user / logging အတွက် သင့်တော်ပါသည်)
MiddlewarePosition.AFTER_ROOT_ROUTE — root stack ပြီးနောက် အလုပ်လုပ်ပါသည်
Handler — Express RequestHandler သို့မဟုတ် IExpressMiddleware / IExceptionMiddleware ကို implement လုပ်သော class
Class middleware တိုင်းတွင် @MiddlewareMetadata({ plugin: metadata.name }) မဖြစ်မနေ လိုအပ်ပါသည်

TSXglobalFilter on @Module

import {
  MiddlewareMetadata,
  MiddlewarePosition,
  Module,
} from "@quan-erp/shared-backend-core";
import type {
  IExceptionMiddleware,
  IExpressMiddleware,
} from "@quan-erp/shared-backend-core";
import type { NextFunction, Request, Response } from "express";
import metadata from "../../module.metadata.json" with { type: "json" };
import { MyController } from "./my.controller.js";
import { MyService } from "./my.service.js";

@MiddlewareMetadata({ plugin: metadata.name })
export class RequestIdMiddleware implements IExpressMiddleware {
  handler(req: Request, res: Response, next: NextFunction) {
    res.setHeader("x-request-plugin", metadata.name);
    return next();
  }
}

@MiddlewareMetadata({ plugin: metadata.name })
export class PluginErrorFilter implements IExceptionMiddleware {
  handler(error: Error, req: Request, res: Response, next: NextFunction) {
    if (res.headersSent) return next(error);
    res.status(500).json({ message: error.message });
  }
}

@Module({
  name: metadata.name,
  providers: [MyService],
  controllers: [MyController],
  entities: [],
  globalFilter: [
    {
      position: MiddlewarePosition.BEFORE_ROOT_ROUTE,
      handler: RequestIdMiddleware,
    },
  ],
  globalExceptionsFilter: [PluginErrorFilter],
})
export class MyPluginModule {}

ကိုယ်ပိုင် middleware ဖန်တီးခြင်း

Controller သို့မဟုတ် method အတွက် Middleware(...) ကို decorator အဖြစ် ထုပ်ပိုးရေးရပါသည်။ DI သိသော handler သို့မဟုတ် globalFilter အတွက် IExpressMiddleware / IExceptionMiddleware ကို implement လုပ်နိုင်ပါသည်။ Class middleware တိုင်းတွင် @MiddlewareMetadata({ plugin: metadata.name }) မဖြစ်မနေ ကြေညာရပါသည် — core က မှန်ကန်သော plugin DI scope တွင် resolve လုပ်ရန်ဖြစ်ပါသည်။ Route ပေါ်တွင် @MyDecorator() သို့မဟုတ် @Middleware(MyClass) ဖြင့် တပ်ဆင်ရပါသည်။

လိုအပ်ပါသည် — IExpressMiddleware / IExceptionMiddleware class တိုင်းတွင် @MiddlewareMetadata({ plugin: metadata.name })
Decorator ပုံစံ — factory မှ Middleware(async (req, res, next) => { … }) ပြန်ပေးရပါသည် (function handler ဖြစ်၍ MiddlewareMetadata မလိုအပ်ပါ)
Class ပုံစံ (IExpressMiddleware) — handler(req, res, next); @Inject သည် @Service() မလိုဘဲ အလုပ်လုပ်ပါသည်
Exception middleware (IExceptionMiddleware) — handler(error, req, res, next)
Middleware ကို တစ်ခုတည်းသော တာဝန်အပေါ် အာရုံစိုက်ထားရပါသည် — လုပ်ငန်းစည်းမျဉ်းများကို ဖြစ်နိုင်လျှင် service တွင် ထားရှိရပါသည်

TSXdecorator middleware

import {
  HttpStatus,
  Middleware,
  ResponseDto,
} from "@quan-erp/shared-backend-core";

export function MyCustomAuth(): MethodDecorator & ClassDecorator {
  return Middleware(async (req, res, next) => {
    if (req.headers["x-custom-header"] === "secret-value") return next();
    return res
      .status(HttpStatus.UNAUTHORIZED)
      .json(ResponseDto.error("Unauthorized", HttpStatus.UNAUTHORIZED));
  });
}

TSXclass middleware

import type { NextFunction, Request, Response } from "express";
import {
  Controller,
  Inject,
  Middleware,
  MiddlewareMetadata,
} from "@quan-erp/shared-backend-core";
import type { IExpressMiddleware } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { MyService } from "./my.service.js";

@MiddlewareMetadata({ plugin: metadata.name })
export class MyComplexMiddleware implements IExpressMiddleware {
  @Inject(MyService)
  private myService: MyService;

  async handler(req: Request, res: Response, next: NextFunction) {
    if (await this.myService.validate(req.body)) return next();
    res.status(400).send("Invalid request");
  }
}

@Middleware(MyComplexMiddleware)
@Controller("/complex")
export class ComplexController {}