Blitz-Guard项目中的Ability文件详解：权限控制核心配置

什么是Ability文件

在Blitz-Guard项目中，Ability文件是整个权限系统的核心配置文件，它定义了应用程序中所有资源和操作的访问规则。这个文件相当于您应用的安全策略中心，决定了"谁能在什么条件下对什么资源执行什么操作"。

基本结构解析

让我们先看一个典型的Ability文件示例：

import db, { Prisma } from "db"
import { GuardBuilder } from "@blitz-guard/core"

// 定义扩展的资源类型和操作类型
type ExtendedResourceTypes = "comment" | "article" | Prisma.ModelName
type ExtendedAbilityTypes = "send email"

// 构建Guard实例
const Guard = GuardBuilder<ExtendedResourceTypes, ExtendedAbilityTypes>(
  async (ctx, { can, cannot }) => {
    cannot("manage", "all") // 最佳实践：默认拒绝所有权限

    // 基础权限设置
    can("read", "article")
    can("read", "comment")

    // 登录用户权限
    if (ctx.session.$isAuthorized()) {
      can("create", "article")
      can("create", "comment")
      can("send email", "comment")

      // 带条件的权限
      can("delete", "comment", async (_args) => {
        return (await db.comment.count({ where: { userId: ctx.session.userId } })) === 1
      })
    }
  },
)

export default Guard

关键概念详解

1. 类型扩展

Ability文件首先定义了两种扩展类型：

• ExtendedResourceTypes：扩展的资源类型，可以包含自定义资源（如"comment"、"article"）和Prisma模型
• ExtendedAbilityTypes：扩展的操作类型，默认有create/read/update/delete/manage，可添加自定义操作如"send email"

2. 权限规则声明

使用can和cannot方法声明权限规则：

• can(ability, resource, guard?)：允许某项操作
• cannot(ability, resource, guard?)：禁止某项操作

这两个方法接受三个参数：

1. ability：操作类型（如read/create/update等）
2. resource：资源类型（如article/comment等）
3. guard（可选）：条件函数，返回布尔值决定是否应用该规则

3. 规则评估顺序

权限规则按照从上到下的顺序评估，后面的规则会覆盖前面的规则。例如：

cannot('manage', 'all') // 默认禁止所有
can("create", "article") // 允许创建文章
cannot("create", "article") // 又禁止创建文章（最终效果）

最佳实践指南

1. 默认拒绝原则

安全第一：始终以cannot("manage", "all")开头，明确拒绝所有权限，然后根据需要逐个添加允许的规则。这种方式比默认允许更安全。

cannot("manage", "all") // 先禁止所有

// 然后按需开放权限
can("read", "article")
if (userIsAdmin) {
  can("delete", "article")
}

2. 优化条件判断

将复杂的条件判断提取到规则外部，避免在多个规则中重复执行相同的计算：

// 不推荐 ❌
can("delete", "article", () => heavyCalculation())
can("update", "article", () => heavyCalculation())

// 推荐 ✅
const canModify = await heavyCalculation()
if (canModify) {
  can("delete", "article")
  can("update", "article")
}

3. 使用原因说明

为规则添加原因说明，便于调试和理解权限决策：

can("create", "article").reason("所有登录用户可创建文章")
cannot("delete", "article").reason("仅管理员可删除文章")

// 使用时可以获取原因
const { can, reason } = Guard.can("delete", "article")
console.log(reason) // "仅管理员可删除文章"

高级用法

1. 条件权限

权限可以基于动态条件，这些条件可以访问上下文和传入参数：

can("delete", "comment", async (args) => {
  const comment = await db.comment.findUnique({ where: { id: args.id } })
  return comment.userId === ctx.session.userId
})

2. 批量权限管理

对于相关权限，可以分组管理：

if (userIsEditor) {
  can("create", "article")
  can("update", "article")
  can("publish", "article")
}

3. 结合Prisma模型

当使用Prisma时，可以直接使用模型名称作为资源类型：

type ExtendedResourceTypes = Prisma.ModelName | "customResource"

常见问题解答

Q: 如果没有定义任何规则会怎样？ A: 默认情况下，没有任何规则意味着允许所有操作，这是非常危险的。务必始终以cannot("manage", "all")开头。

Q: 如何测试权限规则？ A: 可以直接调用Guard.can(ability, resource, args)方法测试权限，它会返回{ can: boolean, reason?: string }。

Q: 权限检查会影响性能吗？ A: 合理组织的权限规则对性能影响很小。避免在条件函数中执行重复或繁重的操作，必要时使用缓存。

通过合理配置Ability文件，您可以为应用构建灵活而强大的权限系统。记住遵循最小权限原则，从默认拒绝开始，再谨慎地授予必要权限。