不知道你们有没有遇到过这种场景:数据库表结构已经定好了,前端要的数据其实就是两三张表联查,但后端还是得老老实实写接口、写字段映射、写联调文档。我手上大部分项目都用 PostgreSQL(后面统一叫 PG)当存储,之前也按老套路在 Node 层用 Apollo Server 包一层 GraphQL。后来试了一把这几年社区里很火的思路——让 PG 自己把表结构、视图、函数编译成 GraphQL schema,直接对外提供接口,瞬间觉得少写了一半代码。
这篇文章我会围绕 PG GraphQL 展开,先讲清楚它到底解决了什么问题,再把 PostGraphile、pg_graphql、Hasura 这几条主流路线的原理和取舍讲明白,然后带大家从零跑起来一个真实可用的接口服务。适合谁看?如果你正在用 PG,又不想为普通 CRUD 手写一堆 resolver;或者前端天天催接口、后端在重复劳动里挣扎,那这篇内容应该能给你一个立竿见影的解法。
1. 为什么需要 PG GraphQL:少写一层接口皮的甜头
1.1 传统开发里 GraphQL 服务层是怎么来的
过去我们做 GraphQL 项目,流程基本是这样的:前端先提出要哪些字段,后端在应用层定义 GraphQL schema,然后写 resolver,每个 resolver 里再通过 ORM 或者手写 SQL 去 PG 里取数。一个简单的文章列表接口,要写 query 定义、要写 type、要写 resolver、要处理关联查询,数据模型一变,schema 又要跟着改。
这套流程最大的问题不是代码量,而是 schema 双份维护。数据库一份表结构,应用层一份 GraphQL 类型,两者之间没有自动同步机制。今天 DBA 在 PG 里加了一个字段,应用层忘改,前端就永远查不到。时间一长,接口层定义和真实数据结构越来越漂移,排查起问题来非常痛苦。
另一个痛点是关系解析。文章表关联用户表、评论表关联文章表,如果用 TypeORM 或者 Prisma,多少要配一些 relation 映射。如果是手写 resolver,那就得小心处理 N+1 查询,查询一条文章列表可能打出去几十条 SQL,数据库压力直接上去。
1.2 PG GraphQL 的核心价值:数据库 schema 即 API schema
PG GraphQL 这类方案做了一件很本质的事情:把 PG 的元数据当作 GraphQL schema 的唯一来源。启动服务时,它直接连接数据库,读取表、列、主外键、约束、注释,自动生成一套完整的 GraphQL 类型和字段。
这意味着表结构就是接口定义,字段增删改自动同步。你在 PG 里建一张 posts 表,GraphQL 服务里立刻多出一个 allPosts 查询入口;你给 posts 加上外键指向 users,GraphQL 里自动就能查 author { name }。整个过程中,你一行 schema 代码都不用写。
它还顺手解决了几个高频问题:
- 自动处理关联关系,查询嵌套数据不再需要手写 JOIN 和多个 resolver。
- 自动生成过滤、排序、分页参数,前端能按需组合。
- 自动把 PG 的权限体系带进 GraphQL,数据库里有 SELECT 权限才有查询,没有就没有。
- 变更操作可以自动生成,也可以把 PG 函数暴露成 mutation,业务约束放在数据库里,接口层只做透传。
1.3 什么项目适合直接走这条路
我很早之前就说过一句:GraphQL 不是银弹,PG GraphQL 也不是万能药。它最适合的场景,是 数据模型已经比较清晰、以 CRUD 为主、关系明确 的项目。
典型例子包括:后台管理系统、内部工具平台、内容发布系统、IoT 数据上报和查询、简单报表展示。这类项目不需要太复杂的业务编排,大多数接口本质就是“查一张表 + 关联几张表 + 过滤 + 分页”。用 PG GraphQL 方案,半天就能把整套接口交付出去,比手写快太多了。
不适合的场景也要心里有数:如果你的核心是复杂业务编排、多个服务的数据聚合、字段需要大量权限定制和加工,或者你出于安全/架构原因不想暴露底层存储结构,那还是老老实实用传统 GraphQL + resolver 方案,别硬套。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 方案盘点:PostGraphile、pg_graphql、Hasura 与手写 Resolver 的取舍
2.1 三条主流路线的关键差异
我实际用过并调研过不少方案,目前社区里 PG GraphQL 主要就是这几条路线,我把它们的核心差异整理成表格。
| 维度 | PostGraphile | pg_graphql | Hasura | 手写 Resolver |
|---|---|---|---|---|
| 运行形态 | Node.js 独立进程 | PG 扩展(库内) | 独立引擎服务 | 应用内代码 |
| schema 来源 | PG introspection 自动生成 | PG introspection 自动生成 | metadata 配置 + 追踪表 | 手写 schema |
| 自动关系解析 | 是 | 是 | 是 | 否 |
| 自动增删改 | v4 需装插件 / v5 内置 | 支持 | 支持 | 否 |
| 权限模型 | 基于 PG 角色权限 | 基于 PG 角色权限 | 自有细粒度权限系统 | 代码控制 |
| 扩展能力 | 插件生态强,可深度定制 | 弱,功能以官方支持为准 | 强但部署偏重 | 完全自由 |
| 适合场景 | 想要 DBA 直接控制模型,快速交付接口 | 少部署一个服务,接受功能受限 | 需要可视化权限管理、API 运维平台 | 复杂业务与多服务聚合 |
先把几个方案的定位讲清楚,选型才有依据。
PostGraphile 是目前社区最成熟的方案。它是个 Node 服务,连上 PG 后自动生成 GraphQL schema。它最大的特点是 schema 完全跟着数据库走,同时给出了大量 smart comment 约定,DBA 可以在表注释里直接控制暴露名称、排序字段、过滤字段,甚至直接隐藏某些列。插件生态也丰富,可以用 @graphile-contrib/pg-mutators 自动生成增删改,后面我会重点演示它。
pg_graphql 走了一条更极致也更轻的路线:它不是一个独立服务,而是一个 PG 扩展,直接用 Rust 在数据库进程内部解析并执行 GraphQL。好处是真省事,装完扩展直接就能查。但我个人用下来的体感是,它的可定制性和生态成熟度比 PostGraphile 弱一些,版本和功能边界也严格受官方支持范围限制,适合对扩展能力要求不高的场景。
Hasura 其实是更大的盒子。它支持 PG,也支持其他数据库,有自己的权限引擎、metadata 管理、事件触发,甚至可以看成一个 API 管理平台。如果你需要
