由Austin Roy Omondi撰写✏️

简介

GraphQL是与服务器端数据通信的绝佳解决方案,它允许开发人员创建快速可靠的 API,通过允许那些与服务器交互的数据来解决过度获取和获取不足数据的问题指定服务器所需数据的精确结构。这意味着为那些构建使用 GraphQL API 的应用程序的开发人员提供更好的体验,并为最终用户提供更快的应用程序。

PostGraphile,以前称为 PostGraphQL,在将这两种技术配对方面做得很好,使开发人员可以快速组合一个功能齐全的 GraphQL 服务器,在 PostgreSQL 数据库上存储数据。 PostGraphile 利用数据库驱动开发从 Postgres 数据库架构生成和更新 Graphql 服务器,自动检测您对架构所做的更改并相应地更新服务器。

用他们自己的话来说:

PostgreSQL 已经拥有惊人的授权和关系基础设施,为什么要在自定义 API 中重复该逻辑?

PostGraphile 处理创建高性能且符合标准的 GraphQL API 层,允许开发人员专注于产品。这也大大缩短了开发时间。

PostGraphile 还拥有一个强大的插件系统,有几个社区开发的插件可以帮助以各种方式扩展其功能。

在本文中,我们将了解如何使用 PostGraphile 在几分钟内启动并运行功能齐全的服务器。

PostGraphile 使用

PostGraphile 可以以三种主要方式使用:

• 使用 PostGraphile CLI — 这是直接从终端启动 PostGraphile API 的最简单、最快捷的方法。我们今天将介绍

• 作为中间件——这种方式将从postgraphile包导入的 PostGraphile 实例安装到 NodeJS 服务器上

• 通过 Docker——通过将 PostGraphile 作为 docker 镜像并将其作为 CLI 选项传递给 Docker 容器来实现

入门

为了使用 PostGraphile,您需要安装 Node.js v8.6 或更高版本,如果您还没有安装它,您可以在 Node网站上找到它。

您还需要 PostgreSQL v9.6.0 或更高版本,可在 PostgreSQL下载页面上找到。

数据库设置

一旦你安装了这两个,你需要创建你的数据库。首先,确保 Postgres 正在运行。为此,请在终端中运行以下命令:

psql

进入全屏模式 退出全屏模式

如果您遇到以下错误,这可能意味着 Postgres 尚未运行:

psql: could not connect to server: No such file or directory
        Is the server running locally and accepting
        connections on Unix domain socket "/tmp/.s.PGSQL.5432"?

进入全屏模式 退出全屏模式

要解决此问题,请启动。对于使用 homebrew 的 mac 用户,运行:

brew services start postgres

进入全屏模式 退出全屏模式

对于 Windows 用户:

• 通过Winkey + R打开运行窗口

• 类型services.msc

• 根据安装的版本搜索 Postgres 服务

• 单击停止、启动或重新启动服务选项

对于 Linux 用户,运行:

sudo service postgresql start

进入全屏模式 退出全屏模式

一旦 Postgres 运行,运行以下命令为您的应用程序创建一个数据库:

createdb testdb

进入全屏模式 退出全屏模式

这将创建一个名为“testdb”的数据库,我们将使用它来创建示例 API。您现在可以使用数据库名称或 URL 运行psql来访问它并在其上运行 SQL 查询,对我们来说,这看起来像这样:

psql testdb

进入全屏模式 退出全屏模式

或者

psql postgres:///testdb

进入全屏模式 退出全屏模式

安装 PostGraphile

通过运行以下命令,可以使用npm轻松地全局安装 PostGraphile:

npm install -g postgraphile

进入全屏模式 退出全屏模式

现在您已经安装了 Postgraphile,您可以通过运行以下命令查看 CLI 标志:

postgraphile --help

进入全屏模式 退出全屏模式

要运行 PostGraphile,您将使用与psql相同的 URL,并添加数据库名称:

postgraphile -c "postgres:///testdb"

进入全屏模式 退出全屏模式

其中-c是连接字符串(默认为postgres:///),-s是模式名称(默认为“public”),-a启用中继支持,-j启用动态 JSON。

当 PostGraphile 运行时,它会给出两个端点:

• GraphQL API:http://localhost:5000/graphql

• GraphiQL GUI/IDE:http://localhost:5000/graphiql

第一个端点供您的应用程序与之通信,第二个端点可以在 Web 浏览器中打开,以便您通过GraphiQL(可视化 GraphQL 浏览器)访问数据库。

伟大的!现在我们已经设置了 PostGraphile,我们可以开始定义数据库的结构,这反过来又允许 PostGraphile 更新我们的 API。

模式和表

如postgres 文档中所述,数据库包含一个或多个名为 schemas 或 namespaces ,其中包含我们存储数据的表。模式还包含其他类型的命名对象,包括数据类型、函数和运算符。相同的对象名称可以在不同的模式中使用而不会发生冲突。例如,schema1和myschema都可以包含名为mytable的表。与数据库不同,模式不是严格分开的。用户可以访问他们连接到的数据库中任何模式中的对象,如果他们有权限这样做的话。

与数据库一起创建的默认模式是public,大多数用户只处理这个。在 PostGraphile 中,建议使用模式来帮助组织您的应用程序——您可以将一种模式用于将公开给 GraphQL 的表,另一种用于应该完全私有的表(例如,您存储散列用户密码的位置),您也可以使用其他模式,具体取决于对您的应用程序有意义的方式。

Postgraphile 文档中提供的模式示例如下:

• app_public– 向 GraphQL 公开的表和函数

• app_hidden- 与app_public相同的权限,但根本不暴露给 GraphQL

• app_private– 需要提升权限才能访问的机密

对于我们的应用程序,我们将保持简单,并通过从 Postgres CLI 运行以下命令来创建我们自己的模式,我们将调用test_schema:

CREATE SCHEMA test_schema;

进入全屏模式 退出全屏模式

一个模式可以包含多个表,对于我们的示例,让我们在test_schema中创建两个表,一个包含作者,另一个包含这些作者发表的帖子。我们将通过给它每个表的结构来做到这一点。

authors表将有一个id作为主键、一个唯一标识它们的用户名以及名字、姓氏和简历。

另一方面,posts表将有一个id作为主键,一个headline字段作为其标题,以及一个body和created_at。还有一个字段,这是author_id,它通过创建一个引用authors表外键链接到它,这创建了一个作者可以有多个帖子的一对多关系:

CREATE TABLE test_schema.authors (
  id serial PRIMARY KEY,
  username text NOT NULL unique,
  firstname text NOT NULL,
  lastname text NOT NULL,
  bio text
);

create table test_schema.posts (
  id serial primary key,
  headline text not null,
  body text,
  -- `references` 👇  sets up the foreign key relation
  author_id int4 references test_schema.authors(id),
  created_at timestamptz NOT NULL DEFAULT now()
);

进入全屏模式 退出全屏模式

现在让我们在数据库中插入一些数据。让我们创建两个用户:

INSERT INTO test_schema.authors (username, firstname, lastname, bio) VALUES
('austinroy', 'Austin', 'Roy', 'Gamer, developer, blogger'),
('darthvader', 'Anakin', 'Skywalker', 'Former Jedi, Dark Lord of the Sith trying to save Padme');

进入全屏模式 退出全屏模式

让我们验证数据是否已按预期输入数据库:

SELECT * FROM test_schema.authors;

进入全屏模式 退出全屏模式

结果应显示创建的两个条目,如下所示。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--U7N1c5Wm--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://i2.wp. com/blog.logrocket.com/wp-content/uploads/2020/02/testdb.png%3Fresize%3D730%252C83%26ssl%3D1)

GraphQL 交互

您可以使用下面显示的查询在 GraphiQL(服务器提供的 GraphQL 可视化浏览器)上查询上述数据,它应该会按预期返回数据。这可以通过将下面声明的query发送到http://localhost:5000/graphiql上的服务器来完成,以返回保存的某些详细信息。

您可能已经注意到,在 Postgres 中使用snake_case声明的一些变量已在 GraphQL API 中转换为camelCase,这是此类 API 的标准。这取决于 PostGraphile 应用变形的概念来将事物映射到更自然的名称上,同时避免冲突。它还有助于命名目标类型和引用列,例如postsByAuthorId。

query {
  allAuthors{
    nodes {
      username
      firstname
      lastname
      bio
    }
  }
}

进入全屏模式 退出全屏模式

[](https://res.cloudinary.com/practicaldev/image/fetch/s--LSz3V4tA--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://i0.wp。 com/blog.logrocket.com/wp-content/uploads/2020/02/graphiql.png%3Fresize%3D730%252C440%26ssl%3D1)

就像这样,我们在 Postgres DB 上启动并运行了一个完整的 GraphQL 服务器。为了利用我们的服务器,让我们使用 GraphiQL 创建我们的第一篇文章。我们将通过执行 PostGraphile 为我们生成的 createPostMutation来做到这一点。

首先,我们需要在 GraphQL 中定义您的查询,它看起来像这样:

mutation createPost($input: CreatePostInput!){
  createPost(input: $input){
    post{
      headline
      body
      createdAt
    }
  }
}

进入全屏模式 退出全屏模式

这利用提供的input创建新帖子并从帖子中返回选定的字段。我选择返回帖子标题、正文和创建时间,省略 ID。您可以通过将它们包含在突变中来选择要返回的值。

您可能想知道input在哪里传递给上面的突变。我们将在当前隐藏的 QUERY VARIABLES 部分中单独声明它们。要启动它,只需单击屏幕底部的 QUERY VARIABLES 面板,然后将以下代码传递给它:

{
  "input":
          {
      "post": {
        "headline": "Obi Wan",
        "body": "Hello There",
        "authorId": 1
      }
    }
}

进入全屏模式 退出全屏模式

带有作为输入传递的变量的对象应该以 JSON 格式声明,不带任何尾随逗号,以避免它被 GraphiQL 无效,GraphiQL 执行自己的检查。

这是它在浏览器中的样子。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--0LfGQAlv--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://i0.wp.com/ blog.logrocket.com/wp-content/uploads/2020/02/queryvariables.png%3Fresize%3D730%252C438%26ssl%3D1)

这些只是 PostGraphile 从我们提供的数据库模式中为我们生成的几个Queries和Mutations中的两个。这些包括:

• allAuthors– 通过一组Author(获取所有作者的所有数据的 GraphQL 对象类型)读取并启用分页

• allPosts– 通过一组Posts(获取所有作者的所有数据的 GraphQL 对象类型)读取并启用分页

• authorByUsername– 返回与给定用户名匹配的Author

• author– 返回与给定id匹配的Author

• post- 返回与给定id匹配的Post

• createAuthor– 从给定的有效载荷创建Author

• updateAuthor– 如果存在匹配的id,则从给定的有效负载更新Author

• deleteAuthor– 如果存在匹配的id,则从给定的有效负载中删除Author

• createPost– 从给定的有效载荷创建一个Post

• updatePost– 如果存在匹配的id,则从给定的有效负载更新Post

• deletePost– 如果存在匹配的id,则从给定的有效负载中删除Post

除了处理您可能需要的大部分 CRUD 功能之外,PostGraphile 还记录了大多数这些 GraphQL 类型(查询和突变)的使用,使得生成的 API 非常容易被任何想要使用它的人使用。

带有智能注释的文档

您可能已经注意到数据类型,即作者和帖子尚未记录。这可以通过使用智能评论快速解决。为了说明这一点,让我们添加一些文档来解释我们的authors表。

要向我们的authors表添加注释,请在 Postgres 中运行以下命令:

COMMENT ON TABLE test_schema.authors IS 'Author on the platform';

进入全屏模式 退出全屏模式

当您检查 GraphiQL 中的Author类型时,它从“无描述”更改为“平台上的作者”,如此屏幕截图所示。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--dXp0SLIU--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://i2. wp.com/blog.logrocket.com/wp-content/uploads/2020/02/documentationwithcomments.png%3Fresize%3D351%252C727%26ssl%3D1)

结论

PostGraphile 是一个强大的工具,可以帮助开发人员快速轻松地设置在 PostgreSQL 数据库上运行的功能齐全且强大的 GraphQL API。这使他们能够构建在安全稳定的数据库上运行的快速可靠的 API,并具有多种强大的功能。它也是一个非常容易使用的工具,可以大大加快这些 API 的开发时间,使开发人员能够专注于解决问题而不是设置应用程序。本文仅涵盖 PostGraphile 必须提供的众多功能的一个子集,您可以通过查看完整的文档来了解有关它们的更多信息。

---

仅 200 个 u200e✅:监控失败并在生产中显示 GraphQL 请求

虽然 GraphQL 具有一些用于调试请求和响应的功能,但确保 GraphQL 可靠地为您的生产应用程序提供资源是事情变得更加困难的地方。如果您有兴趣确保对后端或第三方服务的网络请求成功,请尝试使用 LogRocket。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--UHOs84WY--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://thepracticaldev. s3.amazonaws.com/i/jd2amkhuiynfjf3i33qk.png)

LogRocket就像一个用于网络应用程序的 DVR,几乎可以记录您网站上发生的所有事情。无需猜测问题发生的原因,您可以汇总和报告有问题的 GraphQL 请求,以快速了解根本原因。此外,您可以跟踪 Apollo 客户端状态并检查 GraphQL 查询的键值对。

LogRocket 检测您的应用程序以记录基准性能时间,例如页面加载时间、第一个字节的时间、缓慢的网络请求,并记录 Redux、NgRx 和 Vuex 操作/状态。免费开始监控。

---

帖子Intro to Postgres + GraphQL with PostGraphile首先出现在LogRocket Blog上。