# ZenStack 技能 ZenStack 是一个 TypeScript 工具包，它通过灵活的授权层 (RBAC/ABAC/PBAC/ReBAC) 和自动生成的类型安全 API 来增强 Prisma ORM。 ## 何时使用 * 在ZModel中定义访问控制策略 * 使用 Prisma/tRPC/Next.js 设置 ZenStack * 实施 RBAC、ABAC 或多租户授权 * 从 ZModel 生成 tRPC 路由器 * 添加字段级验证 ## 快速入门 ### 安装 npm 安装 zenstack @zenstackhq/runtime npx zenstack 初始化 ### 从 ZModel 生成 npx zenstack 生成 ## 访问策略语法 ### 模型级策略模型帖子{ id Int @id @default(自动增量()) 标题字符串已发布布尔值@default(false) 作者用户@relation（字段：[authorId]，参考文献：[id]）作者 ID 整数 // 拒绝匿名访问 @@deny('全部', auth() == null) // 任何人都可以阅读的已发布帖子 @@allow('已读', 已发布) // 作者拥有完全访问权限 @@allow('all', auth().id ==authorId) } ### 运营运营|描述 ---|--- `'全部'` |所有CRUD操作 `'创建'` |仅创建 `'阅读'` |只读 `'更新'` |仅更新 `'删除'` |仅删除 `'创建、读取'` |多种操作 ### 政策规则 * **@@deny 优先于@@allow** * 策略在运行时评估 * `auth()` 返回当前用户或 null ### RBAC 示例模型帖子{ id Int @id @default(自动增量()) 标题字符串 // 只有管理员拥有完全访问权限 @@allow('all', auth().role == 'ADMIN') // 用户可以读取 @@allow('读取', auth().role == '用户') } ### ABAC 示例模型资源{ id Int @id @default(自动增量()) 名称字符串已发布布尔值@default(false) 所有者用户@relation（字段：[ownerId]，引用：[id]）所有者 ID 整数 // 基于声誉的创建 @@allow('创建', auth().reputation >= 100) // 发布的资源是公开的 @@allow('已读', 已发布) // 所有者拥有完全访问权限 @@allow('读取、更新、删除', 所有者 == auth()) } ### 多租户示例模型组织{ id Int @id @default(自动增量()) 名称字符串会员用户[] 帖子帖子[] } 模型帖子{ id Int @id @default(自动增量()) 标题字符串 org 组织@relation（字段：[orgId]，引用：[id]）组织ID 整数 // 只有组织成员可以访问 @@allow('all', org.members?[id == auth().id]) } ## 字段级策略模型用户{ id 整数 @id 电子邮件字符串@allow('读', auth().id == id) 密码 String @deny('read', true) // 永远不可读工资 Int @allow('read', auth().role == 'HR') } ### 字段级属性 * `@allow('read', condition)` — 允许字段读取 * `@allow('update', condition)` — 允许字段更新 * `@deny('read', condition)` — 拒绝字段读取 * `@deny('update', condition)` — 拒绝字段更新 ## 数据验证模型用户{ id 字符串 @id @default(cuid()) 名称字符串@length（最小值：3，最大值：20）电子邮件字符串@email 年龄整数？ @gte(18) 密码字符串@length（最小值：8，最大值：32） url 字符串 @url } ### 验证属性属性 |描述 ---|--- `@电子邮件` |有效的电子邮件格式 `@url` |有效的网址格式 `@length(最小，最大)` |字符串长度 `@gt(n)` / `@gte(n)` |大于（或等于） `@lt(n)` / `@lte(n)` |小于（或等于） `@regex(模式)` |正则表达式匹配 `@startsWith(str)` |字符串前缀 `@endsWith(str)` |字符串后缀 ## tRPC 集成 ### 插件配置插件 trpc { 提供商 = '@zenstackhq/trpc' 输出='src/服务器/路由器/生成' } ### 上下文设置从“@zenstackhq/runtime”导入{增强}；从'./db'导入{prisma}；从 './auth' 导入 { getSession }；导出 const createContext = async ({ req, res }) => { const session =等待 getSession(req, res); 返回{ 会议， // 具有访问策略的增强型 Prisma 客户端 prisma: 增强(prisma, { 用户: 会话?.user }), }; }; ### 使用生成的路由器从'./trpc'导入{createTRPCRouter}；从 './routers/ generated/routers' 导入 { createRouter } ；导出常量 appRouter = createTRPCRouter({ ...createRouter(createTRPCRouter, 过程), }); ## 增强的 Prisma 客户端从 '@prisma/client' 导入 { PrismaClient }；从“@zenstackhq/runtime”导入{增强}； const prisma = new PrismaClient(); // 使用用户上下文创建增强的客户端 const db = 增强(prisma, { 用户: currentUser }); // 现在所有查询都遵循访问策略 const posts =等待db.post.findMany(); // 只返回允许的帖子 ## 常见模式 ### 带策略的软删除模型帖子{ id 整数 @id 已删除布尔值@default(false) 删除于日期时间？ // 隐藏软删除的帖子 @@deny('已读', 已删除) // 允许所有者“删除”（软删除） @@allow('update', auth().id ==authorId && future().deleted) } ### 基于时间的访问模型内容{ id 整数 @id 发布时间？ // 只显示已发布的内容 @@allow('读',publishAt!= null &&publishedAt <= now()) } ### 分层访问模型文件{ id 整数 @id 父文档？ @relation("children"，字段：[parentId]，引用：[id]) 父 ID 整数？儿童文档[]@relation(“儿童”) // 如果用户可以访问父级则访问 @@allow('read',parent == null ||parent.canRead(auth())) } ## CLI 命令 # 在项目中初始化ZenStack npx zenstack 初始化 # 生成 Prisma 架构和工件 npx zenstack 生成 # 格式化 ZModel 文件 npx zenstack 格式 ## 示例 ### 示例：将 RBAC 添加到现有模型 **输入：** 将基于角色的访问控制添加到我的 Post 模型 **输出：** 模型帖子{ id Int @id @default(自动增量()) 标题字符串已发布布尔值@default(false) 作者用户@relation（字段：[authorId]，参考文献：[id]）作者 ID 整数 // 拒绝匿名访问 @@deny('全部', auth() == null) // 管理员拥有完全访问权限 @@allow('all', auth().role == 'ADMIN') // 作者可以管理自己的帖子 @@allow('all', auth().id ==authorId) // 任何人都可以阅读已发布的帖子 @@allow('已读', 已发布) } ### 示例：多租户数据隔离 **输入：** 在 SaaS 应用程序中按组织隔离数据 **输出：** 模型组织{ id 整数 @id 会员用户[] 帖子帖子[] } 模型帖子{ id 整数 @id org 组织@relation（字段：[orgId]，引用：[id]）组织ID 整数 // 只有组织成员才能访问帖子 @@allow('all', org.members?[id == auth().id]) } ### 示例：软删除模式 **输入：** 实现软删除，自动隐藏已删除的记录 **输出：** 模型帖子{ id 整数 @id 已删除布尔值@default(false) 删除于日期时间？作者 ID 整数 // 在普通查询中隐藏软删除 @@deny('已读', 已删除) // 允许“删除”=设置删除标志 @@allow('update', auth().id ==authorId && future().deleted) } ### 示例：v3 迁移脚本 **输入：** 更新 ZenStack v3 的 package.json **输出：** { “脚本”：{ “生成”：“禅宗生成”， "db:push": "zen db 推送", "migrate:dev": "zen 迁移开发", "migrate:deploy": "zen 迁移部署" } } ## 提示 ### 提示 1：默认拒绝模式开始严格，然后开放：模型秘密{ id 整数 @id 值字符串 // 从拒绝所有开始 @@deny('全部', true) // 然后将特定访问列入白名单 @@allow('read', auth().role == 'ADMIN') } ### 技巧 2：使用 check() 调试策略在不访问数据库的情况下测试权限：从“@zenstackhq/runtime”导入{检查}； const canCreate =等待检查(db).post.create({ 数据：{标题：'测试'} }); // 返回：{ allowed: true/false, Reason?: string } ### 技巧 3：使用 future() 进行更新验证验证更新结果：模型用户{ id 整数 @id 角色字符串工资整数 // 不能给自己加薪 > 10% @@allow('更新', future().薪水 <= 薪水 * 1.1) } ### 技巧 4：字段级敏感数据对未经授权的用户隐藏敏感字段：模型用户{ id 整数 @id email String @allow('read', auth().id == id || auth().role == 'ADMIN') password String @deny('read', true) // 永远无法通过 API 读取 ssn String @allow('read', auth().role == 'HR') } ### 技巧 5：v3 — 使用 Kysely 进行复杂查询当 Prisma API 不够用时： // 使用窗口函数进行复杂聚合常量结果 = 等待 db.$qb .selectFrom('订单') .选择([ '用户ID', sql`SUM(amount) OVER (PARTITION BY userId)`.as('totalSpent'), sql`ROW_NUMBER() OVER (ORDER BY amount DESC)`.as('rank') ]） .execute(); ## 最佳实践 1. **默认拒绝** — 以 `@@deny('all', true)` 开头，然后添加特定允许 2. **一致地使用 auth()** — 始终检查 null：`auth() != null` 3. **在架构级别验证** - 使用验证属性而不是应用程序代码 4. **测试策略** — 为访问控制规则编写测试 5. **保持策略简单**——复杂的逻辑应该在辅助函数中 6. **新项目首选 v3** — 占用空间更小，功能更多 7. **使用 check() 进行 UI** — 根据权限显示/隐藏按钮 ## 与更好的身份验证集成 // 验证.ts 从 'better-auth' 导入 { betterAuth }；从 'better-auth/adapters/prisma' 导入 { prismaAdapter }；从'./db'导入{prisma}；导出 const auth = betterAuth({ 数据库：prismaAdapter(prisma, { 提供商: 'postgresql' }), }); // context.ts - 与 ZenStack 结合从“@zenstackhq/runtime”导入{增强}；导出 const createContext = async ({ req }) => { const session = wait auth.api.getSession({ headers: req.headers }); 返回{ prisma: 增强(prisma, { 用户: 会话?.user }), }; }; ## ZenStack v3（基于 Kysely） ZenStack v3 是**完全重写** — 使用基于 [Kysely]() 构建的自己的引擎替换了 Prisma ORM。 ### 为什么是 v3？方面| v2（基于 Prisma）| v3（基于 Kysely） ---|---|--- ORM 引擎 | Prisma 运行时 |基于 Kysely 的定制节点模块 | ~224 MB（Prisma 7）| 〜33MB 建筑| Rust/WASM 二进制文件 | 100% 打字稿查询API |仅限 Prisma API |双：Prisma + Kysely 可扩展性|有限公司|运行时插件 JSON 字段 |通用对象 |强类型传承|不支持 |多态`@@delegate` ### v3 双 API 设计 // 高级 ORM（Prisma 兼容）等待 db.user.findMany({ 其中：{ 年龄：{ gt：18 } }，包括：{帖子：true} }); // 低级 Kysely 查询构建器（用于复杂查询）等待 db.$qb .selectFrom('用户') .leftJoin('Post', 'Post.authorId', 'User.id') .select(['用户.id', '用户.电子邮件', '帖子.标题']) .where('用户.年龄', '>', 18) .execute(); ### v3 强类型 JSON 输入地址{ 街道字符串城市字符串拉链字符串 } 模型用户{ id 整数 @id 地址地址 // JSON 列的完整类型安全 } ### v3 多态模型模型资产{ id 整数 @id 名称字符串 @@委托（类型） } 模型图像扩展资产{ 宽度整数高度整数 } 模型视频扩展了资产{ 持续时间 Int } // 查询返回可区分联合 const 资产 = 等待 db.asset.findMany(); // asset[0].type === 'Image' → 有宽度、高度 // asset[0].type === 'Video' → 有持续时间 ### v3 计算字段模型用户{ 名字字符串姓氏字符串全名字符串@compated } const db = new ZenStackClient(架构, { 计算字段：{ 用户：{ // SQL: CONCAT(名字, ' ', 姓氏) fullName: (eb) => eb.fn('concat', ['firstName', eb.val(' '), 'lastName']) }, }, }); ### v3 运行时插件 // 按年龄过滤所有用户查询的插件 const extDb = db.$use({ id: '仅限成人', 查询：{ 用户：{ 异步 findMany({ args, 继续 }) { args.where = { ...args.where, 年龄: { gt: 18 } }; 返回继续（参数）； }, }, }, }); ## 迁移指南 ### 从 Prisma 到 ZenStack # 在现有 Prisma 项目中初始化 ZenStack npx zenstack@最新 init # 使用自定义 Prisma 架构位置 npx zenstack@latest init --prisma prisma/my.schema # 使用特定的包管理器 npx zenstack@latest init --package-manager pnpm 更新 package.json 脚本： { “脚本”：{ "db:push": "zen db 推送", "migrate:dev": "zen 迁移开发", "migrate:deploy": "zen 迁移部署" } } ### 从 ZenStack v2 到 v3 1.用ZenStack替换Prisma依赖 2.更新PrismaClient创建代码 3. 请参阅[v2 迁移指南]() 4. 请参阅[Prisma 迁移指南]() ## 资源 * [ZenStack 文档]() * [GitHub]() * [ZModel 参考]() * [tRPC 插件]() * [从 Prisma 迁移]() * [从 v2 迁移]()

禅斯塔克

包含技能