后端API网关【免费下载链接】crystal Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!项目地址https://gitcode.com/gh_mirrors/cry/crystal点击查看免费下载本指南以 PostGraphile V5 官方文档Introduction为核心系统讲解其设计理念、核心能力与上手路径。你将了解 PostGraphile 如何借助 Gra*fast* 引擎、插件系统与 smart tags 把 PostgreSQL 数据库自动转换为高可定制、可导出的 GraphQL API并通过 CLI 或库模式在数分钟内完成从数据库到 API 的搭建。为什么选择 PostgreSQL GraphQL 的组合PostgreSQL 的价值在于强类型、定义良好的 schema而 GraphQL 恰好是让这一数据层为前端开发者乃至 API 客户端所用的理想接口技术。PostGraphile 正是二者之间的桥梁它利用自动化和智能默认值消除构建一个遵循最佳实践的 GraphQL API 过程中最耗时、最重复的部分同时保留充分的定制与扩展能力。其底层运行在 Gra*fast* 引擎之上见仓库中的 grafast 包PostGraphile 的依赖声明可查 package.json这使得传统 GraphQL/DataLoader 模式构建的 API 在性能上难以与之匹敌——这是它在设计上的核心卖点之一。在介绍具体功能前先明确一个关键理念你的 GraphQL schema 应当反映客户端需求而不是数据库表的 1:1 映射。PostGraphile 不强求数据库长什么样API 就长什么样它提供一整套工具让你在消除常规部分重复工作的同时把资源塑造成前端真正需要的形态。核心理念自动化与可塑性的平衡PostGraphile 的价值主张建立在三条支柱上自动化自动反射数据库中的权限只暴露被授权的表、列、函数与变更操作mutation。可塑性通过 smart tags、schema 扩展、插件接口等手段精细雕琢生成的 schema——隐藏或暴露表/列/函数、改变命名与呈现方式、声明抽象类型/多态等等。无锁定No Lock-in内置导出功能可将生成的 API 导出为可执行的 JavaScript 代码之后完全由你自己维护。官方文档特别强调建议从一个尽量小的 GraphQL API 开始按需逐步添加功能而不是一开始就走厨房水槽kitchen sink式的全量方案。如果你的公司需要 GraphQL API且数据主要但不完全来自 PostgreSQLPostGraphile 可以帮助你在几天甚至几小时内打造出理想的 GraphQL API节省数周乃至数月的开发时间对于已经启用行级安全Row-Level Security的数据库甚至可能在几分钟内构建出安全、高性能且可扩展的 API。不过文档仍建议花时间打磨你的 API。定制 schema 的四大手段PostGraphile 提供了层层递进的定制方式官方文档将其归纳为以下几个方面1. Smart tags用标签微调生成结果schema 智能标签 与类似技术可以让你精雕细琢 GraphQL schema隐藏或暴露表/列/函数、改变它们的命名或呈现、指示抽象类型/多态或用简单的标签以其他方式操纵生成的 schema。这是逐表、逐列、逐约束级别定制的基础手段。2. Schema 扩展添加任意类型与字段通过 schema extensions你可以添加任何所需的类型、字段与参数这些扩展可以与 Node 本身能够通信的任何数据源交互——不限于 PostgreSQL。3. 插件系统包装 plan resolvers通过 插件接口你可以用自定义逻辑包装plan resolvers从而对授权authorization、呈现presentation、过滤filtering等主题获得巨大控制力。整个 PostGraphile 本身就是由插件构成的在源码中Amber 预设presets/amber.ts显式列出了PgTablesPlugin、PgRelationsPlugin、PgMutationCreatePlugin、PgOrderByPrimaryKeyPlugin等一长串插件的编排顺序并继承graphile-build与graphile-build-pg的默认预设这印证了几乎所有特性都是可选的、且多数可按表/列/约束级定制的设计。4. 导出可执行 schema把生成的代码变为自己的通过 exporting-schema你可以查看 PostGraphile 为你生成的 plan resolvers/types/fields并选择把这份代码据为己有——无论是整个 schema 还是其中特定部分。这一能力可以用来让数据库表结构在不破坏 GraphQL schema 的前提下演进也彻底消除了框架锁定。核心特性一览官方文档列出了 PostGraphile 提供的代表性特性完整梳理如下性能与运行时出色的性能——即使是你自定义的逻辑得益于 Gra*fast* 引擎的批量执行与优化大幅降低数据库负载且无需缓存/缓存失效的复杂度纯 TypeScript 编写无二进制模块Serverless 场景下启动非常快自带 PostgreSQL 驱动/适配器可集成几乎任何 Postgres 客户端库GraphQL 功能集完整的 GraphQL 特性包括高级主题多态interfaces 与 unions、实时订阅、stream/defer支持优秀的 Relay 支持通过postgraphile/presets/relay预设全局对象标识、游标分页、变更输入对象与 payload开发体验与集成可集成 Node 生态中任何认证中间件可通过 JS/TS 插件 或 数据库函数 轻松添加字段与变更以 CLI、Node.js 中间件或独立 GraphQL schema 三种方式运行通过 smart tags 轻松定制通过 RuruGra*fast* 增强版 GraphiQL IDE解释你的操作Schema 自动生成自动发现关联关系自动 CRUD 变更如updatePost插件生态丰富的插件带来巨大灵活性聚合Aggregates、强大过滤Filtering、软删除Soft deletion、Upsert、多对多导航Many-to-many navigation、按关联表排序、多租户Multi-tenancy等PostGIS 插件尚未移植到 V5。社区插件可参考 community-plugins。快速上手CLI 一行命令跑起来官方文档给出的最快体验方式是通过 CLI。如果你已安装npxNode.js 自带可以直接运行npx pgl -P pgl/amber -e -c postgres:///mydb其中-P pgl/amber指定使用 Amber 预设pgl命令将其映射到postgraphile/presets/amber-e开启 explain 模式仅建议开发环境使用用于查看每个 GraphQL 操作背后的 plan/SQL 查询-cPostgreSQL 连接字符串请替换为你自己的数据库。如果你的数据不在数据库的publicschema 中可以用-s a,b,c指定逗号分隔的 schema 列表。连接字符串的更多格式包括带密码、SSL 等可参考 usage-cli。pgl 与 postgraphile 命令的区别V5 新增的pgl命令与postgraphile几乎相同它在底层实际上转交给postgraphile仅有两处差异pgl没有peerDependencies——一旦开始安装需要 peerDependencies 的插件建议改用postgraphilepgl将postgraphile/presets/amber暴露为更简洁的pgl/amberpgl/v4、pgl/relay同理。从仓库看pgl包实质上只是一个转发层pgl/src/index.ts 中仅有一行export * from postgraphile印证了defer to postgraphile的实现方式。因此pgl最适合通过npx临时体验要在项目中长期使用应安装postgraphilecd ~/postgraphile npm install postgraphile npx postgraphile -P postgraphile/presets/amber -e -c postgres:///mydbpostgraphile包的exports字段package.json声明了./presets/amber、./presets/v4、./presets/relay、./presets/lazy-jwt、./presets/minify等多个预设子路径以及./adaptors/pg、./grafserv/*等集成入口。CLI 参数详解CLI 接受的配置选项并不多且它会读取当前工作目录下的graphile.config.js文件若存在——把所有选项写进该文件后就可以用极少的 CLI 参数运行。完整参数如下表与 src/cli.ts 中的 yargs 定义一一对应参数别名等价配置说明--preset string-P{ extends: [...] }逗号分隔的预设列表追加到配置中--allow-explain-e{ grafast: { explain: true } }开启 explain 模式生产环境不应使用--connection string-c{ pgServices: [makePgService({ connectionString: ... })] }PostgreSQL 连接字符串省略时从环境变量推断。示例db、postgres:///db、postgres://user:passworddomain:port/db?ssltrue--superuser-connection string-S{ pgServices: [makePgService({ superuserConnectionString: ... })] }用于安装 watch fixtures 的超级用户连接字符串配合--watch省略时使用普通连接--schema string-s{ pgServices: [makePgService({ schemas: [...] })] }逗号分隔的待反射 PostgreSQL schema 列表--watch-w{ grafserv: { watch: true } }数据库 schema 变化时自动更新 GraphQL schema注意需要数据库超级用户安装postgraphile_watchschema--host string-n{ grafserv: { host: localhost } }绑定的主机名默认localhost--port number-p{ grafserv: { port: 5678 } }端口号默认5678此外 CLI 还支持--version与--help。结合 cli.ts 的 run 函数 可以看到完整的启动流程加载 CLI 预设 → 读取graphile.config.js→ 将 CLI 选项写入 preset连接、schema、端口、watch 等→resolvePreset解析配置 →postgraphile(config)创建实例 → 通过createServ(grafserv)挂载 Grafserv 服务器并监听端口。环境要求与快速开始运行 PostGraphile 需要Node.js 22 或更高版本推荐 24见 package.json 的 engines 字段以及PostgreSQL 14.0 或更高版本。完整的从零搭建步骤安装 Node、安装/连接 PostgreSQL、创建数据库createdb mydb、验证select 1 1、安装postgraphile、启动服务请参考 quick-start-guide。启动成功后你会看到类似输出Server listening on port 5678 at http://127.0.0.1:5678/graphql在浏览器访问该 URL 即可使用 RuruGra*fast* 风味 GraphiQL IDE或使用任意 GraphQL 客户端向该 URL 发起请求。用 graphile.config 固化配置为避免每次输入一长串参数推荐创建graphile.config.mjs。仅需省去-P参数的最小配置import { PostGraphileAmberPreset } from postgraphile/presets/amber; export default { extends: [PostGraphileAmberPreset] };等价于带--watchCLI 命令的完整配置import { PostGraphileAmberPreset } from postgraphile/presets/amber; import { makePgService } from postgraphile/adaptors/pg; /** type {GraphileConfig.Preset} */ const preset { extends: [PostGraphileAmberPreset], pgServices: [makePgService({ connectionString: postgres:///mydb })], grafserv: { watch: true }, }; export default preset;此后直接运行npx postgraphile即可。更多关于graphile.config.mjs包括 TypeScript 写法的内容见 Configuration 文档。库模式以编程方式使用 PostGraphile除了 CLIPostGraphile 也可以作为 Node.js 库使用。核心入口 src/index.ts 导出的postgraphile(preset)函数接收一个 preset返回PostGraphileInstance其关键方法包括createServ(grafserv)创建 Grafserv 服务器实例只允许调用一次getSchemaResult()/getSchema()获取 schema 构建结果或最终的GraphQLSchemagetResolvedPreset()获取解析后的完整预设release()释放实例释放 server 与 watch 资源。从源码结构可以看到当 preset 中grafserv.watch为真时实例会通过watchSchema监听数据库变更并热更新 schema否则同步调用makeSchema(preset)一次性构建。这种CLI / 中间件 / 独立 schema的三态运行方式正是 V5 灵活性的体现。继续深入V4 用户迁移参考 V4 到 V5 迁移指南权限反射与行级安全PostGraphile 会自动反射数据库权限只暴露授权内容更多安全话题见 securityGra*fast* 引擎深入了解其 plan/step 执行模型可阅读 grafast 文档 与 grafast-for-postgraphile-users其他专题聚合aggregates、过滤filtering、JWT 认证jwt-guide、实时订阅subscriptions如果你刚接触 GraphQL建议先学习 GraphQL 官方入门教程再继续阅读 PostGraphile 文档。本文涉及的全部文档均可在仓库的postgraphile/website/versioned_docs/version-5/目录下找到原文。赞分享后端API网关【免费下载链接】crystal Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!项目地址https://gitcode.com/gh_mirrors/cry/crystal点击查看免费下载相关推荐PostGraphile 入门指南从 PostgreSQL 自动生成高性能 GraphQL API 的架构与实践PostGraphile 入门指南从 PostgreSQL 自动生成高性能 GraphQL API 的架构与实践 导读 本文基于 Crystal 仓库中 Po后端API网关PostGraphile 5 完全指南从 PostgreSQL 自动生成高性能、可深度定制的 GraphQL APIPostGraphile 5 完全指南从 PostgreSQL 自动生成高性能、可深度定制的 GraphQL API PostGraphile 是 Graph后端API网关PostGraphile实战指南从PostgreSQL到GraphQL API的自动化转换PostGraphile实战指南从PostgreSQL到GraphQL API的自动化转换 本文深入探讨PostGraphile的架构设计、工作原理及其在生产后端API网关创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考