示例工程【免费下载链接】prisma-examples Ready-to-run Prisma example projects项目地址https://gitcode.com/gh_mirrors/pr/prisma-examples点击查看免费下载Prisma Accelerate 是 Prisma 官方提供的数据访问加速层集连接池、全局缓存与区域性读写于一体。本篇文章以 prisma-examples 仓库中的accelerate/nextjs-starter示例项目为主体系统讲解如何在 Next.js 应用中接入 Prisma ORM 与 Accelerate并完整演示 Accelerate 提供的全部缓存策略——TTL、SWR、TTLSWR 组合以及关闭缓存仅使用连接池。读完本文你将掌握 Accelerate 连接串的配置方式、四种缓存策略的参数含义与底层实现、如何通过withAccelerateInfo()观察缓存命中状态与请求耗时并能够直接上手运行这套示例进行实测对比。示例项目概览一个跑满全部缓存策略的 Next.js 应用该项目定位非常纯粹在 Next.js 中展示如何使用 Prisma ORM Prisma Accelerate并逐一演示 Accelerate 中每一种可用的缓存策略参见 README.md 与 API 路由实现。应用的业务场景是一个名人名言Quotes卡片页前端通过四个卡片并行请求同一份数据但分别走TTL、SWR、TTL SWR与无缓存四种模式后端 API 路由解析 URL 查询参数?cacheTTL | SWR | BOTH | NONE将对应的cacheStrategy注入 Prisma 查询页面底部展示每次请求的缓存命中状态Cache Hit / Miss、命中的缓存节点区域Region、缓存最近修改时间以及请求耗时让不同策略的性能差异直观可见。从源码结构看工程分为四层职责清晰层级位置职责页面与组件app/page.tsx、components/Quote/发起四种模式的请求并渲染对比卡片API 路由app/api/route.ts解析缓存策略参数、读写数据库数据访问封装lib/utils/query.ts、lib/db.ts注入cacheStrategy、采集 Accelerate 统计信息数据模型与种子prisma/schema.prisma、prisma/seed.ts定义Quotes表并填充示例数据运行前置条件要成功运行该项目需要准备两样东西一个可公网访问的数据库连接串。Accelerate 是部署在云端的代理层它需要能访问到你的数据库因此本地仅对localhost开放的数据库无法直接使用。Accelerate 连接串内含 Accelerate API Key。在 Prisma Data Platform 账号中为项目开启 Accelerate 即可获得。其中第 2 点是核心Prisma Client 的所有查询都通过这个连接串走 Accelerate 代理而不是直连数据库。快速上手五步跑通示例1. 克隆仓库并安装依赖克隆仓库可使用浅克隆--depth1加速进入示例目录并安装依赖git clone https://gitcode.com/gh_mirrors/pr/prisma-examples.git --depth1 cd prisma-examples/accelerate/nextjs-starter npm install从 package.json 可以看到本示例的技术栈Next.js 15.3.8、React 19、Prisma 7.0.0、prisma/extension-accelerate2.0.2并引入了zod参数校验、react-hot-toast操作反馈与 Tailwind CSS界面样式。2. 配置环境变量在项目根目录创建.env文件touch .env然后写入如下内容# .env # Accelerate connection stringPrisma Client 查询时使用 DATABASE_URL__YOUR_ACCELERATE_CONNECTION_STRING__ NEXT_PUBLIC_URLhttp://localhost:3000其中__YOUR_ACCELERATE_CONNECTION_STRING__是占位符必须替换成你自己的 Accelerate 连接串。NEXT_PUBLIC_URL用于前端组件拼接 API 请求地址见 helpers.ts默认值即为http://localhost:3000。3. 执行迁移并填充种子数据Prisma schema 中只定义了一个Quotes模型。用下面的命令把它映射到数据库、创建对应的Quotes表npx prisma migrate dev --name init此时数据库中已经有一张空的Quotes表。接着运行种子脚本插入示例记录npx prisma db seed种子脚本定义在 prisma/seed.ts通过createMany({ skipDuplicates: true })一次性写入 20 条名人名言skipDuplicates: true保证重复执行不会产生主键冲突。种子命令的注册位置在 prisma.config.tsimport dotenv/config; import { defineConfig, env } from prisma/config; export default defineConfig({ schema: prisma/schema.prisma, migrations: { path: prisma/migrations, seed: tsx ./prisma/seed.ts, // 使用 tsx 直接运行 TS 种子脚本 }, datasource: { url: env(DATABASE_URL), }, });注意这里datasource.url读取的就是.env中的DATABASE_URL因此先配置.env再执行迁移是必要顺序。4. 生成 Prisma Client执行npx prisma generatepackage.json 的build脚本npx prisma generate next build也会在构建前自动完成这一步。5. 启动开发服务器npm run dev打开http://localhost:3000即可看到四张并排的策略对比卡片。TLS 排错提示如果你在向数据库发起POST请求尤其是新增名言时遇到失败可以尝试在开发环境中设置环境变量绕过 TLS 证书校验export NODE_TLS_REJECT_UNAUTHORIZED0。这通常是本地开发证书链不完整时的临时手段生产环境不应使用。环境变量解析Accelerate 连接串的结构与作用README 明确指出Accelerate 连接串具有如下结构prisma://accelerate.prisma-data.net/?api_key__YOUR_ACCELERATE_API_KEY__它包含两个关键部分协议与主机prisma://accelerate.prisma-data.net指向 Accelerate 的全局代理入口查询参数api_key...即你的 Accelerate API Key用于鉴权与计量。Prisma Client 初始化时见 lib/db.ts会把该连接串作为accelerateUrl传入import { PrismaClient } from ../prisma/generated/client; import { withAccelerate } from prisma/extension-accelerate const prismaClientSingleton () { return new PrismaClient({ accelerateUrl: process.env.DATABASE_URL, }).$extends(withAccelerate()) };这里有两处值得注意的实现细节accelerateUrl与数据库直连 URL 是分离的。schema 中datasource只声明了provider postgresql见 schema.prisma并未硬编码数据库地址运行时由DATABASE_URL指向 Accelerate 代理真正的关系型数据库连接串不需要暴露给应用。$extends(withAccelerate())启用扩展能力。正是这个扩展让 Prisma Client 支持cacheStrategy查询参数与withAccelerateInfo()统计方法下面会详细展开。另外lib/db.ts 采用了 Next.js 官方推荐的PrismaClient 单例模式将客户端挂到globalThis上开发环境HMR 频繁重载模块不会反复创建新的连接实例避免连接泄漏。数据模型与数据库初始化模型定义非常精简整个示例只有一张表schema.prismagenerator client { provider prisma-client output ./generated } datasource db { provider postgresql } model Quotes { id Int id default(autoincrement()) quote String createdAt DateTime default(now()) }生成器使用prisma-client新式 provider产物输出到./generated目录源码中的导入路径./generated/client即对应此处数据源为 PostgreSQL表结构为自增主键id、名言文本quote、创建时间createdAt。仓库中已包含该模型的初始化迁移migration.sql可直接对照npx prisma migrate dev --name init生成的 DDLCREATE TABLE Quotes ( id SERIAL NOT NULL, quote TEXT NOT NULL, createdAt TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, CONSTRAINT Quotes_pkey PRIMARY KEY (id) );缓存策略实现源码剖析这是本示例最有教学价值的部分四种缓存策略如何在一条 API 路由中被解析、映射并注入查询。API 路由解析并映射四种缓存策略app/api/route.ts 的GET处理器是核心入口export const runtime edge; // disabling caching export const fetchCache force-no-store; export const revalidate 0; export async function GET(request: Request) { const url new URL(request.url); const searchParams new URLSearchParams(url.search); const parser z.enum([TTL, SWR, BOTH, NONE]); const parsedOutput await parser.safeParseAsync(searchParams.get(cache)); if (!parsedOutput.success) { return new Response(JSON.stringify(Invalid search parameter.), { status: 400, }); } let map new Map(); // TTL缓存 30 秒 map.set(TTL, { ttl: 30 }); // SWR过期后最多再服务 30 秒陈旧数据同时后台重新验证 map.set(SWR, { swr: 30 }); // TTL SWR先按 TTL 缓存 30 秒过期后进入最长 60 秒的 SWR 窗口 map.set(BOTH, { ttl: 30, swr: 60 }); // 关闭缓存仅使用 Accelerate 连接池 map.set(NONE, undefined); const data await getQuotes(map.get(parsedOutput.data)); return new Response(JSON.stringify(data), { headers: { Content-Type: application/json }, status: 200, }); }实现要点路由级缓存关闭runtime edge让路由运行在边缘运行时fetchCache force-no-store与revalidate 0明确告知 Next.js 不参与缓存把缓存决策完全交给 Accelerate避免双层缓存造成观测混乱。参数白名单校验用zod的z.enum配合safeParseAsync限定cache参数只能取TTL、SWR、BOTH、NONE之一非法值返回400。策略映射表将字符串参数映射为 Accelerate 认识的cacheStrategy对象——TTL 30 秒、SWR 30 秒、混合模式{ ttl: 30, swr: 60 }、undefined则意味着完全不做缓存、只用连接池。POST处理器则演示了写路径先请求 quotable.io 取一条随机名言cache: no-cache防止被 HTTP 层缓存再调用addQuote写入数据库返回201与新名言内容。写请求不经过缓存用户可以在 UI 上点击Add new quote制造新数据再对比四种策略卡片对新数据立即可见性的差异。查询封装cacheStrategy 与 withAccelerateInfo真正把策略应用到查询、并采集观测数据的是 lib/utils/query.tsimport prisma from /lib/db; import { CacheStrategy } from /lib/types; export const getQuotes async (strategy?: CacheStrategy) { const start Date.now(); const result await prisma.quotes .findMany({ cacheStrategy: strategy, orderBy: { id: desc }, take: 1, // 每次只取最新一条名言 }) .withAccelerateInfo(); // 附加 Accelerate 执行统计信息 return { data: result?.data?.[0], info: result.info, time: Date.now() - start, // 客户端侧实测耗时 }; }; export const addQuote async (quote: string) { return await prisma.quotes.create({ data: { quote } }); };CacheStrategy的类型定义在 lib/types/index.ts明确限定了合法组合export type CacheStrategy | { ttl: number; swr: number } // TTL SWR | { ttl: number } // 仅 TTL | { swr: number }; // 仅 SWRwithAccelerateInfo()返回的AccelerateInfo结构同样在这里定义export type AccelerateInfo { cacheStatus: ttl | swr | miss | none; // 命中类型 lastModified: Date; // 缓存最近修改时间 region: string; // 命中的缓存节点区域 requestId: string; signature: string; };cacheStatus: ttl表示请求命中 TTL 有效缓存swr表示处于 SWR 窗口内、服务的是稍旧数据已在后台触发重新验证miss表示未命中需要回源none表示未启用缓存、仅走连接池。time字段由应用侧Date.now()差值测得反映的是端到端浏览器 → Next.js → Accelerate → 数据库的完整耗时用于对比各策略的实际性能。客户端单例withAccelerate 扩展再回看 lib/db.ts 的完整逻辑import { PrismaClient } from ../prisma/generated/client; import { withAccelerate } from prisma/extension-accelerate const prismaClientSingleton () { return new PrismaClient({ accelerateUrl: process.env.DATABASE_URL, }).$extends(withAccelerate()) }; declare const globalThis: { prismaGlobal: ReturnTypetypeof prismaClientSingleton; } typeof global; const prisma globalThis.prismaGlobal ?? prismaClientSingleton(); export default prisma; if (process.env.NODE_ENV ! production) globalThis.prismaGlobal prisma;$extends(withAccelerate())是接入 Accelerate 的关键一步扩展会拦截findMany、create等操作把cacheStrategy编码进发往 Accelerate 的请求单例挂在globalThis.prismaGlobal仅在非生产环境写入全局兼顾开发热重载与生产多实例安全。页面侧并行请求四种策略并渲染指标components/Quote/Quotes.tsx 用Promise.all一次性并行发出四个请求const getQuotes async () { const data await Promise.all([ loadData(${HOST}/api?cacheTTL), loadData(${HOST}/api?cacheSWR), loadData(${HOST}/api?cacheBOTH), loadData(${HOST}/api?cacheNONE), ]); return data; };每个请求都带cache: no-cache确保浏览器不介入缓存。渲染组件 Quote.tsx 把AccelerateInfo中的cacheStatus、region、lastModified与result.time展示出来当cacheStatus为swr或ttl时显示绿色并附加CACHE HIT标识否则显示红色命中与否一目了然。页面本身app/page.tsx还声明了export const dynamic force-dynamic注释明确指出如果不加force-dynamicPrisma Client 可能返回陈旧数据——这与路由层的force-no-store共同保证了观测数据的真实性。新增名言后通过router.refresh()触发重新渲染见 AddQuote.tsx此时可观察不同策略对新数据的可见速度TTL 策略在 30 秒窗口内继续返回旧缓存而无缓存策略则立即返回新数据。常见问题TLS 证书校验导致 POST 失败README 特别提示了一个高频问题POST 请求尤其新增名言失败。这通常与本地 TLS 证书链不完整有关。开发环境下的临时解法是export NODE_TLS_REJECT_UNAUTHORIZED0该变量会关闭 Node.js 对 TLS 证书的强校验适合本地调试生产环境应通过正确的证书配置解决而不是关闭校验。小结与进一步探索本文围绕accelerate/nextjs-starter示例完整梳理了从环境准备、数据库初始化到缓存策略实现的整条链路。核心收获有三点接入方式new PrismaClient({ accelerateUrl }).$extends(withAccelerate())即可让查询经由 Accelerate 代理DATABASE_URL存放 Accelerate 连接串而非数据库直连串四种策略{ ttl }、{ swr }、{ ttl, swr }组合以及undefined仅连接池分别对应 TTL 缓存、SWR 缓存、混合缓存与无缓存观测手段withAccelerateInfo()返回cacheStatus、region、lastModified等统计信息配合应用侧耗时测量可以量化每种策略的性能表现。如果想继续深入可以在本仓库中参考加速Accelerate相关示例总览若存在了解其他框架的接入方式compute/nextjs 等目录中基于 Prisma Composer 的进阶工程化用法对照 types/index.ts 与 query.ts尝试把cacheStrategy接入自己的查询路径为读多写少的接口开启全局缓存。动手把.env配好、跑一次迁移与种子再点击Add new quote观察四个卡片的变化你就能直观感受到 Prisma Accelerate 缓存策略的设计意图与实际效果。赞分享示例工程【免费下载链接】prisma-examples Ready-to-run Prisma example projects项目地址https://gitcode.com/gh_mirrors/pr/prisma-examples点击查看免费下载相关推荐SolidStart 实战用 Prisma Accelerate 在 SolidStart 应用中对比四种缓存策略SolidStart 实战用 Prisma Accelerate 在 SolidStart 应用中对比四种缓存策略 本篇技术指南基于 accelerate/s示例工程MediaGo 前端实践用显式条件渲染杜绝 0 与 NaN 泄漏进 JSXMediaGo 前端实践用显式条件渲染杜绝 0 与 NaN 泄漏进 JSX 导读 在 React / TSX 组件开发中 {count span {示例工程Prisma Accelerate 深度应用连接池与全局缓存优化Prisma Accelerate 深度应用连接池与全局缓存优化 本文深入探讨了Prisma Accelerate的核心功能包括连接池配置与管理、全局缓存策示例工程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考