GraphQL 介绍

¥Introduction to GraphQL

Learn about GraphQL, how it works, and how to use it

GraphQL 是用于 API 的查询语言，也是使用你为数据定义的类型系统执行查询的服务器端运行时。GraphQL 规范 于 2015 年开源，此后已在多种编程语言中实现。GraphQL 不依赖于任何特定的数据库或存储引擎 - 它由你现有的代码和数据支持。

¥GraphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your data. The GraphQL specification was open-sourced in 2015 and has since been implemented in a variety of programming languages. GraphQL isn’t tied to any specific database or storage engine—it is backed by your existing code and data.

使用类型系统描述你的 API

¥Describe your API with a type system

GraphQL 服务由 定义类型及其字段 创建，然后为每个字段编写一个函数到 提供所需数据。例如，告诉你登录用户名称的 GraphQL 服务可能如下所示：

¥A GraphQL service is created by defining types and their fields, and then writing a function for each field to provide the required data. For example, a GraphQL service that tells you the name of a logged-in user might look like this:

type Query {
  me: User
}
 
type User {
  name: String
}

以及每种类型的每个字段的函数：

¥Along with functions for each field on each type:

// Provide data for the `me` field on the `Query` type
function Query_me(query, args, context, info) {
  return context.request.auth.user
}
 
// Provide data for the `name` field on the `User` type
function User_name(user, args, context, info) {
  return context.db.getUserFullName(user.id)
}

在上面的例子中，为 Query 类型上的 me 字段提供数据的函数使用有关发出请求的经过身份验证的用户的信息，而 User 类型上的 name 字段则使用该用户的 ID 从数据库中获取其全名来填充。

¥In the example above, the function that provides data for the me field on the Query type uses information about the authenticated user who made the request, while the name field on the User type is populated by using that user’s ID to fetch their full name from a database.

查询你所需的内容

¥Query exactly what you need

GraphQL 服务运行后（通常在 Web 服务的 URL 上），它可以从客户端接收 GraphQL 查询 以进行验证和执行。服务首先检查查询以确保它仅引用为 API 定义的类型和字段，然后运行提供的函数以产生结果。

¥After a GraphQL service is running (typically at a URL on a web service), it can receive GraphQL queries to validate and execute from clients. The service first checks a query to ensure it only refers to the types and fields defined for the API and then runs the provided functions to produce a result.

例如，查询：

¥For example, the query:

{
  me {
    name
  }
}

可以产生以下 JSON 结果：

¥Could produce the following JSON result:

{
  "data": {
    "me": {
      "name": "Luke Skywalker"
    }
  }
}

即使通过简单的查询，我们也可以看到使 GraphQL 如此强大的一些关键功能。客户端可以对 API 进行查询，以反映他们需要的数据结构，然后通过单个请求以预期的形状接收该数据 - 而不必担心哪些底层数据源提供了它。

¥With even a simple query, we can see some of the key features that make GraphQL so powerful. The client can make queries to the API that mirror the structure of the data that they need and then receive just that data in the expected shape with a single request—and without having to worry about which underlying data sources provided it.

无需版本控制即可改进你的 API

¥Evolve your API without versioning

客户端需求会随着时间而变化，GraphQL 允许你的 API 根据这些需求而发展，而无需管理不同 API 版本的开销。例如，如果新功能要求提供更具体的名称值，则可以按如下方式更新 User 类型：

¥Client requirements change over time and GraphQL allows your API to evolve in response to those needs and without the overhead of managing different API versions. For example, if a new feature calls for more specific name values to be available, then the User type could be updated as follows:

type User {
  fullName: String
  nickname: String
  name: String @deprecated(reason: "Use `fullName`.")
}

客户端工具将鼓励开发者使用新字段并删除已弃用的 name 字段的使用。一旦确定不再使用该字段，就可以将其删除；与此同时，GraphQL 将继续按预期提供其数据。

¥Client tooling will encourage developers to use the new fields and remove usage of the deprecated name field. The field can be removed once it is determined it is no longer used; in the meantime GraphQL will continue to provide its data as expected.

试试看！

¥Try it out!

学习 GraphQL 的最佳方法是开始编写查询。本指南中使用的查询编辑器是交互式的，因此请尝试将 id 和 appearsIn 字段添加到 hero 对象以查看更新的结果：

¥The best way to learn GraphQL is to start writing queries. The query editors used throughout this guide are interactive, so try adding an id and appearsIn fields to the hero object to see an updated result:

后续步骤

¥Next steps

现在你已经了解了一些关键的 GraphQL 概念，你已准备好了解其 类型系统 的所有不同方面。

¥Now that you know some key GraphQL concepts, you’re ready to learn about all of the different aspects of its type system.

有关实用教程的深入学习体验，请参阅 可用的培训课程。

¥For an in-depth learning experience with practical tutorials, see the available training courses.