diff --git a/docs/en-US/api/acl/acl.md b/docs/en-US/api/acl/acl.md index bdaa1d968..2cb6b20fa 100644 --- a/docs/en-US/api/acl/acl.md +++ b/docs/en-US/api/acl/acl.md @@ -1,43 +1,42 @@ # ACL -## 概览 +## Overview -ACL 为 Nocobase 中的权限控制模块。在 ACL 中注册角色、资源以及配置相应权限之后,即可对角色进行权限判断。 +ACL is the permission control module in NocoBase. After registering roles and resources in ACL and configuring corresponding permissions, you can authenticate permissions for roles. -### 基本使用 +### Basic Usage ```javascript const { ACL } = require('@nocobase/acl'); const acl = new ACL(); -// 定义一个名称为 member 的角色 +// Define a role named member const memberRole = acl.define({ role: 'member', }); -// 使 member 角色拥有 posts 资源的 list 权限 +// Grant the role of member list permission of the posts resource memberRole.grantAction('posts:list'); acl.can('member', 'posts:list'); // true acl.can('member', 'posts:edit'); // null ``` -### 概念解释 +### Concepts -* 角色 (`ACLRole`):权限判断的对象 -* 资源 (`ACLResource`):在 Nocobase ACL 中,资源通常对应一个数据库表,概念上可类比为 Restful API 中的 Resource。 -* Action:对资源的操作,如 `create`、`read`、`update`、`delete` 等。 -* 策略 (`ACLAvailableStrategy`): 通常每个角色都有自己的权限策略,策略中定义了默认情况下的用户权限。 -* 授权:在 `ACLRole` 实例中调用 `grantAction` 函数,为角色授予 `Action` 的访问权限。 -* 鉴权:在 `ACL` 实例中调用 `can` 函数,函数返回结果既为用户的鉴权结果。 +* Role (`ACLRole`): Object that needs permission authentication. +* Resource (`ACLResource`):In NocoBase ACL, a resource usually corresponds to a database table; it is conceptually analogous to the Resource in Restful API. +* Action: Actions to be taken on resources, such as `create`, `read`, `update`, `delete`, etc. +* Strategy (`ACLAvailableStrategy`): Normally each role has its own permission strategy, which defines the default permissions of the role. +* Grant Action: Call the `grantAction` function in `ACLRole` instance to grant access to `Action` for the role. +* Authentication: Call the `can` function in `ACL` instance, and return the authentication result of the user. - -## 类方法 +## Class Methods ### `constructor()` -构造函数,创建一个 `ACL` 实例。 +To create a `ACL` instance. ```typescript import { ACL } from '@nocobase/database'; @@ -47,12 +46,13 @@ const acl = new ACL(); ### `define()` -定义一个 ACL 角色 +Define a ACL role. + +**Signature** -**签名** * `define(options: DefineOptions): ACLRole` -**类型** +**Type** ```typescript interface DefineOptions { @@ -64,23 +64,22 @@ interface DefineOptions { } ``` -**详细信息** +**Detailed Information** -* `role` - 角色名称 +* `role` - Name of the role ```typescript -// 定义一个名称为 admin 的角色 +// Define a role named admin acl.define({ role: 'admin', }); ``` -* `allowConfigure` - 是否允许配置权限 -* `strategy` - 角色的权限策略 - * 可以为 `string`,为要使用的策略名,表示使用已定义的策略。 - * 可以为 `AvailableStrategyOptions`,为该角色定义一个新的策略,参考[`setAvailableActions()`](#setavailableactions)。 -* `actions` - 定义角色时,可传入角色可访问的 `actions` 对象, - 之后会依次调用 `aclRole.grantAction` 授予资源权限。详见 [`aclRole.grantAction`](./acl-role.md#grantaction) +* `allowConfigure` - Whether to allow permission configuration +* `strategy` - Permission strategy of the role + * It can be a name of strategy in `string`, means to use a strategy that is already defined. + * Or `AvailableStrategyOptions` means to define a new strategy for this role, refer to [`setAvailableActions()`](#setavailableactions). +* `actions` - Pass in the `actions` objects accessible to the role when defining the role, then call `aclRole.grantAction` in turn to grant resource permissions. Refer to [`aclRole.grantAction`](./acl-role.md#grantaction) for details ```typescript acl.define({ @@ -89,7 +88,7 @@ acl.define({ 'posts:edit': {} }, }); -// 等同于 +// Equivalent to const role = acl.define({ role: 'admin', }); @@ -99,50 +98,54 @@ role.grantAction('posts:edit', {}); ### `getRole()` -根据角色名称返回已注册的角色对象 +Get registered role objects by role name. + +**Signature** -**签名** * `getRole(name: string): ACLRole` ### `removeRole()` -根据角色名称移除角色 +Remove role by role name. + +**Signature** -**签名** * `removeRole(name: string)` ### `can()` -鉴权函数 -**签名** +Authentication function. + +**Signature** + * `can(options: CanArgs): CanResult | null` -**类型** +**Type** ```typescript interface CanArgs { - role: string; // 角色名称 - resource: string; // 资源名称 - action: string; //操作名称 + role: string; // Name of the role + resource: string; // Name of the resource + action: string; // Name of the action } interface CanResult { - role: string; // 角色名称 - resource: string; // 资源名称 - action: string; // 操作名称 - params?: any; // 注册权限时传入的参数 + role: string; // Name of the role + resource: string; // Name of the resource + action: string; // Name of the action + params?: any; // Parameters passed in when registering the permission } ``` -**详细信息** +**Detailed Information** -`can` 方法首先会判断角色是否有注册对应的 `Action` 权限,如果没有则会去判断角色的 `strategy` 是否匹配。 -调用返回为`null`时,表示角色无权限,反之返回 `CanResult`对象,表示角色有权限。 +The `can` method first checks if the role has the corresponding `Action` permission registered; if not, it checks if the `strategy` and the role matches. It means that the role has no permissions if it returns `null`; else it returns the `CanResult` object, which means that the role has permissions. + +**Example** -**示例** ```typescript -// 定义角色,注册权限 +// Define role and register permissions acl.define({ role: 'admin', actions: { @@ -174,66 +177,70 @@ acl.can({ action: 'destroy', }); // null ``` + ### `use()` -**签名** +**Signature** + * `use(fn: any)` -向 middlewares 中添加中间件函数。 +Add middleware function into middlewares. ### `middleware()` -返回一个中间件函数,用于在 `@nocobase/server` 中使用。使用此 `middleware` 之后,`@nocobase/server` 在每次请求处理之前都会进行权限判断。 +Return a middleware function to be used in `@nocobase/server`. After using this `middleware`, `@nocobase/server` will perform permission authentication before each request is processed. ### `allow()` -设置资源为可公开访问 +Set the resource as publicly accessible. + +**Signature** -**签名** * `allow(resourceName: string, actionNames: string[] | string, condition?: string | ConditionFunc)` -**类型** +**Type** + ```typescript type ConditionFunc = (ctx: any) => Promise | boolean; ``` -**详细信息** +**Detailed Information** -* resourceName - 资源名称 -* actionNames - 资源动作名 -* condition? - 配置生效条件 - * 传入 `string`,表示使用已定义的条件,注册条件使用 `acl.allowManager.registerCondition` 方法。 +* resourceName - Name of the resource +* actionNames - Name of the resource action +* condition? - Configuration of the validity condition + * Pass in a `string` to use a condition that is already defined; Use the `acl.allowManager.registerCondition` method to register a condition. ```typescript acl.allowManager.registerAllowCondition('superUser', async () => { return ctx.state.user?.id === 1; }); - // 开放 users:list 的权限,条件为 superUser + // Open permissions of the users:list with validity condition superUser acl.allow('users', 'list', 'superUser'); ``` - * 传入 ConditionFunc,可接收 `ctx` 参数,返回 `boolean`,表示是否生效。 + * Pass in ConditionFunc, which can take the `ctx` parameter; return `boolean` that indicate whether it is in effect. ```typescript - // 当用户ID为1时,可以访问 user:list + // user:list accessible to user with ID of 1 acl.allow('users', 'list', (ctx) => { return ctx.state.user?.id === 1; }); ``` -**示例** +**Example** ```typescript -// 注册 users:login 可以被公开访问 +// Register users:login to be publicly accssible acl.allow('users', 'login'); ``` ### `setAvailableActions()` -**签名** +**Signature** * `setAvailableStrategy(name: string, options: AvailableStrategyOptions)` -注册一个可用的权限策略 +Register an available permission strategy. -**类型** +**Type** ```typescript interface AvailableStrategyOptions { @@ -244,10 +251,9 @@ interface AvailableStrategyOptions { } ``` -**详细信息** - -* displayName - 策略名称 -* allowConfigure - 此策略是否拥有 **配置资源** 的权限,设置此项为`true`之后,请求判断在 `ACL` 中注册成为 `configResources` 资源的权限,会返回通过。 -* actions - 策略内的 actions 列表,支持通配符 `*` -* resource - 策略内的 resource 定义,支持通配符 `*` +**Detailed Information*** +* displayName - Name of the strategy +* allowConfigure - Whether this strategy has permission of **resource configuration**; if set to `true`, the permission that requests to register as `configResources` resource in `ACL` will return pass +* actions - List of actions in the strategy, wildcard `*` is supported +* resource - Definition of resource in the strategy, wildcard `*` is supported