nocobase/docs/zh-CN/api/acl/acl.md

ACL

ACL 为权限管理类，系统中的角色与资源都可以在 ACL 中进行注册。

成员变量

availableActions: Map<string, AclAvailableAction>

ACL 内的 AclAvailableAction 名称映射。

availableStrategy: Map<string, ACLAvailableStrategy>

ACL 内的 ACLAvailableStrategy 名称映射。

middlewares

ACL 鉴权中间件。

roles: Map<string, ACLRole>

ACL 内的 ACLRole 名称映射。

actionAlias: Map<string, string>

Action 别名映射。

configResources: Array<string>

配置资源列表。

类方法

constructor()

构造函数，创建一个 ACL 实例。

import { ACL } from '@nocobase/database';

const acl = new ACL();

define(options: DefineOptions)

定义系统角色

DefineOptions 参数

• role - 角色名称

// 定义一个名称为 admin 的角色
acl.define({
  role: 'admin',
});

• allowConfigure - 是否允许配置权限
• strategy - 角色的权限策略
  • 可以为 string，为要使用的策略名，表示使用已定义的策略。
  • 可以为 AvailableStrategyOptions，为该角色定义一个新的策略。
• actions - 定义角色时，可传入角色可访问的 actions 对象， 之后会依次调用 aclRole.grantAction 授予资源权限。详见 ResourceActionsOptions

acl.define({
  role: 'admin',
  actions: {
    'posts:edit': {}
  },
});
// 等同于
const role = acl.define({
  role: 'admin',
});

role.grantAction('posts:edit', {});

getRole(name: string): ACLRole

根据角色名称返回角色对象

removeRole(name: string)

根据角色名称移除角色

can({ role, resource, action }: CanArgs): CanResult | null

鉴权函数，调用返回为null时，表示角色无权限，反之返回CanResult对象，表示角色有权限。

can 方法首先会判断角色是否有注册对应的 Action 权限，如果没有则会去判断角色的 strategy 是否匹配.

CanArgs 参数

• role - 角色名称
• resource - 资源名称
• action - 操作名称

CanResult 参数

• role - 角色名称
• resource - 资源名称
• action - 操作名称
• params - 注册权限时传入的参数

acl.define({
  role: 'admin',
  actions: {
    'posts:edit': {
      fields: ['title', 'content'],
    },
  },
});

const canResult = acl.can({
  role: 'admin',
  resource: 'posts',
  action: 'edit',
});
/**
 * canResult = {
 *   role: 'admin',
 *   resource: 'posts',
 *   action: 'edit',
 *   params: {
 *     fields: ['title', 'content'],
 *   }
 * }
 */

acl.can({
  role: 'admin',
  resource: 'posts',
  action: 'destroy',
}); // null

use(fn: any)

向 middlewares 中添加中间件函数。

middleware()

返回一个中间件函数，用于在 @nocobase/server 中使用。使用此 middleware 之后，@nocobase/server 在每次请求处理之前都会进行权限判断。

setAvailableStrategy(name: string, options: AvailableStrategyOptions)

注册一个可用的权限策略

registerConfigResource(name: string)

将传入的资源名称设置为配置资源。配置资源是指这样的一种资源，这些资源的改动会调用ACL中的角色、权限注册相关方法，例如用户、权限、角色等，这些资源就需要被设置为配置资源。

registerConfigResources(names: string[])

registerConfigResource 的批量方法

isConfigResource(name: string)

判断传入的资源名称是否为配置资源

setAvailableAction(name: string, options: AvailableActionOptions = {})

设置 ACL 中有效的 Action 名称。

参数

• name - action 名称
• options - action 选项
  • displayName - action 显示名称
  • aliases - action 别名
  • resource - action 所属资源名称
  • onNewRecord - action 是否是在创建新的数据库记录
  • allowConfigureFields - action 是否允许配置字段

getAvailableAction(name: string)

获取 ACL 中有效的 Action。

setAvailableStrategy(name: string, options: AvailableStrategyOptions)

设置可用的权限策略，详见 AvailableStrategyOptions

allow(resourceName: string, actionNames: string[] | string, condition?: string | ConditionFunc)

在不指定角色的情况下，开放资源的访问权限。 举例来说，例如登录操作，可以被公开访问：

// 注册 users:login 可以被公开访问
acl.allow('users', 'login');

参数

• resourceName - 资源名称
• actionNames - 资源动作名
• condition? - 配置生效条件
  • 传入 string，表示使用已定义的条件，注册条件使用 acl.allowManager.registerCondition 方法。

    acl.allowManager.registerAllowCondition('superUser', async () => {
      return ctx.state.user?.id === 1;
    });
    
    // 开放 users:list 的权限，条件为 superUser
    acl.allow('users', 'list', 'superUser');
    

  • 传入 ConditionFunc，可接收 ctx 参数，返回 boolean，表示是否生效。

    // 当用户ID为1时，可以访问 user:list 
    acl.allow('users', 'list', (ctx) => {
      return ctx.state.user?.id === 1;
    });