Communitygithub.com

Prisma Composer 核心概念

用于部署和管理使用 Prisma Composer (`@prisma/composer`) 的应用:连接其服务和模块、本地运行、测试组合服务,或搭建/拆除环境。触发词包括 "prisma composer"、"@prisma/composer"、"prisma app"、`prisma deploy`、`prisma dev`、`compute()`、`module()`、`contract()`、`service.load()`、`mockService`、`bootstrapService`。

Prisma Composer 核心概念 是什么?

该技能详细介绍了 Prisma Composer 的核心概念与工作流程。Prisma Composer 是一个 TypeScript 框架,用于声明式地组合云应用,通过类型安全的端口连接服务(`compute()`)、资源(如 `rawPostgres()`)和模块(`module()`),并通过 `prisma deploy` 和 `prisma dev` 命令进行部署和本地开发。技能强调两项关键原则:应用代码从不直接读取环境变量(`process.env`),且 Composer 本身不打包或转换代码。它详细解释了通过 `service.load()` 获取依赖、通过 `service.input()` 获取配置输入(区分普通值和机密值 `SecretString`)、以及通过类型化的合约(Contract)实现服务间 RPC 通信的机制。此外,技能还涵盖了构建流程(需开发者自行构建)、数据库与迁移(提供 `rawPostgres()` 和带 Prisma ORM 类型化的 `postgres()`)、测试方法(使用 `mockService`)、以及环境生命周期管理(`destroy` 和 `log` 操作)。该技能主要面向使用 Claude Code、Cursor、Codex 等 AI Agent 来协助开发、部署和管理 Prisma Composer 应用的开发者。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Adrian7373/semantic-video-pipeline/tree/HEAD/packages/database/.agents/skills/prisma-composer-core-concepts

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Prisma Composer 核心概念 是做什么的?

Prisma App 是一个用 TypeScript 组合的、由类型化声明构成的树,并交给 prisma CLI 处理。CLI 提供了两个 Composer 命令:prisma deploy 和 prisma dev。拆除和日志并非命令,而是由脚本调用的 @prisma/composer/control 包的 destroy 和 log 操作。本文档涵盖了结构、层级、关系和工作流程:这些是您无法从代码或 CLI 的帮助输出中观察到的概念。它不是 CLI 参考手册;请通过 prisma <command> --help 发现每个命令的标志,而不是自行推断。Prisma 平台发展迅速,因此请将此文件视为稳定的核心概念,并在 https://www.prisma.io/docs 查找当前更完整的文档。要获取工作代码,请阅读 prisma/composer 仓库中的 examples/ 目录。

以下两条原则统御一切,具有约束力(docs/design/01-principles/):

  1. 您的代码从不读取其环境。 依赖、配置、凭据和端口都通过服务节点类型化地传入。process.env 永远不是答案。
  2. Composer 从不打包或转换您的代码。 您使用自己的打包工具构建;框架通过确定性步骤组装构建输出,并将其交给配置的部署目标。

声明即数据

您编写的所有内容都是声明:描述应用某一部分的纯数据,在导入时不执行任何操作。存在三种节点类型:

类型声明方式用途
服务 (Service)compute()代码的运行单元;原子性,Composer 仅看到其端口
资源 (Resource)rawPostgres(), bucket()有状态的管理依赖
模块 (Module)module()分组边界;自身不运行代码,暴露类型化的端口

节点通过端口连接:deps 声明一个节点所需的内容,expose 声明其提供的内容。连接在模块的构建器中通过 provision() 完成,传递给 CLI 的根模块即为应用:

// module.ts
import { module } from '@prisma/composer';

export default module('store', ({ provision }) => {
  const catalog = provision(catalogModule);
  provision(storefrontService, { deps: { catalog: catalog.rpc } });
});

由于端口是类型化的,编译器会验证每一条连接。连接到错误生产者的依赖、缺少的 RPC 处理程序、形状错误的字面输入值:所有这些都会导致 tsc 失败,而不是部署失败。与环境绑定的输入是例外:这些值只在部署时存在,因此密钥绑定不匹配和缺失的平台变量会在部署时尽早暴露为拒绝(见下文双通道)。先类型检查,然后构建,最后部署;不要通过云端来发现连接是否正确。

Composer 本身与目标无关:@prisma/composer 包含编写、测试和 CLI,不与任何平台耦合。部署目标是在部署配置中注册的扩展;@prisma/composer-prisma-cloud 是 Prisma Cloud 目标,也是本技能部署部分假设使用的目标。其根导出 compute、rawPostgres、bucket、envSecret 和 envParam;ORM 词汇(postgres、dataContract)位于 /orm 子路径下,以及共享的 /cron、/storage、/streams、/auth 和 /email 模块。这些是基础 Prisma Cloud 应用需要的仅有的两个 Composer 包,并且它们不会自动安装:新项目开始时两者都没有,因此首先将两者添加为依赖项。扩展会在它们旁边添加自己的 prisma-composer-* 包。在自行实现功能之前,先组合现有的模块;通过几行代码即可连接一个模块。

在入口图(从 module.ts 可达的所有内容)内,编写带有显式 .ts 扩展名的相对导入(./service.ts,并在 tsconfig 中配置 allowImportingTsExtensions):这种形式在所有地方都能解析。prisma deploy 和 prisma dev 也会将 ./service.js 和无扩展名的 ./service 映射到 .ts 源码,但其他工具可能不会。

服务节点是唯一的入口

您的运行时代码从它导入的服务声明中接收所有内容:

  1. service.load():依赖(类型化的 RPC 客户端、数据库绑定)。
  2. service.input():整个输入作为一个经过模式验证的对象;其中的凭据是经过脱敏处理的 SecretString 盒子。
  3. service.port():要绑定的预留端口(默认为 3000)。

服务声明是纯数据;服务器入口是您构建产生的并由平台启动的内容:

// service.ts
export default compute({
  name: 'auth',
  deps: { db: rawPostgres() },
  build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
  expose: { rpc: authContract },
});

// server.ts
const { db } = service.load(); // { url }: 您自己构建客户端
const handler = serve(service, {
  rpc: { verify: async ({ token }) => ({ ok: token.length > 0 }) },
});
Bun.serve({ port: service.port(), hostname: '0.0.0.0', fetch: handler });

消费者声明 deps: { auth: rpc(authContract) } 并从 load() 获取一个类型化的客户端。

双通道:依赖和输入

值...声明提供读取
由另一个节点产生deps: { db: rawPostgres() }在 provision() 时连接load()
其他任何内容(配置或凭据)input 模式的一个字段在 provision() 时绑定:字面值、envParam() 或 envSecret()input()

服务声明其整个传入配置,普通值和凭据一起,作为一个**标准模式**(arktype 是内定选择)。凭据是类型为 secretString()(来自 @prisma/composer/arktype)的字段;条件合法性(例如“没有账单功能则不应有 stripe 密钥”)是普通的模式联合。provision() 处的绑定反映了模式的形状;envSecret('NAME') 命名平台变量,从不携带值。

容易出错的规则:

  1. 机密性通过验证强制执行。 将字面值绑定到期望 SecretString 的模式字段会导致部署失败;将 envSecret 绑定到普通字符串字段的失败方式相同。
  2. envParam 值以原始字符串形式到达;将它们绑定到字符串字段。阶段的平台变量是存储位置;部署 shell 仅播种一个缺失的名称(当两者都缺失时部署会提前失败,并命名该变量)。更改平台值需要重新部署。
  3. 缺失由模式决定。 一个与环境绑定的字段,其变量未设置或为空,将解析为键被省略,这仅在模式允许时(可选字段、联合分支)才合法。部署报告会打印序列化的输入文档(机密作为 {"$secret":"VAR"} 指针传输)以及每个解析为缺失的键。
  4. 预留的 port 在模式之外。 通过 service.port() 读取它,永远不要使用 process.env。框架也会为 Next.js standalone 模式导出 PORT,由它自行绑定。
  5. 模块可以转发机密需求而无需了解平台名称。 在模块边界声明 secrets: { signingKey: secret() },并将转发的引用作为绑定叶子传递;父模块绑定实际的来源。
  6. input.apiKey.expose() 是获取机密值的唯一方式;该盒子在其他任何地方(日志、JSON、错误)都会进行脱敏。

合约和 RPC

合约是服务之间通信的类型化接口。它与其所属的服务一起存在,由任何标准模式验证器进行类型化,提供者(serve(),在编译时详尽覆盖合约的所有方法)和消费者(rpc(contract))都引用相同的值。调用作为 RPC 通过 HTTP 传输。有两种行为是为您预置的,不得重新实现:

  1. 服务密钥。 在部署时,Composer 为每个消费者→提供者绑定生成一个独特的不可猜测的密钥;serve() 在处理程序运行之前返回 401 给任何其他请求。您的代码中无需声明它。后果:不要构建自己的服务到服务认证,也不要 curl 已部署的 /rpc/<method> 来检查其是否工作。未连接的调用者总是得到 401,这看起来像是部署失败,但实际上不是。通过消费者进行调试,或者本地调试,本地不强制执行任何内容。密钥是每个绑定(一个泄漏不能冒充另一个消费者)、服务范围(任何有效密钥都能访问所有方法;拆分服务以单独门控)、只能通过移除绑定或销毁堆栈并重新部署来轮换,并存储在部署拥有的 COMPOSER_* 变量中,您永远不应手动编辑。
  2. 幂等性和重试。 每个生成的客户端的调用都带有 Idempotency-Key;丢弃的调用会使用退避策略重试,并且 serve() 对每个密钥执行一个调用,将已完成的结果重放给迟到的重试。因此,每个方法都可以安全地重试,并且没有合约对此进行声明(没有“这是否幂等”的标志;不要发明一个)。处理程序可以接受可选的第三个参数 (input, deps, ctx),并在需要超越单个实例内存的恰好一次语义时读取 ctx.idempotencyKey(string | undefined);大多数不需要。在本地和测试中,未预置任何内容,因此 serve() 会通过所有调用:永远不要在测试输入中提供密钥。

构建是您的责任

您来构建,框架进行组装。对于普通服务器进程,entry 必须指向一个独立的 ESM 文件:除运行时内置模块(bun、bun:*、node:*)外,所有内容都应内联。部署会复制该文件,并且从不发送 node_modules,因此任何未内联的内容会在启动时失败,而不是在部署时。容易出错的规则:

  1. 一个包中的两个服务意味着两个独立的构建,每个入口一个。单个多入口构建会将共享代码拆分为两个输出都不包含的块。
  2. 目录构建使用 dir + entry(dir 相对于服务模块,entry 是 dir 内的文件;../ 是错误)。树将被逐字复制,因此服务器必须相对于 import.meta.url 解析同级文件,而不是相对于工作目录。树必须不包含符号链接:打包程序会拒绝它们、命名该链接,然后组装失败。
  3. Next.js:使用 output: 'standalone' 的 next build 是完整的构建;nextjs({ module, appDir }) 命名应用根目录。任何调用 load() 的页面或操作都需要 export const dynamic = 'force-dynamic',因为运行时环境在构建时不存在,并且 Next 会忽略预渲染路由的运行时环境。
  4. 始终在 deploy 或 dev 之前构建。 两者都不会为您构建。

部署配置位于 prisma.config.ts 的 composer 部分,仅此而已。它注册扩展(prismaCloud()、nodeBuild()、nextjsBuild()(当应用具有 Next.js 服务时))和部署状态后端(prismaState()):

// prisma.config.ts
import { defineConfig as composer } from '@prisma/composer/config';
import { nodeBuild } from '@prisma/composer/node/control';
import { prismaCloud, prismaState } from '@prisma/composer-prisma-cloud/control';
import { definePrismaConfig } from 'prisma/config';

export default definePrismaConfig({
  composer: composer({ extensions: [prismaCloud(), nodeBuild()], state: prismaState() }),
});

命令从其运行的目录开始查找 prisma.config.ts,向上遍历到仓库根目录;找到的最近一个声明了 composer 的文件胜出,并且其部分被整体使用,从不逐键合并。只允许 extensions 和 state;任何其他键都是错误。应用代码从不导入此文件。

一个单独的 prisma-composer.config.ts 不再被读取,并且旧的设置被拒绝,绝不会被静默忽略:当加载的 prisma.config.ts 没有声明 composer 部分时,出现 CONFIG.SECTION_MISSING;当该部分仍具有 configPath 时,出现 CONFIG.FIELD_RETIRED;当 prisma-composer.config.* 位于声明它的 prisma.config.ts 旁边时,出现 CONFIG.FILE_RETIRED。所有这三种情况都在 CLI 的 CLI.CONFIG_SECTION_INVALID 下。所有三种情况的修复方法都是将旧文件的 extensions 和 state 移入该部分并删除旧文件。@prisma/composer-cli/family 不再导出 ComposerSection;该部分的类型是 @prisma/composer/config 中的 PrismaAppConfig。

数据库和迁移

两种 Postgres 依赖:

  1. rawPostgres():绑定是 { url },应用拥有其客户端。
  2. postgres(...):一个 Prisma ORM 类型化的数据库。绑定是 { url, client }(ADR-0040):原始连接 URL 加上 Composer 根据您的数据合约构建的类型化客户端,在首次访问时惰性构建,因此查询通过 binding.client 进行,并在编译时检查。postgres 和 dataContract 都从 @prisma/composer-prisma-cloud/orm 导入,而不是从包根目录导入。一个由 dataContract 包装的值(由 prisma contract emit 从 contract.prisma 生成)被依赖端(deps: { db: postgres(catalogData) })和资源端引用,资源端还指定了 prisma.config.ts 路径,以便部署的迁移步骤可以重新加载生成的 contract.json 并找到 migrations/。

部署仅重放:它们应用提交在 migrations/ 下的迁移,并且从不自行创建模式。每次模式更改,包括新数据库的首次模式,都遵循一个循环:

  1. 编辑 contract.prisma。
  2. prisma contract emit 重新生成 contract.json + contract.d.ts。
  3. prisma migration plan --name <slug> 编写迁移(在空图上,这会编写基线)。
  4. 提交 migrations/ 及更改,然后部署。新数据库从空数据库重放整个路径。

使用该数据库的每个服务仅在其迁移完成后部署:失败的迁移意味着新代码不会部署。旧代码在新部署上线之前会针对新模式提供服务,因此请保持每次迁移与它替换的代码兼容。

如果没有编写的路径达到目标合约,部署(以及针对过时本地数据库的 dev)会拒绝并显示 MIGRATION_PATH_NO

...

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能