第45章 为 NodeBB 插件添加路由
添加路由
除了钩住现有页面,插件还可以注册自己的路由:包括通过模板渲染的 HTML 页面,以及供客户端脚本调用的 JSON REST API 端点。NodeBB 提供了一组基础的路由辅助函数(route helpers),确保你的路由能继承核心使用的中间件、CSRF 保护和响应格式化。
```javascript const routeHelpers = require.main.require('./src/routes/helpers'); ```
页面路由
页面路由通过挂载在 `static:app.load` 钩子上的方法来注册。钩子的载荷(payload)暴露了应用程序路由器和中间件对象。
plugin.json ```json { "hook": "static:app.load", "method": "init" } ```
library.js ```javascript plugin.init = async ({ router, middleware }) => { // 公开面向用户的论坛页面,从 templates/myplugin/page.tpl 渲染 routeHelpers.setupPageRoute(router, '/myplugin/page', [middleware.ensureLoggedIn], (req, res) => { res.render('myplugin/page', { title: '[[myplugin:page.title]]' }); });
// 管理员控制面板(ACP)页面,从 templates/admin/plugins/myplugin.tpl 渲染 routeHelpers.setupAdminPageRoute(router, '/admin/plugins/myplugin', (req, res) => { res.render('admin/plugins/myplugin', { title: 'My Plugin' }); }); }; ```
* `setupPageRoute(router, path, middlewares, controller)` 用于挂载论坛页面。`middlewares` 数组是可选的;常见条目包括 `middleware.ensureLoggedIn` 和 `middleware.admin.buildHeader`。 * `setupAdminPageRoute(router, path, controller)` 用于挂载 ACP 页面。由于系统会自动构建管理员页头,因此不需要提供中间件数组。
若要在管理侧边栏中添加指向你的 ACP 页面的链接,请监听 `filter:admin.header.build`:
```javascript plugin.addAdminNavigation = (header) => { header.plugins.push({ route: '/plugins/myplugin', icon: 'fa-cog', name: 'My Plugin' }); return header; }; ```
REST API 路由
API 路由通过挂载在 `static:api.routes` 钩子上的方法来注册。载荷暴露了 `{ router, middleware, helpers }`。
plugin.json ```json { "hook": "static:api.routes", "method": "addRoutes" } ```
library.js ```javascript plugin.addRoutes = async ({ router, middleware, helpers }) => { routeHelpers.setupApiRoute(router, 'get', '/myplugin/:id', [middleware.ensureLoggedIn], async (req, res) => { const data = await getThing(req.params.id); helpers.formatApiResponse(200, res, { data }); });
routeHelpers.setupApiRoute(router, 'post', '/myplugin/:id', [middleware.ensureLoggedIn], async (req, res) => { if (!req.body.content) { return helpers.formatApiResponse(400, res, new Error('[[error:invalid-data]]')); } const thing = await createThing(req.params.id, req.body.content); helpers.formatApiResponse(200, res, { thing }); }); }; ```
`setupApiRoute(router, method, path, middlewares, controller)` 注册一条路由,其中 `method` 可以是 `get`、`post`、`put` 或 `delete`。
API 路由的公共 URL
这是最容易被误解的细节。`static:api.routes` 中提供的路由器挂载在 `/api/v3/plugins` 之下。因此,你注册的 `/myplugin/:id` 路由实际访问地址为:
`/api/v3/plugins/myplugin/:id`
你注册的相对路径是基于 `/api/v3/plugins`(即从你自己的路由段开始),而不是基于站点根目录。
从客户端脚本调用路由
使用 `api` 客户端库。其 `get`/`post`/`put`/`del` 方法会自动添加 `/api/v3` 前缀,因此调用路由时应写为 `/plugins/myplugin/:id`:
```javascript require(['api'], function (api) { // GET /api/v3/plugins/myplugin/42 api.get('/plugins/myplugin/42', {}, function (err, data) { /* ... */ });
// POST /api/v3/plugins/myplugin/42 api.post('/plugins/myplugin/42', { content: 'hello' }, function (err, data) { /* ... */ });
// DELETE 对应 api.del(...) api.del('/plugins/myplugin/42', {}, function (err) { /* ... */ }); }); ```
简而言之:服务端路由 `/myplugin/:id` 对应客户端调用 `/plugins/myplugin/:id`。
格式化响应
务必通过 `helpers.formatApiResponse`(来自 `require.main.require('./src/controllers/helpers')`,同时也作为钩子参数传入)来返回响应。它会发出 NodeBB 客户端期望的信封格式(envelope),并统一处理错误。传入一个 message 为翻译键的 `Error` 对象即可返回失败状态:
```javascript helpers.formatApiResponse(200, res, { ok: true }); helpers.formatApiResponse(400, res, new Error('[[error:invalid-data]]')); helpers.formatApiResponse(403, res, new Error('[[error:no-privileges]]')); ```
路由顺序
路由按注册顺序进行匹配,因此请优先注册特定路径和静态路径,最后再注册带参数的路由。否则,参数路由会捕获本应指向更具体路径的请求:
```javascript // 正确:先注册特定和静态路由… routeHelpers.setupApiRoute(router, 'get', '/myplugin/:id/children', mw, childrenHandler); routeHelpers.setupApiRoute(router, 'get', '/myplugin/search', mw, searchHandler); // …最后注册参数化路由 routeHelpers.setupApiRoute(router, 'get', '/myplugin/:id', mw, getHandler); ```
如果先注册了 `/myplugin/:id`,那么对 `/myplugin/search` 的请求就会被匹配到该路由,且 `id` 参数值为 `"search"`。
使用自定义中间件保护路由
`middlewares` 接受任何 Express 风格的中间件,包括你自定义的异步函数。一种常见模式是设置授权门禁,当访问被拒绝时通过 `formatApiResponse` 返回响应:
```javascript const ensurePrivileged = async (req, res, next) => { if (!(await canAccess(req.uid))) { return helpers.formatApiResponse(403, res, new Error('[[error:no-privileges]]')); } next(); };
routeHelpers.setupApiRoute(router, 'post', '/myplugin/:id', [middleware.ensureLoggedIn, ensurePrivileged], handler); ```
返回文件而非 JSON
如果你需要通过路由流式传输文件(例如用于受访问控制的下载),而不是通过静态目录公开,请像上述那样挂载控制器,并在执行完自定义验证后使用 `res.sendFile`。