zenstack-migrate-from-v2

从 ZenStack V2 迁移到 V3

ZenStack V3 是一次重大重写：Prisma ORM 引擎被基于 Kysely 构建的 ZenStack 自有引擎取代，同时 ZModel 架构仍基本兼容，查询 API 也仍兼容 PrismaClient。支持的数据库：PostgreSQL、MySQL、SQLite。

由于 V2 基于 Prisma，迁移分为两个部分：通用的 Prisma→ZenStack 变更，以及下面列出的 V2 特有差异。有关常规设置和 CLI，请参阅 zenstack-project-setup。

步骤 1 — 先完成 Prisma 迁移

V2 基于 Prisma，因此请先使用 zenstack-migrate-from-prisma 技能（替换依赖项，将架构移至 zenstack/schema.zmodel，将客户端替换为 ZenStackClient，并更新生成和迁移脚本）。然后应用下面的 V2 特有步骤。

步骤 2 — 重命名 ZenStack 包

npm uninstall zenstack @zenstackhq/runtime
npm install @zenstackhq/schema @zenstackhq/orm
npm install --save-dev @zenstackhq/cli

V2	V3
zenstack（CLI）	@zenstackhq/cli
@zenstackhq/runtime	@zenstackhq/orm
—	@zenstackhq/schema（新增）

CLI 命令从 zenstack <cmd> 变为 zen <cmd>（例如，zen generate）。

步骤 3 — 访问控制现在是一个插件

在 V2 中，访问控制内置于运行时（enhance(prisma)）。在 V3 中，它是一个可选插件。

1. 安装：npm install @zenstackhq/plugin-policy
2. 在架构中声明：

   plugin policy {
       provider = '@zenstackhq/plugin-policy'
   }
   

3. 包装客户端，并在每个请求中绑定用户：

   import { ZenStackClient } from '@zenstackhq/orm';
   import { PolicyPlugin } from '@zenstackhq/plugin-policy';
   
   export const db = new ZenStackClient(schema, { dialect });
   export const authDb = db.$use(new PolicyPlugin());   // was: enhance(prisma, { user })
   // per request:
   const userDb = authDb.$setAuth(user);                // was: passing { user } to enhance()
   

有关完整的策略和运行时模型，请参阅 zenstack-access-control。

步骤 4 — 更新后策略：future() → post-update + before()

在 V2 中，更新后条件通过 update 规则中的 future() 表达。V3 使用专用的 post-update 操作，其中不带修饰的字段引用表示新值，而 before() 读取旧值。

// V2
@@deny('update', future().ownerId != ownerId)

// V3
@@deny('post-update', ownerId != before().ownerId)

步骤 5 — 抽象模型 → 类型 + 混入

V2 的 abstract model + extends 变为通过 with 应用的 type（参见 zenstack-schema-modeling）。

// V2
abstract model Timestamped {
    createdAt DateTime @default(now())
    updatedAt DateTime @updatedAt
}
model Post extends Timestamped { title String }

// V3
type Timestamped {
    createdAt DateTime @default(now())
    updatedAt DateTime @updatedAt
}
model Post with Timestamped { title String }

（注意：V3 中仍存在 extends，但它通过 @@delegate 用于多态，这是另一项功能；不要将其用作普通的混入替代方案。）

步骤 6 — 服务端适配器

V3 要求显式传入 apiHandler（RPCApiHandler 或 RestApiHandler），同时提供客户端的回调函数也从 getPrisma 重命名为 getClient：

// V2
ZenStackMiddleware({ getPrisma: (req) => enhance(prisma, { user: getUser(req) }) });

// V3
ZenStackMiddleware({
    apiHandler: new RPCApiHandler({ schema }),
    getClient: (req) => authDb.$setAuth(getUser(req)),
});

有关所有框架和两种 API 风格，请参阅 zenstack-crud-server。

步骤 7 — 客户端钩子（TanStack Query）

扁平的钩子名称已替换为按客户端分组的钩子，其结构与 ORM 一致：

// V2
import { useFindManyUser } from '~/hooks';
const { data } = useFindManyUser({ where: { ... } });

// V3
import { useClientQueries } from '@zenstackhq/tanstack-query/react';
import { schema } from '~/zenstack/schema';

const client = useClientQueries(schema);
const { data } = client.user.useFindMany({ where: { ... } });

V3 已移除对 SWR 的支持。有关完整的 TanStack Query 设置，请参阅 zenstack-crud-server。

步骤 8 — 其他插件和实用工具迁移

• Zod：现在是实用工具，而非插件（参见 Zod 实用工具文档）。
• OpenAPI：已整合到自动 CRUD API 处理程序中——通过 apiHandler.generateSpec() 生成规范（参见 zenstack-crud-server）。
• 自定义插件：V3 的插件系统已修订；请参阅当前插件文档。

升级后

运行 zen generate，进行类型检查，并运行测试套件或实际应用。确认访问控制行为符合预期；现在需要显式使用 $use(new PolicyPlugin()) + $setAuth() 流程，而非 V2 中隐式的 enhance()。

参考文档

此主题的完整 ZenStack 文档包含在 references/ 下：

• migrate-v2.md — 官方《从 ZenStack v2 迁移》指南