Skip to content

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 强制)

配置项 ​

选项类型默认值说明
namestring-路由唯一标识
aliasstring-显示名称
methodstring-HTTP 方法
urlstring-路由路径
handlerfunction-处理函数
requireLoginbooleanfalse是否需要登录
permissionstring/objectnull权限校验
allowRolesstring[][]角色白名单
allowIpsstring[][]IP 白名单
schemaobject{}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:该邮箱已注册');

基于 GPL-3.0 许可发布