Permix项目实例创建与权限管理指南

什么是Permix实例

Permix实例是整个权限管理系统的核心入口点，它负责处理所有权限检查请求。在Permix项目中，每个应用通常只需要一个主实例，这个实例会贯穿整个应用的权限检查流程。

创建Permix实例

要创建一个Permix实例，我们需要使用createPermix函数：

import { createPermix } from 'permix'

const permix = createPermix<{
  post: {
    action: 'create' | 'edit'
  }
}>()

TypeScript类型支持

Permix在设计时就充分考虑了类型安全，通过TypeScript的泛型系统提供了强大的类型检查和自动补全功能。

1. 定义动作类型

在创建实例时，我们需要为每个实体定义可能的操作类型：

const permix = createPermix<{
  post: {
    action: 'create' | 'edit' | 'delete'  // 定义文章实体的操作类型
  },
  user: {
    action: 'view' | 'update'  // 定义用户实体的操作类型
  }
}>()

2. 实体数据类型定义（推荐）

为了获得更好的类型安全，建议为每个实体定义数据类型：

interface Post {
  id: string
  author: string
  content: string
  isPublished: boolean
}

const permix = createPermix<{
  post: {
    dataType: Post  // 指定文章实体的数据类型
    action: 'create' | 'edit'
  }
}>()

这样在编写权限规则时，可以获得完整的类型提示和检查。

3. 分离权限定义

对于大型项目，建议将权限定义与实例创建分离：

import type { PermixDefinition } from 'permix'

// 单独定义权限结构
type AppPermissions = PermixDefinition<{
  post: {
    dataType: Post
    action: 'create' | 'edit' | 'publish'
  }
}>

// 创建实例时使用定义好的类型
const permix = createPermix<AppPermissions>()

JavaScript使用方式

即使不使用TypeScript，Permix也能正常工作：

const permix = createPermix()

permix.setup({
  post: {
    create: true,
    edit: (post) => post.author === currentUser.id
  }
})

初始化权限规则

Permix支持在创建实例时直接初始化权限规则：

const permix = createPermix<{
  post: {
    action: 'create' | 'edit'
  }
}>({
  post: {
    create: true,  // 允许创建文章
    edit: false   // 默认禁止编辑文章
  }
})

这种方式特别适合以下场景：

1. 权限规则在应用启动时就已知
2. 不需要异步加载权限
3. 需要立即进行权限检查

最佳实践建议

1. 始终使用泛型：即使使用JavaScript，也建议添加类型定义以获得更好的开发体验
2. 合理组织权限结构：按业务模块划分权限实体
3. 考虑数据敏感性：对于敏感操作，建议使用函数式权限检查
4. 性能考虑：对于复杂权限逻辑，考虑使用memoization优化

常见问题解答

Q: 为什么我的权限检查没有类型提示？ A: 请确保正确设置了泛型类型，特别是dataType的定义。

Q: 能否动态修改权限结构？ A: Permix的权限结构在创建实例时就固定了，但具体的规则可以通过setup方法动态更新。

Q: 如何处理异步权限检查？ A: Permix本身不直接支持异步权限检查，但可以在规则函数中使用Promise，然后在业务代码中处理异步逻辑。

通过本文的介绍，你应该已经掌握了如何在Permix项目中创建和管理权限实例。合理使用这些功能，可以构建出既安全又易于维护的权限系统。