GraphQL 和 Swagger 之间的比较和工作方式

随着前端技术的发展，越来越多的应用程序需要与后端进行交互。在这个过程中，API 是连接前端和后端的重要桥梁。在 API 设计中，GraphQL 和 Swagger 是两种流行的选择。本文将比较这两种技术的工作方式，并提供深度学习和指导意义。

GraphQL

GraphQL 是一种用于 API 的查询语言。它允许客户端指定需要获取的数据，并以所需的形式返回。GraphQL 具有以下特点：

• 客户端可以精确指定需要获取的数据，从而避免了不必要的数据传输。
• GraphQL 支持多个查询，从而减少了网络请求。
• GraphQL 具有强大的类型系统，可以在编译时检查查询的正确性，避免运行时错误。

以下是一个 GraphQL 查询的示例：

// www.javascriptcn.com code example
query {
  user(id: "123") {
    name
    email
    posts {
      title
      content
    }
  }
}

这个查询将返回一个用户的名称、电子邮件和帖子列表。该查询具有明确的结构，客户端只获取所需数据。

Swagger

Swagger 是一种用于描述 API 的语言。它允许开发人员定义 API 的各个方面，包括输入参数、输出响应、错误代码等。Swagger 具有以下特点：

• Swagger 可以自动生成客户端和服务器代码，从而加快了开发速度。
• Swagger 具有强大的文档功能，可以帮助开发人员理解和使用 API。
• Swagger 支持多种格式，包括 JSON 和 YAML。

以下是一个 Swagger API 描述的示例：

// www.javascriptcn.com code example
paths:
  /users/{id}:
    get:
      summary: Get a user by ID
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the user to get
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
    Post:
      type: object
      properties:
        title:
          type: string
        content:
          type: string

这个 Swagger 描述定义了一个获取用户信息的 API，包括输入参数、输出响应和数据模型。

比较

GraphQL 和 Swagger 在 API 设计中有不同的使用场景。GraphQL 更适用于需要精确控制数据获取的场景，而 Swagger 更适用于需要自动生成代码和文档的场景。以下是它们的比较：

• 查询方式：GraphQL 使用查询语言进行查询，Swagger 使用 HTTP 请求进行查询。
• 数据获取：GraphQL 允许客户端精确指定需要获取的数据，Swagger 通常返回完整的数据模型。
• 自动生成代码：Swagger 可以自动生成客户端和服务器代码，GraphQL 需要手动编写代码。
• 错误处理：GraphQL 返回详细的错误信息，Swagger 返回标准的 HTTP 错误码。

工作方式

GraphQL 和 Swagger 在后端实现方式上也有不同。以下是它们的工作方式：

• GraphQL：在后端实现 GraphQL 时，需要定义数据模型和查询语句。GraphQL 服务器将查询语句转换为数据库查询，并返回所需的数据。GraphQL 还提供了订阅和变更等高级功能。
• Swagger：在后端实现 Swagger 时，需要定义 API 描述。Swagger 服务器使用这个描述来生成代码和文档，并将请求转发给实际的处理程序。

指导意义

在实际应用中，GraphQL 和 Swagger 都有自己的优点和缺点。以下是一些指导意义：

• 如果应用需要精确控制数据获取，或者需要高级功能（如订阅和变更），则使用 GraphQL。
• 如果应用需要自动生成代码和文档，或者需要与其他 Swagger 兼容的应用程序进行交互，则使用 Swagger。
• 在实际应用中，可以使用 GraphQL 和 Swagger 的组合，以获取它们的优点并弥补它们的缺点。

示例代码

以下是一个使用 GraphQL 和 Swagger 的示例代码：

// www.javascriptcn.com code example
import { gql } from 'graphql-request';
import SwaggerClient from 'swagger-client';

const graphqlQuery = gql`
  query {
    user(id: "123") {
      name
      email
      posts {
        title
        content
      }
    }
  }
`;

const swaggerClient = await SwaggerClient({
  url: 'http://example.com/swagger.json',
});

const swaggerResponse = await swaggerClient.apis.users.getUser({ id: '123' });

console.log(graphqlResponse.data.user);
console.log(swaggerResponse.body);

这个代码示例使用了 GraphQL 和 Swagger，分别查询了一个用户的信息。

来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/67d5a8f2a941bf7134ad10a7