加入我们，于10月8日至10日在纽约市学习关于GraphQL联合体和API平台工程的最新的技巧、趋势和新闻。在新泽西市为GraphQL峰会2024做准备
文档
免费开始

API 参考文档：ApolloServer

本篇文章文档了

查看我们的

构造函数

示例

import { ApolloServer } from '@apollo/server';


const server = new ApolloServer({
  typeDefs,
  resolvers,
});
import { ApolloServer } from '@apollo/server';


const server = new ApolloServer({
  typeDefs,
  resolvers,
});

选项

名称 /
类型		描述

指定模式

typeDefs

string，DocumentNode，Array＜DocumentNode＞

有效的Schema Definition Language（）字符串、文档或文档，代表您的服务器接口模式模式。要生成文档，可以将gql标签（来自graphql-tag）应用于有效的SDL字符串

必需除非您提供schema或gateway。

有关示例，请参阅定义您的GraphQL模式。

解析器

Object或Array

为个人模式字段填充数据的函数图。也可以是多个图合并的数组。

虽然技术上可选，如果您提供 typeDefs，强烈建议同时提供 resolvers。

有关详细信息，请参阅 解析器。

模式

对象

可执行的 GraphQL 模式。在内部， 自动从这个 typeDefs 和 resolvers 中生成这个字段。

如果以下情况适用，这个字段很有用：

  • 您正在为 Apollo Federation 构建子图，它使用 buildSubgraphSchema 函数来生成其模式。
  • 您正在使用类似 makeExecutableSchema 的函数从 graphql-tools 的函数来创建您的模式
  • 您正在使用一个采用代码优先方法的库（即，而不是采用模式优先方法）来生成一个模式
网关

对象

您可以使用此字段将您的服务器与 Apollo Gateway 集成。

模式选项

自省

布尔值

如果 true，则通过客户端启用 模式自省。这对于像 和 Playground 这样的工具有用，这些工具直接与服务器交互来了解其模式。（非沙盒版本的 Apollo Studio Explorer 不需要，该版本使用 Studio 模式注册表中发布的模式。）

默认值是 true，除非 环境变量 NODE_ENV 设置为 production。

字段解析器

GraphQLFieldResolver

一个自定义 ，它将替换 Apollo Server's 默认字段解析器。

根值

Any 或 Function

一个值或函数，它会接收解析的 Document，并创建传递给 GraphQL 执行器的根值。

如果要根据操作细节（例如，是否是一个 或 ）使用不同的根值，那么提供一个函数是非常有用的。

验证规则

Array

一个包含自定义函数的数组，用作额外的 验证规则，用于在验证操作时对照模式。请注意，这些规则应仅依赖于操作和模式，而不应依赖于特定于单个请求的任何其他内容，因为成功验证的结果会在请求之间进行缓存。

文档存储

KeyValueCache 或 null

一个键值缓存，Apollo Server 使用它来存储之前遇到的 GraphQL 操作 Apollo Server（作为 DocumentNode）。它不会存储查询结果。

每当 Apollo Server 接收一个传入的操作时，它会检查该确切的操作是否存在于其 documentStore。如果存在，Apollo Server 可以安全地跳过解析和验证操作，从而提高性能。

默认的 documentStore是一个近似容量为 30MiB 的 InMemoryLRUCache。这通常足够使用，除非服务器处理大量独特的操作。提供此选项以更改缓存大小或存储缓存信息到其他位置。

要使用 InMemoryLRUCache 但将大小更改为 approximateDocumentStoreMiB 约值：

import { InMemoryLRUCache } from '@apollo/utils.keyvaluecache';
import type { DocumentNode } from 'graphql';


new ApolloServer({
  documentStore: new InMemoryLRUCache<DocumentNode>({
    maxSize: Math.pow(2, 20) * approximateDocumentStoreMiB,
    sizeCalculation: InMemoryLRUCache.sizeCalculation,
  }),
  // ...
});

将 null 传递以完全禁用此缓存。

协议选项

持久查询

Object 或 false

如果你正在使用 自动化持久查询（APQ），你可以提供一个包含 cache 和/或 ttl 字段的 Apollo Server 对象来自定义操作哈希与查询字符串之间的映射存储方式，或者提供 false 来完全禁用 。

csrfPrevention

布尔型 或 对象

默认情况下， CSRF 防护功能已启用，以保护 Apollo Server 免受 CSRF 和 XS-Search攻击。

此功能可以防止某些 GET请求执行 GraphQL 操作，如果这些请求没有指定 特定头部信息。你可以通过传递一个配置对象到这个选项来配置允许执行操作的头部信息（例如，csrfPrevention: { requestHeaders: ['special-header'] }）。

如果你的服务器有发送 GET请求的客户端，并且这些客户端 不是 Apollo 的客户端库（Web、iOS、Kotlin）之一，你可能需要修改这些客户端的配置来使用此功能。有关更多详情，请参见 CSRF 防护文档。

你可以通过传递 false 给 csrfPrevention 来禁用此推荐的安全功能。

formatError

函数

提供此函数以在将错误对象发送到客户端之前转换其结构。

The formatError 钩子接收两个 ：第一个是要发送的 GraphQLFormattedError （将随响应发送），第二个是原始错误 (如果在解析器中抛出则包裹在 GraphQLError 中) 对象。

apollo

对象

一个包含连接Apollo Server到Apollo Studio配置选项的对象。此对象的每个字段也可以通过环境变量设置，这是设置这些参数的建议方法。Apollo Studio。所有字段都是可选的。字段包括：

  • key：Apollo Server用于验证Apollo Studio的图形API密钥。您可以使用APOLLO_KEY环境变量设置此值。
  • graphRef：您的在Apollo注册中的引用，如graph-id@my-variant或仅graph-id。您可以使用APOLLO_GRAPH_REF环境变量设置此值。
  • graphId：您在Apollo注册中的graph的ID。您可以使用APOLLO_GRAPH_ID环境变量设置此值。如果您指定了，则可能不需要指定此值。
  • graphVariant：与该服务器模式集和度量关联的的变体。您可以使用APOLLO_GRAPH_VARIANT环境变量设置此值。默认值为current。如果您指定了graph ref，则不需要指定此值。
allowBatchedHttpRequests

布尔值

控制是否允许在单个HTTP请求中批处理查询。批量请求查询默认为false。如果请求以数组格式而不是单个请求对象格式发送，则会引发错误（即，禁用操作批处理）除非启用了批处理。

生命周期选项

缓存

键值缓存

A KeyValueCache，Apollo Server用于多个功能，包括和完整响应缓存。此缓存也适用于Apollo Server的插件。

默认缓存是一个InMemoryLRUCache，默认大小约30MiB。为与Apollo Server 3向后兼容，指定cache: 'bounded'也会选择此默认有界缓存。

有关配置Apollo Server缓存的更多信息，请参阅配置缓存后端。

插件

数组

一个要在您的服务器实例中安装的插件插件数组。

您可以在启动服务器之前使用addPlugin方法将插件添加到服务器中。如果您的插件需要访问ApolloServer实例，这可能会很有用。

Apollo Server自带一些插件，如果满足某些条件，它会在默认配置下自动安装。例如，如果提供了和graph ref，则会安装使用情况报告插件。如果手动提供插件（在plugins数组中或使用addPlugin方法中），或者提供了插件的相应“禁用”插件（例如ApolloServerPluginUsageReportingDisabled()为ApolloServerPluginUsageReporting），Apollo Server会跳过此自动安装。有关详细信息，请参阅这些插件的API参考：使用情况报告，模式报告，着陆页面，缓存控制和内联跟踪。

stopOnTerminationSignals

布尔值

默认情况下，每当 Apollo Server 收到一个 SIGINT 或 SIGTERM 信号时，它会在自身上调用 await this.stop()。然后，它将相同的信号发送给自己以继续进程关闭。在 Apollo Server 等待 this.stop() 期间，会忽略后续的 SIGINT 和 SIGTERM 信号。注意，当 NODE_ENV 等于 test 或 Apollo Server 以服务端模式运行时，此情况不会发生。

将此选项设置为 false 以禁用此默认行为，或设置为 true 以在 NODE_ENV 等于 test 时启用行为。

在成功返回 start() 之后安装信号处理程序。

您还可以在其他上下文中手动调用 stop()。注意，stop() 是异步的，因此它不适合在 process.on('exit') 处理程序中使用。

调试选项

includeStacktraceInErrorResponses

布尔值

如果 true，则在发生错误时，在 GraphQL 响应中包括堆栈跟踪。

默认情况下为 true，除非环境变量 NODE_ENV 为 production 或 test。

logger

Logger

一个用于记录而不使用 console 的对象。如果提供，该对象必须实现 Logger 接口中所有的方法。

如果您提供此值，Apollo Server 将自动记录所有严重级别的消息（从 debug 到 error）。确定如何处理每个级别的记录消息是记录器的责任。

此记录器将自动添加到传递给所有 Apollo Server 插件函数 的 GraphQLRequestContext 对象中。

parseOptions

对象

一个指定您的服务器如何解析 GraphQL 操作的 请参阅 graphql-js 了解可用的配置选项。

nodeEnv

字符串

如果设置为任何字符串值，将使用该值而不是环境变量 NODE_ENV 来处理取决于 NODE_ENV 的默认值的特性 introspection）（例如）。注意，在这里传递空字符串与没有设置 NODE_ENV 环境变量相同。这主要是为了测试 NODE_ENV 环境变量的效果。

status400ForVariableCoercionErrors

布尔值

将此选项设置为 true。它减轻了 Apollo Server v4 中引入的一个回归问题，即当客户端的查询提供无效的 时，服务器返回 200 状态码（而不是 400）。更多详情。更多信息。

Apollo Server v5 将始终以此选项为 true 的方式操作（并将忽略提供的任何值）。

dangerouslyDisableValidation

布尔值

⚠️ 注意：此选项可能导致安全漏洞和意外的行为。Apollo 不支持在生产中使用此选项。

当设置为 true 时，完全禁用 GraphQL 操作的验证。

如果您在构建时处理操作验证并将只有已知的、经过验证的操作允许在运行时执行，您可能会对此选项感兴趣。请注意，操作验证将缓存到 Apollo Server 的文档存储中。

start

异步 start 方法指示 Apollo Server 准备处理即将到来的操作。

仅在您为非无服务器环境使用框架集成（例如，expressMiddleware）时调用 start。

  • 如果您使用的是无服务器框架集成（如 Lambda），则不应在将您的服务器传递给集成函数之前调用此方法。您的无服务器集成函数会为您处理服务器的启动。

  • 如果您使用 startStandaloneServer，则无需在将服务器直接传递给 startStandaloneServer 之前启动您的服务器。

始终在将您的服务器传递给您的集成函数并开始接受请求之前调用 await server.start()：

const server = new ApolloServer<MyContext>({
  typeDefs,
  resolvers,
});
await server.start();


app.use('/graphql', cors<cors.CorsRequest>(), express.json(), expressMiddleware(server));
const server = new ApolloServer({
  typeDefs,
  resolvers,
});
await server.start();


app.use('/graphql', cors(), express.json(), expressMiddleware(server));

这使得您可以通过终止进程来响应 Apollo Server 启动失败，而不是开始接收流量。

如果您正在使用 executeOperation 测试您的服务器（即，您并未实际启动一个 HTTP 服务器），则无需调用 start()，因为 executeOperation 会为您完成这一操作。

触发动作

start 方法会触发以下动作：

  1. 如果您的服务器是一个 联邦网关，它将尝试获取其模式。如果获取失败，start 会抛出一个错误。
  2. 您的服务器将调用已安装的所有插件的 serverWillStart 处理器。如果有任何这些处理器引发错误，start 会抛出一个错误。

startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests

无服务器集成通过调用 Apollo Server 实例的 startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests 方法在后台启动实例。这种方法是 同步的，不需要 awaited。这意味着发生的任何错误都发生在后台，因此您无法立即处理它们。有关详细信息，请参阅 构建集成。

此方法 触发了与 start() 方法相同的作用。

addPlugin

您可以使用 addPlugin 方法在服务器启动前添加插件。当您想添加一个接受您初始化 ApolloServer 实例本身的插件时，这非常有用：

const server = new ApolloServer({
  typeDefs,
  plugins: [makeFirstPlugin()],
});


server.addPlugin(makeSecondPlugin(server));
const server = new ApolloServer({
  typeDefs,
  plugins: [makeFirstPlugin()],
});


server.addPlugin(makeSecondPlugin(server));

assertStarted

框架集成应调用 server.assertStarted() 确保服务器在接收请求之前已启动。有关详细信息，请参阅 构建集成。

stop

ApolloServer.stop() 是一个异步方法，告诉 Apollo Server 的所有后台任务完成。具体来说，它会：

  • 调用并等待所有 drainServer 插件处理器。这些应通常：
    • 停止监听新连接
    • 关闭空闲连接（即，没有当前 HTTP 请求的连接）
    • 当它们变为空闲时关闭活动连接
    • 等待所有连接关闭
    • 宽限期过后，如果存在任何活动连接，强制关闭它们。如果你使用 startStandaloneServer，则默认会执行此操作。否则，你可以使用 drain HTTP server 插件 来排空你的 HTTP 服务器。
  • 将服务器转换为不会执行更多：GraphQL 操作 的状态。
  • 调用并等待所有 serverWillStop 插件处理程序（包括 usage reporting 插件's 处理程序，该处理程序会将最终使用报告发送到 Apollo Studio）。
  • 如果你的服务器是一个 联邦网关，则 stop 也会停止特定于网关的后台活动，例如轮询更新的服务配置。

此方法不接受任何参数。您只能在 start() 成功返回（或您已经调用 startStandaloneServer 并使用您的 ApolloServer 实例）之后调用它。

在某些情况下，Apollo Server 会自动在进程接收到 SIGINT 或 SIGTERM 信号时调用 stop。有关详细信息，请参阅 stopOnTerminationSignals 构造函数选项。

executeOperation

异步 executeOperation 方法主要用于通过 Apollo Server 的请求流水线而无需发送 HTTP 请求来测试 GraphQL 操作。

const response = await server.executeOperation({
  query: 'query SayHelloWorld($name: String) { hello(name: $name) }',
  variables: { name: 'world' },
});

executeOperation 方法接受两个参数：

  • 第一个参数是一个描述要执行的 GraphQL 操作的对象。
    • 支持的字段列在下表中。
  • 第二个参数是可选的选项对象。此对象包含操作的可选 contextValue。此参数是可选的，前提是你的服务器 不需要一个上下文值（即，你的服务器使用默认上下文，因为您没有明确提供另一个上下文）。
const response = await server.executeOperation({
  query: 'query SayHelloWorld($name: String) { hello(name: $name) }',
  variables: { name: 'world' },
}, {
  contextValue: { userId: 'test' },
});

从 executeOperation 返回的 response 对象是一个 GraphQLResponse，它具有 body 和 http 字段。

Apache Server 4 支持增量交付指令，例如，如@defer和@stream（当与适当的graphql-js版本结合时），因此response.body的结构可以表示单个结果或多个结果。response.body.kind可以是'single'或'incremental'。如果是'single'，则未使用增量交付，response.body.singleResult是一个具有data、errors和extensions字段的对象。如果是'incremental'，则response.body.initialResult是操作的初始结果，response.body.subsequentResults是一个异步迭代器，将产出后续结果。（initialResult和subsequentResults的确切结构由graphql-js定义，并且在graphql-jsv17的当前预发布版和最终发布版之间可能会有变化；如果您在graphql-jsv17发布前编写用于处理这些值的代码，您可能需要在API最终确定时对其进行修改。）

The http字段包含可选的数字状态码和一个headers映射，用于指定任何应设置的HTTP状态码和头部。

下面是executeOperation的第一个参数可用字段：

字段

名称描述
查询

string或DocumentNode

必需. 运行的GraphQL操作。请注意，即使操作是mutation，也必须使用query字段。这可能也是一个TypedQueryDocumentNode，在这种情况下，variables选项和response.body.singleResult.data的类型将自动推断。

变量

对象

包含任何GraphQL变量作为执行操作参数值的对象。
操作名称

字符串

如果query包含多个操作定义，必须提供此选项以指示要执行的操作。

扩展

对象

The extensions 对象通常用于在服务器请求的生命周期中从一个触点传递至另一个触点（例如，从请求到插件）传递请求元数据。在这种情况下，此对象表示实际请求中发送的请求 。

http

HTTPGraphQLRequest

一个实现 HTTPGraphQLRequest 接口的对象，包含有关传入 HTTP 请求的信息。

executeHTTPGraphQLRequest

The executeHTTPGraphQLRequest 方法是 web 框架集成的入口。您可以向 executeHTTPGraphQLRequest 方法传递 HTTPGraphQLRequest 对象以执行 GraphQL 请求：

const result = await server.executeHTTPGraphQLRequest({
  httpGraphQLRequest: OurHttpGraphQLRequest,
  context: async () => ({
    // token: ...,
  }),
});
const result = await server.executeHTTPGraphQLRequest({
  httpGraphQLRequest: OurHttpGraphQLRequest,
  context: async () => ({
    // token: ...,
  }),
});

有关详细信息和方法示例，请参阅 Building Integrations。

缓存

ApolloServer 公共只读字段，允许您访问服务器缓存。

logger

ApolloServer 公共只读字段，允许您访问服务器的日志。

上一页
健康检查
下一页
startStandaloneServer
评价文章评价在GitHub上编辑Edit论坛Discord

©2024Apollo Graph Inc.，以Apollo GraphQL的名义。

隐私政策

公司

资源

联系