用法
可装饰整个控制器类（全部路由）或单个方法。管理端 API 通常先认证再做权限校验。若需要对应用内每个请求生效，请在根 @Module 上使用 globalFilter。
TSXusage
1import {
2 AuditLogMiddleware,
3 AuthenticatedUserOnly,
4 CheckAPIPermission,
5 Controller,
6 Get,
7 ResponseDto,
8} from "@quan-erp/shared-backend-core";
9
10@Controller("/admin-dashboard")
11export class AdminDashboardController {
12 @Get("/stats")
13 @AuthenticatedUserOnly()
14 @CheckAPIPermission()
15 @AuditLogMiddleware((req) => `View stats`)
16 async getStats() {
17 return ResponseDto.ok(data);
18 }
19}内置中间件
- @AuthenticatedUserOnly() — 未认证返回 401；用于需要登录的接口
- @CheckAPIPermission() — 按 method + URL 校验角色允许的 API；管理端需搭配 @AuthenticatedUserOnly
- @AuditLogMiddleware(action) — 静态字符串或 (req) => string，写入审计日志
TSXaudit
1import {
2 AuditLogMiddleware,
3 Controller,
4 Get,
5 Put,
6} from "@quan-erp/shared-backend-core";
7
8@Controller("/branch")
9export class BranchController {
10 @AuditLogMiddleware("View all branches")
11 @Get("/")
12 async getAll() { /* … */ }
13
14 @AuditLogMiddleware((req) => `Update branch ${req.params.id}`)
15 @Put("/:id")
16 async update() { /* … */ }
17}全局中间件（模块）
在根 @Module 上注册过滤器，使其对每个请求生效（而不仅是某个控制器）。请求用 globalFilter，异常用 globalExceptionsFilter。卸载插件时核心会自动注销。
- globalFilter: { position, handler }[] — 应用级请求中间件
- globalExceptionsFilter: handler[] — 应用级异常中间件（IExceptionMiddleware）
- MiddlewarePosition.BEFORE_ROOT_ROUTE — 在插件根路由之前（认证 / 解析用户 / 日志）
- MiddlewarePosition.AFTER_ROOT_ROUTE — 在根栈之后
- Handler — Express RequestHandler，或实现 IExpressMiddleware / IExceptionMiddleware 的类
- 每个类中间件必须：@MiddlewareMetadata({ plugin: metadata.name })
TSXglobalFilter on @Module
1import {
2 MiddlewareMetadata,
3 MiddlewarePosition,
4 Module,
5} from "@quan-erp/shared-backend-core";
6import type {
7 IExceptionMiddleware,
8 IExpressMiddleware,
9} from "@quan-erp/shared-backend-core";
10import type { NextFunction, Request, Response } from "express";
11import metadata from "../../module.metadata.json" with { type: "json" };
12import { MyController } from "./my.controller.js";
13import { MyService } from "./my.service.js";
14
15@MiddlewareMetadata({ plugin: metadata.name })
16export class RequestIdMiddleware implements IExpressMiddleware {
17 handler(req: Request, res: Response, next: NextFunction) {
18 res.setHeader("x-request-plugin", metadata.name);
19 return next();
20 }
21}
22
23@MiddlewareMetadata({ plugin: metadata.name })
24export class PluginErrorFilter implements IExceptionMiddleware {
25 handler(error: Error, req: Request, res: Response, next: NextFunction) {
26 if (res.headersSent) return next(error);
27 res.status(500).json({ message: error.message });
28 }
29}
30
31@Module({
32 name: metadata.name,
33 providers: [MyService],
34 controllers: [MyController],
35 entities: [],
36 globalFilter: [
37 {
38 position: MiddlewarePosition.BEFORE_ROOT_ROUTE,
39 handler: RequestIdMiddleware,
40 },
41 ],
42 globalExceptionsFilter: [PluginErrorFilter],
43})
44export class MyPluginModule {}创建自定义中间件
用 Middleware(...) 封装为控制器/方法装饰器，或实现 IExpressMiddleware / IExceptionMiddleware（也可用于 globalFilter）。每个类中间件必须声明 @MiddlewareMetadata({ plugin: metadata.name })，以便核心在正确的插件 DI 作用域中解析。路由上通过 @MyDecorator() 或 @Middleware(MyClass) 应用。
- 必须：每个实现 IExpressMiddleware / IExceptionMiddleware 的类加 @MiddlewareMetadata({ plugin: metadata.name })
- 装饰器方式 — 工厂返回 Middleware(async (req, res, next) => { … })（函数处理器无需 MiddlewareMetadata）
- 类方式（IExpressMiddleware）— handler(req, res, next)；@Inject 无需 @Service()
- 异常中间件（IExceptionMiddleware）— handler(error, req, res, next)
- 中间件保持精简；业务规则尽量放在 service
TSXdecorator middleware
1import {
2 HttpStatus,
3 Middleware,
4 ResponseDto,
5} from "@quan-erp/shared-backend-core";
6
7export function MyCustomAuth(): MethodDecorator & ClassDecorator {
8 return Middleware(async (req, res, next) => {
9 if (req.headers["x-custom-header"] === "secret-value") return next();
10 return res
11 .status(HttpStatus.UNAUTHORIZED)
12 .json(ResponseDto.error("Unauthorized", HttpStatus.UNAUTHORIZED));
13 });
14}TSXclass middleware
1import type { NextFunction, Request, Response } from "express";
2import {
3 Controller,
4 Inject,
5 Middleware,
6 MiddlewareMetadata,
7} from "@quan-erp/shared-backend-core";
8import type { IExpressMiddleware } from "@quan-erp/shared-backend-core";
9import metadata from "../../module.metadata.json" with { type: "json" };
10import { MyService } from "./my.service.js";
11
12@MiddlewareMetadata({ plugin: metadata.name })
13export class MyComplexMiddleware implements IExpressMiddleware {
14 @Inject(MyService)
15 private myService: MyService;
16
17 async handler(req: Request, res: Response, next: NextFunction) {
18 if (await this.myService.validate(req.body)) return next();
19 res.status(400).send("Invalid request");
20 }
21}
22
23@Middleware(MyComplexMiddleware)
24@Controller("/complex")
25export class ComplexController {}