API 路由
路由注册
使用 registerSecureRoute() 注册路由,自动附加三级安全守卫:
js
import { registerGroupMetadata, registerSecureRoute } from '../../guard.js';
import { getModel } from '../../../framework/persistence/db/index.js';
async function registerUserRoutes(fastify) {
registerSecureRoute(fastify, {
name: 'getUsers',
alias: '获取用户列表',
method: 'GET',
url: '/users',
requireLogin: true,
permission: 'admin:user:read',
handler: async (request, reply) => {
// `app.db` 只在 loader 期可用;请求期取模型用 getModel('User')。
// 业务仓库里更推荐把这行下沉到 DAO(见「应用模块开发」的 DAO / Service 分层)
const users = await getModel('User').findAll({
attributes: ['uid', 'username', 'email', 'status'],
limit: 20
});
return reply.result.success('获取成功', users);
}
});
}
export default registerUserRoutes; // 🔴 export 一律收拢到文件末尾(eslint 强制)配置项
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | - | 路由唯一标识 |
alias | string | - | 显示名称 |
method | string | - | HTTP 方法 |
url | string | - | 路由路径 |
handler | function | - | 处理函数 |
requireLogin | boolean | false | 是否需要登录 |
permission | string/object | null | 权限校验 |
allowRoles | string[] | [] | 角色白名单 |
allowIps | string[] | [] | IP 白名单 |
schema | object | {} | JSON Schema 校验 |
权限配置
js
// 单个权限
permission: 'fw:config:read';
// 任一满足(OR)
permission: {
any: ['fw:block:write', 'fw:admin:*'];
}
// 全部满足(AND)
permission: {
all: ['fw:admin:reset', 'fw:admin:*'];
}自助接口 vs 管理端接口
改「自己的」数据和改「别人的」数据,必须是两个接口。 这不是风格问题:权限码表达的是 「能做什么」,不表达「能对谁做」。同一个 posecraft:user:changename 挂在 PUT /posecraft/v1/profile/:userId 上,等于"凡是有权改自己昵称的人,都能改任何人的昵称"。
边界用三个静态可查的形状钉住(src/__tests__/conventions/user-data-route-boundary.test.js 机器检查,违反即红):
| 规则 | 判据 |
|---|---|
| ① 写他人只走管理端 | URL 带目标用户(/users/:id、/:uid、/:userId)+ 写方法(POST/PUT/PATCH/DELETE) ⇒ 放行权限必须在 ADMIN_PERMISSIONS 命名空间 |
| ② 目标用户只走路径 | 请求体 schema 里不得声明单数 userId / user_id / uid(批量用 userIds 数组) |
| ③ 应用级用户码只能自助 | *_PERMISSIONS.USER.* 这类非 admin 码,只能挂在不带目标用户参数的路由上 |
推荐写法(改自己):
js
registerSecureRoute(fastify, {
name: 'posecraftRenameSelf',
method: 'PUT',
url: '/posecraft/v1/profile', // 不带 :id —— 目标就是登录者本人
requireLogin: true,
schema: {
body: {
type: 'object',
properties: { nickname: { type: 'string', maxLength: 64 } },
additionalProperties: false // 多一个字段就报错,挡住"顺手传个 userId"
}
},
handler: async (request, reply) => {
// 目标用户只能从登录态推导,绝不从 params / body / query 取
const me = await userDao.findByUid(request.state.user.uid, ['id']);
...
}
});改别人则挂在管理端域名下,用 ADMIN_PERMISSIONS.USER.UPDATE 之类的码,并复用 assertCanManageUser(见 app/admin/console/services/access-scope.service.js)做"能不能动这个人"的判定。
唯一允许的例外:写"关系",不写"用户数据"
POST /posecraft/v1/follow/:userId(关注 / 取关)带目标用户参数,但它改的是我和他的关系, 不是他的资料,所以允许。这类例外必须在测试的 ALLOWED_WRITE_ON_OTHER 里逐条写明理由, 并且有"白名单条目必须仍然存在"的反向守卫 —— 删了路由忘删白名单同样会红。
响应格式
js
reply.result.success(message, data); // 200 成功
reply.result.fail(message, data, httpCode, bizCode);
// 签名:fail(message='操作失败', data=null, httpCode=400, bizCode=null)
// 第三参是 **HTTP 状态码**,业务码是第四参(响应里的 code = bizCode ?? httpCode)
reply.result.unauth(message); // 401 未登录
reply.result.forbidden(message); // 403 权限不足响应结构:
json
{
"code": 200,
"message": "操作成功",
"data": { ... },
"timestamp": 1762740000000,
"requestId": "uuid-xxx"
}Schema 校验
js
registerSecureRoute(fastify, {
name: 'createUser',
method: 'POST',
url: '/users',
schema: {
body: {
type: 'object',
required: ['username', 'email'],
properties: {
username: { type: 'string', minLength: 2, maxLength: 50 },
email: { type: 'string', format: 'email' }
}
}
},
handler: async (request, reply) => { ... }
});Group 级配置
js
registerGroupMetadata({
name: 'user',
description: '用户管理',
prefix: '/v1',
requireLogin: true,
allowRoles: ['admin']
});Group 级配置对组内所有路由强制生效,API 级只能在此基础上叠加更严的条件(三级各自独立执行、AND 叠加,requireLogin/allowRoles/allowIps 无法被 API 级关闭)。
WebSocket 路由
js
import { registerSecureWebSocket } from '../../guard.js';
registerSecureWebSocket(fastify, {
url: '/ws/monitor',
requireLogin: true,
allowRoles: ['fw_viewer'],
handler: (connection, req, client) => {
client.on('message', (msg) => { ... });
}
});错误处理
js
registerSecureRoute(fastify, {
handler: async (request, reply) => {
try {
const result = await someService.doSomething();
return reply.result.success('操作成功', result);
} catch (err) {
// 业务错误返回 400
return reply.result.fail(err.message, null, 400);
}
}
});业务错误前缀约定:
js
throw new Error('VERIFY_FAILED:验证码错误');
throw new Error('PARAM_ERROR:邮箱不能为空');
throw new Error('BUSINESS_ERROR:该邮箱已注册');