关于前端:GrowingIO-前端团队对于-GraphQL-的实践总结

前言

社区里已有很多无关 GraphQL 入门和原理的文章，GraphQL 和 Apollo Client 的官方网站也有较为具体的介绍。绝对于 RESTful API（简称 REST)，社区也从各个方面剖析了 GraphQL 的优劣利弊。本文次要是从前端角度登程，在现在前后端开发拆散流行的前提下，分享一些咱们如何利用社区中热门的工具进步开发效率和工程质量的教训，心愿对曾经信心入坑 GraphQL 的敌人们有一些帮忙。

GraphQL Playground

第一次接触 GraphQL 的时候肯定会从官网文档里理解到 GraphQL Server 所提供的 Playground。
Playground 是一个残缺的浏览器端 GraphQL IDE，包含 Documentation，Schema 和一个能够编写和测试 GraphQL 申请的编辑器。

对于应用 GraphQL 的开发团队，Playground 根本能够代替如 Swagger 之类的的 API 文档和如 Postman 之类的的申请模仿工具。是一个较齐备的开发手册，并且长处是零老本应用，并且有团队在保护和迭代。GraphQL 社区绝大多数对于 GraphQL Server 的实现都会内置 Playground。

Apollo Client Devtool

Apollo Client Devtool 是 Apollo Client 提供的一款 Chrome 插件，能够在浏览器的 Console 中捕获页面发送的 Query 和 Mutation，并且提供了编辑，批改和重试这些申请，还有最重要的查看 GraphQL Client 缓存的性能。
因为所有的 GraphQL 都是发送给对立的门路，Query Body 也是以字符串的模式发送，使得申请的可读性很差，Apollo Client Devtool 相较于通过传统 Network 的形式做了优化。
以上两个工具能够说是入门必备，相似咱们前后端对接 Restful Api 时咱们会用到的工具。GraphQL 依赖 Schema 提供了更多的提效工具。

GrahpQL VS Code Plugin

Visual Studio Code（简称 VS Code）Plugin GraphQL 提供了相当齐全的性能，包含语法查看，语法高亮，援用跳转，Schema 悬浮提醒，Autocomplete 等。是一个必装的插件。
很重要的一个性能是，当咱们在定义 Schema 的时候对每一个参数所定义的形容（有的实现是通过代码正文的形式插入 Schema）是能够通过这个插件的提醒在 IDE 里展现的，也就是本来前后两端都须要的正文内容，包含对接口的形容，对接口参数的形容等，当初能够只用在 Schema 里定义一遍就能够了。

该 Plugin 还提供了一个能够在 IDE 内执行 Query 和 Mutation 的性能。

然而集体认为实用性无限，对于不含参数的 Query 查问能够间接执行，对于须要传入参数的 Query 和 Mutation 须要在 VS Code 的弹窗中输出参数，如果是较为简单的字符串或者数字参数比拟不便，然而如果是较为简单的构造体就须要输出 Stringfy 过后的 JSON 格局，并且很多状况下链式申请的参数依赖上一个申请，发送申请所需的参数就更不容易手动获取了。

以上工具能够帮忙咱们更不便的查问和编写 Query，但只有这些性能还是远远不够的，咱们须要借助工具将 Schema 融入前端工程化的过程，提效的同时进步代码的健壮性。

GraphQL ESLint

GraphQL ESLint 最根底的前端代码查看就是 ESLint，咱们有了对立的 Schema 之后，就能够通过 Schema 生成的对应的规定来对 Query 进行相似 Playground 中 Syntax 查看。

GraphQL Code Generator

GraphQL Code-Generator 最能进步前端代码健壮性的办法无疑是 TypeScript，然而依据 Schema 手写我的项目全套的类型文件会有很大的工作量，GraphQL Code Generator 是一个依据 Schema 生成各类语言类型文件的 cli 工具，工具自身是通过 Preset 和 Plugin 的形式来实现针对不同语言和性能的需要，官网自身也提供了很丰盛的 Preset 和 Plugin 能够满足大部分的开发需要，自定义 Plugin 也有较为具体的文档和示例。这里咱们只探讨 Typescript 和相干的 Plugin。

最外围的一点是通过 Code Generator 生成的 Type 文件是蕴含 Schema 形容的。所以咱们在应用 GraphQL 返回的数据时，Typescript 是会提醒数据类型的形容的。如下图，对于 Event 对象中 Description 字段的形容“Maximum 50 characters”是后端在定义 Schema 时写的正文，通过这个生成的类型文件，成为了前端 Typescript 类型文件中的正文，能够被 IDE 完满援用。等于说后端同学在写代码正文时，也在帮前端同学写代码正文。

上面就是咱们该如何应用这些类型文件的问题，以在 VS Code Typescript 插件的帮忙下咱们在应用 UseQuery Hook 时，定义好 UseQuery 的伪类 就能够在应用返回数据时领有残缺的数据类型揭示，Autocomplete 和定义 Schema 时对字段的具体形容。这种形式在开发体验和效率上相比传统在我的项目和文档间来回切换进步了很多，也同时加强了代码的健壮性。
然而这种形式也存在一个问题，就是仔细的敌人可能发现咱们在定义 Query 的时候只申请了 Events 对象的 Name 属性，然而主动提醒却提醒了 Events 蕴含的所有可能字段，并不能齐全满足咱们的要求。

咱们看一下 UseQuery 办法的类型定义:

useQuery: TData = any, TVariables = OperationVariables: (query: DocumentNode | TypedDocumentNode<TData, TVariables>, options?: QueryHookOptions<TData, TVariables>): QueryResult<TData, TVariables>;

承受两个伪类 TData 和 TVaraibles，咱们须要在应用 Hooks 的时候传入这两个参数，如果要依据 Query 来自定义返回值，咱们须要在第一个参数传入被 Pick 或 Exclude 包装过后的类型，如果 Query 或 Mutation 有传入参数也须要从根门路的 Type。TS 去援用 Input 的类型，十分麻烦。

 {events: Pick<Event, 'name'>[]}
query GetEvents{
  events {
    id
    name
  }
}

Code-Generator 针对这个问题也有相应的计划，通过 Typescript-Operations 这个 Plugin 生成的文件生成的类型文件会主动排除缺省的字段。

export type GetEventsQueryVariables = SchemaTypes.Exact<{[key: string]: never; }>;

// With Pick 
export type GetEventsQuery = {events?: SchemaTypes.Maybe<Array<SchemaTypes.Maybe<Pick<SchemaTypes.Event, 'id' | 'name'>>>>};

// Without Pick
export type GetEventsQuery = {events?: SchemaTypes.Maybe<Array<SchemaTypes.Maybe<{ id: string, name?: SchemaTypes.Maybe<string>}>>> };

对于应用 React + Apollo Client 的我的项目，typescript-react-apollo plugin 不仅能够生成类型，还能够能够生成和 Query 绝对应的申请的 hook 包含封装好的 UseQuery，UseLazyQuery 等，能够在保障代码类型残缺的前提下极大的进步开发效率。

Code Generator 的插件很多，配置项也很多，自定义 Plugin 也比拟容易，能够依据依据我的项目须要，配置出适宜我的项目适宜团队的工程化计划。

GraphQL Introspection

以上提到的所有工具都是依附 GraphQL 规范中提供的 Introspection 接口实现的，该接口的能力其实也很简单明了，就是规定了对于 GraphQL 申请的根部永远是 __schema 节点，能够通过这个节点来查问整个 Schema 的内容。社区里的绝大部分工具也都是通过这个接口的能力开发。
Introspection，感兴趣的敌人也能够参考 GraphQL 的官网文档去开发适宜本人的工具。

GraphQL Config

最初要提的是 GraphQL Config，一份配置文件反对所有和 GraphQL 相干的工具。该配置文件反对多种文件类型，例如 Json、Yaml、Yml、JS、TS 等等，社区里大部分工具都已反对 GraphQL Config 配置文件，GraphQL 官网也倡议开发者应用 GraphQL Config 来作为配置文件。如果开发本人的工具也能够应用 GraphQL Config 作为配置文件。咱们在应用和分享 GraphQL 生态中的这些工具时，只依赖一份配置文件是十分不便的。

schema: './schema/*.GraphQL'
extensions:
  codegen:
    generates:
      ./src/types.ts:
        plugins:
          - typescript
          - typescript-resolvers

总结

GraphQL 给予了前端工程在申请数据方面更好的灵活性，更为健全的类型定义，同时也为应用 Typescript 带来了更多的工作量。然而在社区的反对下，正当的使用工具能够在保障前端我的项目类型平安的前提下，极大的进步工程效率和工程质量，也从侧面解决了一些陈词滥调的文档问题和正文问题。

参考目录

Apollo Grpahql (https://www.apollographql.com…
Graphql-playground (https://github.com/GraphQL/Gr…
Apollo Client Devtools (https://chrome.google.com/web…
GraphQL VS Code Plugin (GraphQL – Visual Studio Marketplace)
Graphql-eslint (dotansimha/graphql-eslint)
Graphql-code-generator (https://www.graphql-code-gene…
Graphql Orgnization (https://graphql.org/)
Graphql Config (https://graphql-config.com/)

作者：周兆庭 / 前端开发工程师

招聘信息

GrowingIO 技术团队是一个生机四射、对技术充斥激情的团队，多个岗位继续招聘中！诚招前端工程师 / 大数据工程师 /Java 工程师等，欢送有趣味的同学投递简历至：jianli@growingio.com（邮件题目请注明具体岗位名称），更多职位及信息可进入招聘官网查看


对于 GrowingIO

GrowingIO 是国内当先的一站式数据增长引擎整体计划服务商，创建于 2015 年，以数据智能剖析能力为外围，通过构建客户数据平台，打造增长营销闭环，帮忙企业晋升数据驱动能力，赋能商业决策、实现业务增长。