Skip to main content

Usage使用方式

There's three main ways of using PostGraphile: a CLI that you can run with minimal effort, the library mode that we expect most users will ultimately want to use, and schema-only mode which gives you the most control (but also the most responsibilities). Each of these layers builds on top of the layer below it, so it's fairly easy to move between them. We've also made sure that they are each configured via the same preset system so you can move from one to another with minimal effort.

PostGraphile 主要有三种使用方式:几乎零门槛即可运行的 CLI 命令行模式、大多数用户最终会选择的库模式(library mode),以及控制度最高(同时需要自行承担最多集成工作)的纯 schema 模式(schema-only mode)。这三种方式逐层构建,因此在它们之间切换相当容易;而且它们共用同一套 preset 系统,迁移几乎无需额外成本。

CLICLI​

PostGraphile CLI is the most user-friendly way to try PostGraphile, but also the most limited: it accepts a few command line options, will load your config file, and spins up a Node http server (or cluster thereof) to host the Grafserv instance from the PostGraphile library (see next). The CLI does not integrate with existing Node.js servers, so if you need that you'll want to use library mode.

PostGraphile CLI 是体验 PostGraphile 最便捷的方式,但功能也相对受限:它接收少量命令行参数、加载你的配置文件,并启动一个 Node http 服务器(或其集群)来托管 PostGraphile 库提供的 Grafserv 实例(见下文)。CLI 无法集成到现有的 Node.js 服务器中,如有这类需求,请改用库模式。

tip提示

Most users should start with this layer, and many users use it successfully in production. If you don't need to leverage much of the Node.js ecosystem in your API then you may find it's sufficient for your needs.

建议绝大多数用户从这一层起步,也有不少用户直接在生产环境中稳定运行它。如果你的 API 不需要深度借助 Node.js 生态中的其他组件,CLI 模式往往就已经足够了。

Library库模式​

The PostGraphile library builds your GraphQL schema (see next), possibly in watch mode, and lets you access it or retrieve a Grafserv instance. You can mount the Grafserv instance in Node's http server, or as a middleware in any of a number of Node.js web servers, such as Connect, Express, Koa, Fastify, Restify, etc.

PostGraphile 库模式负责构建你的 GraphQL schema(见下文),并支持在 watch 模式下自动监听变更,同时允许你直接访问该 schema 或获取一个 Grafserv 实例。你可以将 Grafserv 实例挂载到 Node 原生 http 服务器中,或作为中间件集成到 Connect、Express、Koa、Fastify、Restify 等各类 Node.js Web 框架里。

Grafserv is responsible for receiving, deciphering, and validating the GraphQL HTTP request from the user according to the options supplied; building the GraphQL context (which includes things such as authentication details); and then sending the query along with the GraphQL schema (see next) to Grafast to be executed.

Grafserv 负责根据配置项接收、解析并校验来自客户端的 GraphQL HTTP 请求,构建包含鉴权信息等内容的 GraphQL context,随后将查询语句连同 GraphQL schema(见下文)一并交给 Grafast 执行。

tip提示

About 70% of PostGraphile users end up using this layer in their applications. Using PostGraphile as a middleware like this is the recommended setup for most folks — it allows you to combine your PostGraphile GraphQL server with anything else your Node server needs to provide (e.g. authentication, session management, logging, rate limiting, other endpoints, etc) and leverage the full power of the Node.js ecosystem.

约 70% 的 PostGraphile 用户最终都会在应用中使用这一层。对大多数项目而言,以中间件形式接入 PostGraphile 是最推荐的做法——它能让你将 PostGraphile GraphQL 服务与 Node 服务器所需的其他能力(如鉴权、会话管理、日志记录、限流、自定义接口等)无缝结合,充分发挥 Node.js 生态的优势。

Schema纯 Schema 模式​

PostGraphile schema-only mode ("schema-only") focuses on building the GraphQL schema containing all your types, fields and plans (Grafast's replacement for resolvers). The plans inside the schema take care of configuring a PG client with the relevant settings when needed, so the schema can be used without lifecycle management (though you will need to be sure to pass a suitable context).

PostGraphile 纯 schema 模式(schema-only)专注于构建包含所有类型、字段及 plan(Grafast 中替代传统 resolver 的概念)的 GraphQL schema。schema 内部的 plan 会在需要时自动为 PG 客户端配置相关会话参数,因此该 schema 可以脱离生命周期管理独立运行(不过你仍需确保传入合适的上下文)。

Thanks to PostGraphile's exportable schema support you can even write an executable version of this GraphQL schema to disk as JavaScript - this file will not depend on postgraphile, graphile-build, graphile-build-pg, graphile-utils or other "build time" schema concerns - it will only contain references to what is necessary for it to execute in production, such as graphql, grafast, @dataplan/pg and jsonwebtoken.

借助 PostGraphile 的可导出 schema 支持,你甚至可以将可执行版本的 GraphQL schema 直接写成 JavaScript 文件保存到磁盘中。该文件不再依赖 postgraphile、graphile-build、graphile-build-pg、graphile-utils 等“构建期”依赖,仅保留生产环境执行所必需的模块引用,例如 graphql、grafast、@dataplan/pg 和 jsonwebtoken。

tip提示

Few users need this, but it is helpful for server-side GraphQL resolution without the overhead of a network layer.

只有少数场景需要用到这一层,不过当你需要跳过网络层开销、直接在服务端执行 GraphQL 解析时,它非常实用。

Use the config, Luke!愿配置之力与你同在!​

By storing your configuration into a graphile.config.js (or similar) file, you will be able to run PostGraphile in any of these three modes and still leverage a similar setup in each. This file also saves us from having to offer 72 different CLI flags like we did in V4, instead only offering the most essential options.

只要把你的配置存入 graphile.config.js(或同类文件),就能在以上三种模式中通用同一套配置逻辑,轻松运行 PostGraphile。也正因有了这个配置文件,V5 不再需要像 V4 那样提供多达 72 个 CLI 参数,只需保留最核心的选项即可。

Which one should I use?我该选择哪一种?​

We recommend that you start with the PostGraphile CLI and then quickly move to the PostGraphile middleware if you need deeper integration with Node.js.

我们建议先从 PostGraphile CLI 上手;当需要与 Node.js 做更深度的集成时,再迅速切换到 PostGraphile 中间件模式。

Which layer would you like to read more about?

你想进一步了解哪一层?