从混乱到秩序的前端

Source: Dev.to

工作原理

• 后端更新微服务的 GraphQL schema。
• 前端拉取最新的 schema，生成查询/变更并重新生成类型。
• 所有破坏性更改都会在前端构建之前被捕获。

这种做法使我们能够在 前端构建阶段 检测到后端查询与响应之间的所有不匹配，远早于运行时。

创建方式

要集成类型生成，需要在项目中添加以下依赖：

• @graphql-codegen/cli
• @graphql-codegen/typescript
• @graphql-codegen/typescript-document-nodes
• @graphql-codegen/typescript-operations

类型生成和更新通过 GraphQL Code Generator 的 YAML 配置文件进行配置。

从本地 schema 生成类型

# Should existing files be overwritten after generation
overwrite: true
generates:
  # Path to the generated output
  src/generated/schema.graphql.ts:
    # Path to the GraphQL schema
    schema: ./graphql-schema/schema.graphql
    # GraphQL documents (queries/mutations) to parse in the project
    documents: src/**/*.graphql
    plugins:
      - typescript
      - typescript-operations
      - typescript-document-nodes

从 introspection 端点生成类型

overwrite: true
generates:
  src/generated/introspection.graphql.ts:
    # GraphQL endpoint URL
    schema: "http://localhost:4000/graphql"
    documents: "src/**/*.graphql"
    plugins:
      - typescript
      - typescript-operations
      - typescript-document-nodes

运行生成

在 package.json 中定义便捷脚本：

{
  "scripts": {
    "codegen:schema": "npx graphql-codegen --config codegen-schema.yml",
    "codegen:introspection": "npx graphql-codegen --config codegen-introspection.yml"
  }
}

示例用法

GraphQL 查询

query GetOpportunities($request: GetOpportunitiesRequestInput!) {
  opportunities(request: $request) {
    statusCode
    message
    data {
      contractNumber
      creationDate
    }
  }
}

类型安全的变量和查询执行（TypeScript）

// Type-safe variables
const variables: GetOpportunitiesThemesQueryVariables = {
  providerId: test1,
  keycloakUserId: test2,
};

// Query using Apollo (example from the project)
this.apollo
  .watchQueryWithService('accreditationService', {
    query: GetOpportunitiesThemes,
    variables,
  });

结论

将 GraphQL Code Generator 与严格的后端部署工作流结合使用，能够让前端团队与后端更改保持同步，在构建阶段捕获不匹配，并显著降低手动调试的工作量。

该方法既适用于基于 SDL 的工作流，也适用于基于 introspection 的工作流，并且能够很好地扩展到拥有多个微服务的项目。

欢迎在自己的项目中尝试此配置，并分享你的想法或其他替代方案！