在 Next.js 中接入 Grafbase 本地 GraphQL 后端：Type-Safe 数据层完整实战

在 Next.js 中接入 Grafbase 本地 GraphQL 后端Type-Safe 数据层完整实战【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js导读本篇文章以官方仓库 examples/with-grafbase 示例为骨架完整讲解如何将GrafbaseEdge 级 GraphQL 后端接入 Next.js App Router 应用通过 Grafbase CLI 在本地启动 GraphQL 后端、用 GraphQL 变更mutation填充数据、借助 GraphQL Code Generator 在构建期自动生成 TypeScript 类型并在 React Server ComponentRSC中以类型安全的方式执行查询。读完本文你将掌握一套「后端即代码 自动代码生成 RSC 直连」的端到端数据层搭建方法。示例概览这个 Demo 做了什么示例应用是一个极简博客一个侧边栏列出所有Post文章点击进入/posts/[slug]详情页。数据全部来自本地 Grafbase 后端而不是写死在页面里。核心目录结构如下路径职责grafbase/schema.graphqlGrafbase 数据模型定义model指令lib/grafbase.ts封装graphql-request客户端注入 API URL 与密钥app/layout.tsx服务端组件中查询文章列表并渲染侧边栏导航app/posts/[slug]/page.tsx依据动态路由参数slug查询单篇文章详情app/page.tsx首页占位说明codegen.tsGraphQL Code Generator 配置gql/代码生成产物类型定义 graphql()辅助函数.env.local.example环境变量模板应用的 package.json 只依赖少量关键包graphql用于解析查询graphql-requestv5作为运行时 HTTP 客户端graphql-codegen/cli与graphql-codegen/client-preset负责类型生成其余为 Next.js/React/Tailwind 常规依赖。第一步用 create-next-app 拉取示例官方推荐用create-next-app直接引导整个示例无需手工复制文件。三种主流包管理器命令等价npx create-next-app --example with-grafbase with-grafbase-appyarn create next-app --example with-grafbase with-grafbase-apppnpm create next-app --example with-grafbase with-grafbase-app执行后会在当前目录生成with-grafbase-app项目其中已包含上述完整目录结构与依赖声明。第二步配置本地环境变量复制环境变量模板cp .env.local.example .env.local模板 .env.local.example 的内容即默认值开发模式下可以直接沿用GRAFBASE_API_URLhttp://localhost:4000/graphql GRAFBASE_API_KEY两个变量的语义GRAFBASE_API_URLGraphQL 端点地址。Grafbase CLI 默认把本地后端跑在http://localhost:4000/graphql所以模板给出的默认值即可直接使用。GRAFBASE_API_KEY访问后端所需的 API Key。本地开发模式下 Grafbase 不强制鉴权留空即可部署到远端如 Grafbase Cloud 或 Vercel时需要把真实的 Key 注入为环境变量。提示若部署到 Vercel必须在平台侧配置GRAFBASE_API_URL和GRAFBASE_API_KEY两个环境变量否则生产环境将无法访问远端后端。第三步定义并启动本地 Grafbase 后端数据模型schema.graphqlGrafbase 采用「后端即代码」思路数据模型就写在 grafbase/schema.graphql 里type Post model { id: ID! title: String! slug: String! unique comments: [Comment] } type Comment model { id: ID! message: String! post: Post }要点解读model指令把普通 GraphQL 类型标记为数据库模型Grafbase 会基于它自动生成一整套 CRUD 的 Query/Mutation 与关系解析逻辑。Post.comments与Comment.post构成一对多双向关联slug上的unique约束保证文章地址唯一正好对应当前项目里「按 slug 访问详情页」的需求。示例中Post模型最终会自动生成post(by: { slug })、postCollection、postCreate等操作这些能力直接支撑后面页面代码与填充数据所用的 Mutation。启动本地后端启动基于该 schema 的本地 GraphQL 服务npx grafbaselatest dev命令会读取项目中的grafbase/schema.graphql在本地起一个带 GraphQL Playground 的后端默认端口 4000并支持 schema 热更新。示例还在 package.json 中提供了一个「一键双开」脚本backend: npx grafbaselatest dev yarn codegen它同时启动后端和类型监听生成适合日常开发。用 Mutation 填充数据在 GraphQL Playground或任何 GraphQL 客户端中执行下面的变更创建一篇带评论的文章mutation { postCreate( input: { title: I love Next.js! slug: i-love-nextjs comments: [{ create: { message: me too! } }] } ) { post { id slug } } }这里展示了两点能力一是postCreate创建Post记录二是嵌套写入语法——在创建文章的同时通过comments: [{ create: { ... } }]一并创建关联的Comment充分体现 Grafbase 对关系型数据模型的一体化支持。创建成功后即可通过返回的id与slug验证数据落库。第四步构建类型安全的 GraphQL 客户端数据访问层封装lib/grafbase.ts 是贯穿全应用的数据访问入口import { GraphQLClient } from graphql-request; export { gql } from graphql-request; export const grafbase new GraphQLClient( process.env.GRAFBASE_API_URL as string, { headers: { x-api-key: process.env.GRAFBASE_API_KEY as string, }, fetch, }, );值得注意的实现细节客户端通过process.env.GRAFBASE_API_URL/GRAFBASE_API_KEY读取配置因此环境变量文件必须就绪。显式传入fetch让客户端复用平台原生的fetch能力——这对 Next.js Server Component / Route Handler 场景尤其重要可自动继承 Next.js 运行时的缓存与请求调度语义。应用内任何组件只需import { grafbase } from /lib/grafbase即可发起请求。Codegen 配置codegen.ts 定义了 GraphQL Code Generator 的行为import { CodegenConfig } from graphql-codegen/cli; const url process.env.GRAFBASE_API_URL as string; const xApiKey process.env.GRAFBASE_API_KEY as string; const config: CodegenConfig { schema: [ { [url]: { headers: { x-api-key: xApiKey, }, }, }, ], documents: [app/**/*.tsx, app/**/*.ts], ignoreNoDocuments: true, generates: { ./gql/: { preset: client, plugins: [], }, }, }; export default config;配置项逐条说明schema指向运行中的 Grafbase 端点并带上与数据层一致的x-api-key请求头读取同名环境变量。documents扫描范围是app/**/*.tsx与app/**/*.ts即应用源码中所有内联graphql()标签模板里的查询都会被收集。示例的两个查询GetAllPosts、GetPostBySlug正是写在 app/layout.tsx 与 app/posts/[slug]/page.tsx 中的。ignoreNoDocuments: true即使没有匹配到任何查询文档也不会报错。generates配合preset: client来自graphql-codegen/client-preset生成免手写的客户端预设产物输出到 gql/ 目录其中包含gql.ts的类型化graphql()函数与全部查询/返回类型。触发类型生成代码生成命令为npm run codegen对应脚本 package.json 中的codegen: graphql-codegen --watch -r dotenv/config--watch让命令常驻、监听源码里查询的变化并自动重新生成类型-r dotenv/config让 Node 预加载 dotenv从而在启动阶段就正确注入.env.local中的环境变量。开发时保持该进程运行即可「改查询 → 类型即刻同步」。第五步在 Server Component 中读取数据并渲染示例完全基于 App Router 的 Server Component 直连后端无需任何客户端数据请求层。布局中查询文章列表app/layout.tsx 是根布局它在服务端拉取全部文章并构建侧边栏导航const GetAllPostsDocument graphql(/* GraphQL */ query GetAllPosts($first: Int!) { postCollection(first: $first) { edges { node { id title slug } } } } ); export default async function RootLayout({ children }) { const { postCollection } await grafbase.request(GetAllPostsDocument, { first: 50, }); // ...用 postCollection.edges 渲染 Link href{/posts/${edge.node.slug}} }要点graphql()函数来自 codegen 生成的 gql/它对查询字符串做了静态类型绑定——变量$first: Int!和返回字段id/title/slug都会被推导为 TS 类型写错字段名或漏传变量会在编译期直接报错。布局顶部export const revalidate 0;表明该数据层请求不做静态缓存配合grafbase客户端显式传入的fetch每次请求语义清晰可控。详情页按 slug 查询app/posts/[slug]/page.tsx 展示了「动态路由 类型安全查询 兜底 404」的完整写法const GetPostBySlugDocument graphql(/* GraphQL */ query GetPostBySlug($slug: String!) { post(by: { slug: $slug }) { id title slug } } ); export default async function Page({ params }: { params: { slug: string } }) { const { post } await grafbase.request(GetPostBySlugDocument, { slug: params.slug, }); if (!post) { // optionally import notFound from next/navigation return h1404: Not Found/h1; } return ( h1{post.title}/h1 pre{JSON.stringify(post, null, 2)}/pre / ); }这里利用了 Grafbase 为unique字段自动生成的查询参数post(by: { slug: $slug })把路由参数params.slug直接作为 GraphQL 变量传入。当记录不存在时查询返回null页面据此渲染 404 提示代码注释提示可改用next/navigation的notFound()触发标准 404。布局中还有一个指向/posts/not-found的“Show 404 page”链接用于手动验证这一兜底路径。第六步本地运行与验证完成上述配置后按以下顺序启动开发环境保持 Grafbase 后端运行npx grafbaselatest dev如未启动则重新执行运行应用npm run dev打开 http://localhost:3000 即可在侧边栏看到刚才用 mutation 创建的文章I love Next.js!点击进入/posts/i-love-nextjs查看详情——该数据正是从本地 Grafbase 后端实时取回的可选保持npm run codegen监听运行后续修改任何查询后类型会自动重新生成。关键链路一览与延伸阅读从整个示例可以提炼出一条清晰的调用链grafbase/schema.graphql → Grafbase CLI 启动本地后端 ↓ (自动 CRUD API) app/**/*.tsx 内联 graphql() 查询 → graphql-codegen 扫描生成 TS 类型 (gql/) ↓ lib/grafbase.ts 的 GraphQLClient (注入 URL x-api-key fetch) ↓ Server Component 内 await grafbase.request(...) → 直接渲染这套模式的工程价值在于数据模型schema、类型定义codegen 产物与组件消费RSC三者由工具链自动对齐基本消除了「手写类型不同步」这类传统前后端协作痛点。想快速了解 Grafbase 的完整能力可从 schema 中的model、unique与嵌套写入语法入手它们在本例的 grafbase/schema.graphql 中均有落地示范。想进一步理解 GraphQL Code Generator 的clientpreset 与产物结构可对照 codegen 配置 codegen.ts 与生成的 gql/gql.ts 阅读。部署到 Vercel 时请务必在平台环境变量中配置GRAFBASE_API_URL与GRAFBASE_API_KEY并确保后端已指向 Grafbase Cloud 等可被生产环境访问的远端端点。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考