BF用户角色权限上下文使用说明

INFO

本文前置说明 请先将用户绑定到【角色管理】里，然后通过bff中的角色来判断功能的实现逻辑。本文仅说明 BFF 脚本中如何读取当前登录用户、当前应用角色。

1. 脚本中如何读取

BFF 独立端点脚本统一使用如下函数签名：

export default async function(params, context) {
  // params: HTTP 请求体
  // context: 运行时上下文
}

当前用户和应用角色通过 context 读取：

const FINANCE_APPROVER_ROLE_ID = xxx;

export default async function getCurrentUserRoles(params, context) {
  const userInfo = context.userInfo || {};
  const appRoles = context.appRoles || [];

  // 这里直接用脚本内固定的角色 ID 判断。roleId 对应 app_role_permit.id。
  const roleIds = appRoles
    .map(role => role.roleId)
    .filter(roleId => roleId !== null && roleId !== undefined);

  const hasFinanceApproverRole = roleIds.some(
    roleId => Number(roleId) === FINANCE_APPROVER_ROLE_ID
  );

  return {
    appCode: context.appCode,
    tenantCode: context.tenantCode || null,
    userId: userInfo.userId,
    username: userInfo.username,
    userRole: userInfo.role,
    appRoles,
    roleIds,
    hasFinanceApproverRole
  };
}

2. context 中的相关字段

字段	类型	说明
context.userInfo	object	运行态用户上下文
context.appRoles	array	当前用户在当前 appCode 下启用的应用角色关系
context.tenantCode	string	当前登录用户的租户编码
context.appCode	string	当前 BFF 执行所属应用编码
context.client	object	BFF 数据访问、SQL、事务、扩展等 SDK

3. appRoles 字段结构

context.appRoles 是 List<Map<String, Object>>。

每一项字段如下：

字段	类型	来源	说明
id	number	user_app_relation.id	用户应用关系主键
appCode	string	user_app_relation.app_code	应用编码
userId	number	user_app_relation.user_id	用户 ID
username	string	user_app_relation.username	用户名
status	string	user_app_relation.status	用户在应用中的状态，启用值为 ENABLE
roleType	string	user_app_relation.role_type	角色类型，如ADMIN、DEV、USER、CUSTOM（自定义角色类型均为 CUSTOM）
roleId	number	user_app_relation.role_id	角色配置 ID，关联 app_role_permit.id
roleName	string	app_role_permit.role_name 或默认角色描述	角色名称

示例返回：

[
  {
    "id": 1001,
    "appCode": "demo-app",
    "userId": 12345,
    "username": "zhangsan",
    "status": "ENABLE",
    "roleType": "ADMIN",
    "roleId": 10,
    "roleName": "管理员"
  }
]

4. 权限模型关系

当前项目权限模型是“权限绑定角色，用户绑定角色”：

用户
  -> user_app_relation
  -> roleType / roleId
  -> app_role_permit
  -> permits
  -> PermissionEngine 判断资源动作权限

也就是说：

• user_app_relation 表示用户在某个应用下拥有哪些角色。
• app_role_permit 表示某个角色拥有哪些权限配置。
• app_role_permit.permits 保存角色的完整权限表达式。

如果 BFF 脚本只需要判断当前用户是不是管理员、开发者、普通成员或自定义角色，直接使用 context.appRoles 即可。

5. 常用脚本片段

判断是否拥有指定角色 ID：

function hasRoleId(context, requiredRoleId) {
  const appRoles = context.appRoles || [];
  return appRoles.some(role => Number(role.roleId) === Number(requiredRoleId));
}

判断是否拥有任一指定角色 ID：

function hasAnyRoleId(context, requiredRoleIds) {
  const appRoles = context.appRoles || [];
  const requiredIdSet = new Set((requiredRoleIds || []).map(roleId => Number(roleId)));
  return appRoles.some(role => requiredIdSet.has(Number(role.roleId)));
}

读取当前用户基础信息：

function getCurrentUser(context) {
  const userInfo = context.userInfo || {};
  return {
    userId: userInfo.userId,
    username: userInfo.username,
    nickname: userInfo.nickname,
    tenantCode: context.tenantCode || userInfo.tenantCode || null
  };
}

在 BFF 中做角色保护：

const FINANCE_APPROVER_ROLE_ID = xxx;

export default async function protectedEndpoint(params, context) {
  if (!hasRoleId(context, FINANCE_APPROVER_ROLE_ID)) {
    throw new Error("当前用户无指定角色权限");
  }

  return {
    success: true
  };
}

function hasRoleId(context, requiredRoleId) {
  const appRoles = context.appRoles || [];
  return appRoles.some(role => Number(role.roleId) === Number(requiredRoleId));
}

6. 注意事项

• context.appRoles 只查询当前 appCode 下 ENABLE 状态的角色关系。
• 一个用户在同一个应用下可能有多条角色关系，所以 appRoles 是数组。
• roleType 用于判断系统角色，roleName 更适合展示或判断自定义角色名称。
• 不要把前端传入的用户、角色、权限字段当作可信来源，应以 context.userInfo 和 context.appRoles 为准。