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/):
- 您的代码从不读取其环境。 依赖、配置、凭据和端口都通过服务节点类型化地传入。
process.env永远不是答案。 - 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 源码,但其他工具可能不会。
服务节点是唯一的入口
您的运行时代码从它导入的服务声明中接收所有内容:
service.load():依赖(类型化的 RPC 客户端、数据库绑定)。service.input():整个输入作为一个经过模式验证的对象;其中的凭据是经过脱敏处理的SecretString盒子。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') 命名平台变量,从不携带值。
容易出错的规则:
- 机密性通过验证强制执行。 将字面值绑定到期望
SecretString的模式字段会导致部署失败;将envSecret绑定到普通字符串字段的失败方式相同。 envParam值以原始字符串形式到达;将它们绑定到字符串字段。阶段的平台变量是存储位置;部署 shell 仅播种一个缺失的名称(当两者都缺失时部署会提前失败,并命名该变量)。更改平台值需要重新部署。- 缺失由模式决定。 一个与环境绑定的字段,其变量未设置或为空,将解析为键被省略,这仅在模式允许时(可选字段、联合分支)才合法。部署报告会打印序列化的输入文档(机密作为
{"$secret":"VAR"}指针传输)以及每个解析为缺失的键。 - 预留的
port在模式之外。 通过service.port()读取它,永远不要使用process.env。框架也会为 Next.js standalone 模式导出PORT,由它自行绑定。 - 模块可以转发机密需求而无需了解平台名称。 在模块边界声明
secrets: { signingKey: secret() },并将转发的引用作为绑定叶子传递;父模块绑定实际的来源。 input.apiKey.expose()是获取机密值的唯一方式;该盒子在其他任何地方(日志、JSON、错误)都会进行脱敏。
合约和 RPC
合约是服务之间通信的类型化接口。它与其所属的服务一起存在,由任何标准模式验证器进行类型化,提供者(serve(),在编译时详尽覆盖合约的所有方法)和消费者(rpc(contract))都引用相同的值。调用作为 RPC 通过 HTTP 传输。有两种行为是为您预置的,不得重新实现:
- 服务密钥。 在部署时,Composer 为每个消费者→提供者绑定生成一个独特的不可猜测的密钥;
serve()在处理程序运行之前返回401给任何其他请求。您的代码中无需声明它。后果:不要构建自己的服务到服务认证,也不要curl已部署的/rpc/<method>来检查其是否工作。未连接的调用者总是得到401,这看起来像是部署失败,但实际上不是。通过消费者进行调试,或者本地调试,本地不强制执行任何内容。密钥是每个绑定(一个泄漏不能冒充另一个消费者)、服务范围(任何有效密钥都能访问所有方法;拆分服务以单独门控)、只能通过移除绑定或销毁堆栈并重新部署来轮换,并存储在部署拥有的COMPOSER_*变量中,您永远不应手动编辑。 - 幂等性和重试。 每个生成的客户端的调用都带有
Idempotency-Key;丢弃的调用会使用退避策略重试,并且serve()对每个密钥执行一个调用,将已完成的结果重放给迟到的重试。因此,每个方法都可以安全地重试,并且没有合约对此进行声明(没有“这是否幂等”的标志;不要发明一个)。处理程序可以接受可选的第三个参数(input, deps, ctx),并在需要超越单个实例内存的恰好一次语义时读取ctx.idempotencyKey(string | undefined);大多数不需要。在本地和测试中,未预置任何内容,因此serve()会通过所有调用:永远不要在测试输入中提供密钥。
构建是您的责任
您来构建,框架进行组装。对于普通服务器进程,entry 必须指向一个独立的 ESM 文件:除运行时内置模块(bun、bun:*、node:*)外,所有内容都应内联。部署会复制该文件,并且从不发送 node_modules,因此任何未内联的内容会在启动时失败,而不是在部署时。容易出错的规则:
- 一个包中的两个服务意味着两个独立的构建,每个入口一个。单个多入口构建会将共享代码拆分为两个输出都不包含的块。
- 目录构建使用
dir+entry(dir相对于服务模块,entry是dir内的文件;../是错误)。树将被逐字复制,因此服务器必须相对于import.meta.url解析同级文件,而不是相对于工作目录。树必须不包含符号链接:打包程序会拒绝它们、命名该链接,然后组装失败。 - Next.js:使用
output: 'standalone'的next build是完整的构建;nextjs({ module, appDir })命名应用根目录。任何调用load()的页面或操作都需要export const dynamic = 'force-dynamic',因为运行时环境在构建时不存在,并且 Next 会忽略预渲染路由的运行时环境。 - 始终在
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 依赖:
rawPostgres():绑定是{ url },应用拥有其客户端。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/ 下的迁移,并且从不自行创建模式。每次模式更改,包括新数据库的首次模式,都遵循一个循环:
- 编辑
contract.prisma。 prisma contract emit重新生成contract.json+contract.d.ts。prisma migration plan --name <slug>编写迁移(在空图上,这会编写基线)。- 提交
migrations/及更改,然后部署。新数据库从空数据库重放整个路径。
使用该数据库的每个服务仅在其迁移完成后部署:失败的迁移意味着新代码不会部署。旧代码在新部署上线之前会针对新模式提供服务,因此请保持每次迁移与它替换的代码兼容。
如果没有编写的路径达到目标合约,部署(以及针对过时本地数据库的 dev)会拒绝并显示 MIGRATION_PATH_NO
...