最佳实践

¥Best Practices

GraphQL 可扩展吗？

¥Is GraphQL scalable?

是的，GraphQL 被设计为可扩展的，并且被许多公司在非常高负载下用于生产。

¥Yes, GraphQL is designed to be scalable and is used by many companies in production under a very high load.

GraphQL 附带一些可以提供帮助的 内置性能提升。但一旦将其推向生产，你就有责任跨实例扩展它并监控性能。

¥GraphQL comes with some built-in performance boosts that can help. But once you push it to production, you’re responsible for scaling it across instances and monitoring performance.

GraphQL 是否支持离线使用？

¥Does GraphQL support offline usage?

不，或者至少不是原生的。但有 GraphQL 客户端 可让你先离线构建。它们使用旨在离线执行数据操作的功能，例如缓存和服务工作者。

¥No, or at least not natively. But there are GraphQL clients that enable you to build offline-first. They use features designed to perform data operations while offline, such as caching and service workers.

你可以在我们的 代码页 上找到各种语言的 GraphQL 客户端列表。

¥You can find a list of GraphQL clients in various languages on our Code page.

GraphQL 有哪些安全问题？

¥What are the security concerns with GraphQL?

与 GraphQL 相关的大多数安全问题对于任何 API 或服务来说都是典型的。举几个例子：SQL 注入、拒绝服务 (DoS) 攻击或有人滥用有缺陷的身份验证。但也有一些特定于 GraphQL 的攻击。例如，批处理攻击。这些攻击可能是由于 GraphQL 允许你在单个网络调用中批量处理多个查询（或多个对象实例的请求）而发生的。

¥Most of the security concerns associated with GraphQL are typical for any API or service. A few examples: SQL injections, Denial of Service (DoS) attacks, or someone abusing flawed authentication. But there are also some attacks specific to GraphQL. For instance, batching attacks. These attacks can happen as a result of GraphQL allowing you to batch multiple queries (or requests for multiple object instances) in a single network call.

无论问题是什么，积极主动都很重要。有很多方法可以保护你的 GraphQL 服务器。使用超时、设置查询的最大深度以及根据服务器完成所需的时间来限制查询都是潜在的方法。

¥No matter the concern, it’s important to be proactive. There are many ways to securing your GraphQL server. Using a timeout, setting a maximum depth for queries, and throttling queries based on the server time it needs to complete are all potential approaches.

有关常见安全问题的概述及其解决方法，请查看 关于如何使用 GraphQL 的安全教程 和 OWASP 的 GraphQL 备忘单。

¥For an overview of common security concerns and how to address them, check out the Security tutorial on How to GraphQL and OWASP’s GraphQL Cheat Sheet.

如何使用 GraphQL 设置授权？

¥How can I set up authorization with GraphQL?

我们建议在 业务逻辑层 中强制执行授权行为。这样，你就有了一个授权的单一真实来源。

¥We recommend enforcing authorization behavior in the business logic layer. That way, you have a single source of truth for authorization.

有关更详细的解释，请访问我们的 授权文档。

¥For a more detailed explanation, go to our Authorization documentation.

GraphQL 中的身份验证如何工作？

¥How does authentication work with GraphQL?

你可以使用常见结构（例如 OAuth 或 JWT）实现身份验证。GraphQL 规范中的身份验证没有什么特别之处。

¥You can implement authentication with common patterns, such as OAuth or JWT. There’s nothing special about authentication within the GraphQL specification.

一些 GraphQL 库 还包括用于身份验证的特定协议。尽管如果你使用的是管道模型，我们建议 GraphQL 应置于所有身份验证中间件之后。

¥Some GraphQL libraries include a specific protocol for authentication as well. Although if you’re working with a pipeline model, we recommend that GraphQL be placed after all authentication middleware.

如果你使用 GraphQL.js 构建 API 服务器，我们有关于 使用 Express 中间件处理身份验证 的文档。

¥If you’re using GraphQL.js to build your API server, we have documentation on handling authentication with Express middleware.

GraphQL 是否适合设计微服务结构？

¥Is GraphQL the right fit for designing a microservice architecture?

是的，可以。如果你将 GraphQL 集成到你的微服务结构中，我们建议使用一个 GraphQL 结构作为 API 网关，而不是让你的客户端与多个 GraphQL 服务对话。这样，你可以将后端拆分为微服务，但仍然将所有数据从单个 API 聚合到前端。

¥Yes, it can be. If you’re integrating GraphQL into your microservice architecture, we’d recommend having one GraphQL schema as an API gateway rather than having your client talk to multiple GraphQL services. This way, you can split your backend into microservices, but then still aggregate all your data to the frontend from a single API.

创建 API 网关的方法有很多。使用 GraphQL 的好处是你可以利用 caching 等功能、请求预算和规划查询计划。

¥There are many ways to create an API gateway. The benefit of using GraphQL is that you can take advantage of features like caching, request budgeting, and planning out query schedules.

GraphQL 中的版本控制如何工作？

¥How does versioning work in GraphQL?

没有什么可以阻止 GraphQL 服务像任何其他 REST API 一样进行版本控制。也就是说，GraphQL 在设计上避免了版本控制。

¥There’s nothing that will prevent a GraphQL service from being versioned like any other REST API. That said, GraphQL avoids versioning by design.

相反，GraphQL 提供了不断构建和发展结构的工具。例如，GraphQL 仅返回明确请求的数据。这意味着你可以添加新功能（以及所有相关类型和字段），而不会对现有查询造成重大更改或导致结果膨胀。

¥Instead, GraphQL provides the tools to continually build and evolve your schema. For example, GraphQL only returns the data that’s explicitly requested. This means that you can add new features (and all the associated types and fields) without creating a breaking change or bloating results for existing queries.

你可以在我们的最佳实践部分阅读有关 GraphQL 中的版本控制工作原理 的更多信息。

¥You can read more about how versioning works in GraphQL in our Best Practices section.

我如何记录我的 GraphQL API？

¥How can I document my GraphQL API?

GraphQL 的一个好处是它本质上是自文档化的。这意味着当你使用像 GraphiQL 这样的交互式工具时，你可以探索 GraphQL API 公开的数据。这包括 fields、types 等。你还可以添加 描述字段 来提供有关你的端点的补充说明。此描述字段支持字符串和 Markdown。

¥One of the benefits of GraphQL is that it’s inherently self-documenting. This means that when you use an interactive tool like GraphiQL, you’re able to explore what data is exposed by your GraphQL API. This includes the fields, types, and more. You can also add a description field to provide supplementary notes about your endpoint. This description field supports strings and Markdown.

对于许多人来说，这提供了足够的 API 参考文档。但这不会减少对其他形式文档的需求。你可能仍需要创建指南来解释一般概念如何与你的特定用例相关联。

¥For many, this provides enough API reference documentation. But it doesn’t reduce the need for other forms of documentation. You’ll likely still need to create guides that explain how the general concepts tie into your specific use case.