NocoBase Server 的中间件(Middleware)本质上是 Koa 中间件,你可以像在 Koa 一样操作 ctx 对象处理请求和响应。但由于 NocoBase 需要管理不同业务层的逻辑,如果所有中间件都放在一起,会非常难以维护和管理。
为此,NocoBase 将中间件分为 四个层级:
数据源级中间件:app.dataSourceManager.use()
只作用于 某个数据源 的请求,常用于该数据源的数据库连接、字段验证或事务处理等逻辑。
资源级中间件:app.resourceManager.use()
只对已定义的资源(Resource)生效,适合处理资源级逻辑,如数据权限、格式化等。
权限级中间件:app.acl.use()
在权限判断前执行,用于校验用户权限或角色。
应用级中间件:app.use()
对每一次请求都会执行,适合日志记录、通用错误处理、响应处理等。
中间件通常在插件的 load 方法中注册,例如:
中间件执行顺序如下:
acl.use() 添加的权限中间件resourceManager.use() 添加的资源中间件dataSourceManager.use() 添加的数据源中间件app.use() 添加的应用中间件为了更灵活地控制中间件顺序,NocoBase 提供 before、after 和 tag 参数:
示例:
如果未指定位置,新增的中间件默认执行顺序为:
acl.use() -> resourceManager.use() -> dataSourceManager.use() -> app.use()
中间件执行顺序遵循 Koa 的 洋葱圈模型,即先进入中间件栈,最后出栈。
访问不同接口,输出顺序示例:
普通请求:/api/hello
输出:[1,2] (未定义资源,不执行 resourceManager 和 acl 中间件)
资源请求:/api/test:list
输出:[5,3,7,1,2,8,4,6]
中间件按层级和洋葱圈模型执行
before / after / tag 灵活控制执行顺序