第4章 Prisma Composer 入门

Prisma Composer

Prisma Composer 是一个 TypeScript 框架，用于定义由多个服务和资源组成的应用程序，并将其部署到 Prisma Compute 和 Prisma Postgres。

使用 Prisma Composer，你可以用 TypeScript 描述整个应用程序：每个服务及其依赖项，例如其他服务、Prisma Postgres 数据库、定时任务、对象存储和密钥。执行一次部署命令即可在 Prisma Compute 上配置服务，在 Prisma Postgres 上配置数据库，并建立它们之间的认证连接。

Prisma CLI 的 deploy 命令、GitHub 部署动作以及 Deploy Button 都用于部署 Composer 模块。不过，通过 REST API 部署到 Prisma Compute 时不需要使用 Composer：该 API 会为服务创建一个部署，并返回一个用于上传构建产物的 URL，Alchemy 等工具就是采用这种方式进行部署的。有关所有部署路径，请参阅 Deployments。

早期访问

Prisma Composer 目前处于早期访问阶段，API 和命令可能会在版本间发生变化。Composer 作为根级 dev 和 deploy 命令集成在 Prisma CLI 中：执行 npx prisma dev module.ts 和 npx prisma deploy module.ts 来运行。

Composer 应用程序是什么

Composer 应用程序是服务和资源的树状结构。每个服务声明其所需的资源，例如数据库。服务通过类型化契约相互调用。下面逐步说明各部分之间的关系：

Prisma 应用：服务、契约和资源 | 步骤 1/3
Prisma 应用 · store | resources | orders 契约 | catalog 契约 | catalog 契约 | storefront | Next.js 服务 | orders 服务 | catalog 服务 | Prisma Postgres | orders 数据库 | Prisma Postgres | catalog 数据库

应用程序由一个或多个服务组成。每个服务都是一个进程，Composer 为其构建声明：名称、构建方式及依赖项。被其他服务调用的服务会暴露一个契约：即用模式描述其 API。消费者声明对该契约的依赖，并获得一个类型化客户端。TypeScript 会检查每个声明的依赖是否与某个服务暴露的契约相匹配。

资源是服务依赖的非服务实体：Prisma Postgres 数据库、对象存储桶或密钥。每个服务独立声明其资源，因此 orders 和 catalog 服务各自拥有独立的数据库。

最小示例

你以数据形式声明服务，而非编写部署脚本。以下声明表示 storefront 服务调用 catalog 服务的 API，并作为 Next.js 应用构建：

src/storefront/service.ts
import nextjs from '@prisma/composer/nextjs';
import { rpc } from '@prisma/composer/service-rpc';
import { compute } from '@prisma/composer-prisma-cloud';
import { catalogContract } from '../catalog/contract.ts';

export default compute({
  name: 'storefront',
  deps: { catalog: rpc(catalogContract) },
  build: nextjs({ module: import.meta.url, appDir: '..' }),
});

在运行时，服务通过 service.load() 获取每个声明依赖的类型化客户端。契约决定了该客户端暴露的方法及其 TypeScript 类型，调用这些方法就是普通的异步函数调用：

src/storefront/data.ts
import service from './service.ts';

const { catalog } = service.load();
const { products } = await catalog.listProducts({});

根模块将应用程序连接起来，将每个声明的依赖项链接到提供该服务或资源的实体：

module.ts
import { module } from '@prisma/composer';
import catalogModule from './src/catalog/module.ts';
import ordersModule from './src/orders/module.ts';
import storefrontService from './src/storefront/service.ts';

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

TypeScript 会检查连接逻辑：将依赖项绑定到具有不同契约的生产者、缺失 RPC 处理器或配置值形状错误，都会导致编译错误，而不是部署失败。

从声明到部署

npx prisma deploy module.ts 加载根模块，将其与该环境存储的部署状态进行比较，并在 Prisma Compute 上创建或更新服务，在 Prisma Postgres 上创建或更新数据库。重新运行部署只会应用差异：

从声明到运行中的服务 | 步骤 1/3
你编写 | composer deploy 配置 | 注入的环境变量
服务声明 | compute({ name, deps, build })
根模块 | module.ts 连接依赖项
composer deploy | 与存储状态对比
Prisma Compute | 每个服务一个实例
Prisma Postgres | 每个数据库一个实例
service.load() | 运行时的类型化客户端

每个服务都以数据形式声明：其名称、依赖项及构建方式。根模块配置这些服务，并将每个依赖项连接到提供该服务或资源的实体。composer deploy 加载根模块，将声明的应用程序与平台存储的该环境的部署状态进行比较，并在 Prisma Compute 上创建或更新服务，在 Prisma Postgres 上创建或更新数据库。重新运行部署只会应用差异；未更改的资源不会被重新创建。

在运行时，每个服务调用一次 service.load()，接收其依赖项的类型化值：每个契约依赖项对应一个 RPC 客户端，每个数据库对应一个连接。这些值来自 Composer 在部署时写入的环境变量；你的代码无需直接读取 process.env。

核心概念

App：完整的可部署应用程序，由根模块定义。作为单个 Prisma 项目部署。
Service：运行的应用程序组件，通过 compute() 声明。作为单个 Prisma Compute 服务部署。
Resource：服务依赖的非服务实体：Prisma Postgres 数据库、存储桶或密钥。
Contract：服务之间通信的类型化接口，以 Standard Schema 定义编写。
Module：在类型化边界之后配置服务和资源的可重用单元，例如带有独立数据库的服务包。

Apps and Modules 将深入介绍每个概念。

设计原则

两个选择塑造了框架的其余部分。首先，应用程序代码不读取 process.env 或硬编码 URL。依赖项通过 service.load() 以类型化形式传入，因此生产环境、隔离阶段和测试都可以使用不同的注入值运行相同的代码。其次，Composer 不对你的代码进行打包或转换。你使用自己的打包器构建代码，部署过程只需组装你构建的内容。

入门

获取开始指南：在本地构建并运行一个双服务应用程序，然后部署它。移植现有应用程序：保留你的服务器代码，并在其周围添加声明。

使用 AI 编码智能体配合 Composer

Composer 的基于声明的 API 非常适合编码智能体，因为错误会在 TypeScript 编译阶段暴露，而不是在部署阶段。Composer 技能内置在 @prisma/composer 包中，因此始终与你安装的版本匹配。在智能体编写 Composer 代码之前，请先安装该技能：
bunx prisma skills sync

prisma-composer-core-concepts 技能文档记录了完整的编写 API、CLI 命令以及用于定时任务、对象存储和事件流的第一方模块。它是 Prisma 智能体技能之一。像其他 TypeScript 一样审查生成的声明：npx tsc --noEmit 在部署前检查连接逻辑。

接下来阅读什么

先从 Apps and Modules 开始，了解服务、资源和模块如何组合成应用，然后阅读 Services and contracts 以了解它们之间的类型化 RPC。准备好运行代码时，Local development 无需云凭据即可工作，而 Deploying 涵盖生产环境、阶段和 CI。在设计定稿前，请检查 Limitations。

在 GitHub 上编辑 | 核心概念：每个 Composer 声明和命令背后的思想：服务、资源、模块、端口、契约、阶段和部署模型。