Update acl.md
This commit is contained in:
Pearl C
GitHub
parent
92185ec57c
commit
7affcece55
@ -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> | 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user