Summary of the GrowingIO front end team’s practice with GraphQL

preface

There are many articles in the community on how GraphQL gets started and how it works, and the official websites of GraphQL and Apollo Client have more details. The community also analyzed the pros and cons of GraphQL compared to RESTful APIS (REST for short) from various aspects. This article is mainly from the front end perspective, under the premise that the front end development separation is prevalent today, we share some of the popular tools in the community to improve development efficiency and engineering quality, hope to have some help to friends who have decided to fall into GraphQL.

GraphQL Playground

When you first touch GraphQL, you must know about the Playground provided by GraphQL Server from the official documentation.

Playground is a complete browser-side GraphQL IDE, including Documentation, Schema, and an editor for writing and testing GraphQL requests.

For development teams using GraphQL, Playground is basically a substitute for API documentation such as Swagger and request emulation tools such as Postman. Is a complete development manual, and has the advantage of zero cost to use, and a team to maintain and iterate. Most GraphQL community implementations of GraphQL Server have a built-in Playground.

Apollo Client Devtool

Apollo Client Devtool is a Chrome plug-in for Apollo Client that captures queries and mutations sent by a page in the browser’s Console and provides the ability to edit, modify, and retry those requests. And, most importantly, the ability to view the GraphQL Client cache.

Because all GraphQL is sent to the same path and the Query Body is sent as a string, making the request less readable, Apollo Client Devtool is optimized compared to the traditional Network approach.

These two tools are essential to getting started, and are similar to the ones we use when interconnecting Restful apis to the front and back ends. GraphQL relies on Schema to provide more efficiency tools.

GrahpQL VS Code Plugin

Visual Studio Code (VS Code) Plugin GraphQL provides a complete set of functions, including syntax checking, syntax highlighting, reference jumps, Schema hover prompt, Autocomplete, and more. Is a required plugin.

An important feature is that when we define the Schema, the description of each parameter (some implementations insert the Schema through code comments) can be displayed in the IDE via the plugin’s prompt, which is the annotations that are required at both the front and back, including the description of the interface. Description of interface parameters can now be defined only once in the Schema.

The Plugin also provides a facility to execute queries and mutations within the IDE.

However, in my opinion, the practicability is limited. Query queries without parameters can be executed directly. For Query and Mutation that need to be passed in parameters, parameters need to be input in VS Code popover. However, for more complex structures you need to enter JSON format after Stringfy, and in many cases the parameters of the chained request depend on the previous request, making it harder to manually obtain the parameters needed to send the request.

These tools can help us make queries and write Queries more convenient, but they are not enough. We need tools to integrate Schema into the front-end engineering process to improve efficiency and code robustness.

GraphQL ESLint

The most basic front end code check for GraphQL ESLint is ESLint. Once we have a unified Schema, we can use the corresponding rules generated by the Schema to perform Query Syntax checks similar to those in Playground.

GraphQL Code Generator

GraphQL Code-Generator’s best way to improve the robustness of front-end Code is undoubtedly TypeScript, but writing out a full set of type files based on Schema can be a lot of work. The GraphQL Code Generator is a CLI tool for generating various language type files based on Schema. The tool itself implements the requirements for different languages and functions through Preset and Plugin. There are plenty of Preset and Preset plugins available for most of the development needs, as well as detailed documentation and examples for custom plugins. We’ll only discuss Typescript and related plugins here.

The core point is that the Type file generated with the Code Generator contains the Schema description. So when we use GraphQL to return data, Typescript prompts for a description of the data type. As shown below, the Description “Maximum 50 characters” in the Description field of the Event object is a comment written by the back end when the Schema is defined. Through this generated type file, it becomes a comment in the front-end Typescript type file. Can be referenced perfectly by the IDE. This means that when the backend student is writing code comments, they are also writing code comments for the front-end student.

Here’s how we can use these types of files, so that with the help of the VS Code Typescript plugin we can define the UseQuery pseudo-class to have full data type alerts when using the returned data. Autocomplete and specific descriptions of fields when defining schemas. This approach improves the development experience and efficiency compared to the traditional back-and-forth between projects and documents, and also improves the robustness of the code.

However, there is a problem with this approach. Careful friends may find that we only request the Name attribute of Events object when defining the Query, but the automatic prompt prompts all possible fields contained in Events, which cannot fully meet our requirements.

Let’s look at the type definition of the UseQuery method:

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

We accept two pseudo-classes, TData and TVaraibles, which we need to pass in when we use Hooks. If we want to return values based on Query definitions, we need to pass in a Pick or Exclude wrapper as the first parameter. Type from the root path is also required if Query or Mutation has an incoming parameter. TS to reference Input type, very troublesome.

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

query GetEvents{  events {    id    name  }}
Copy the code

Code-generator has a solution for this problem. Files generated with the typescript-operations Plugin will automatically exclude the default fields.

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 Pickexport type GetEventsQuery = { events? : SchemaTypes.Maybe<Array<SchemaTypes.Maybe<{ id: string, name? : SchemaTypes.Maybe<string> }>>> };Copy the code

For projects that use the React + Apollo Client, the typescript- React-apollo plugin can generate not only the type, but also the Query corresponding hook including the encapsulated UseQuery, UseLazyQuery can greatly improve the development efficiency under the premise of ensuring the integrity of the code type.

Code Generator has many plug-ins and configuration items, and it is easy to customize plugins. You can configure engineering solutions suitable for projects and teams according to project needs.

GraphQL Introspection

All of the tools mentioned above rely on the Introspection interface provided in the GraphQL standard. The capability of this interface is very simple. It specifies that the root of GraphQL requests is always the __schema node. You can use this node to query the contents of the entire Schema. Most of the tools in the community are also developed through the capabilities of this interface.

Introspection, interested friends can also refer to the official document of GraphQL to develop their own tools.

GraphQL Config

Finally, GraphQL Config, a configuration file that supports all graphQL-related tools. The GraphQL Config configuration file is supported by various types of files, such as Json, Yaml, Yml, JS, TS, etc. Most tools in the community already support the GraphQL Config file, and GraphQL official also recommends developers to use GraphQL Config as a configuration file. You can also use GraphQL Config as a configuration file if you are developing your own tools. It is convenient to rely on just one configuration file when using and sharing these tools in the GraphQL ecology.

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

conclusion

GraphQL gives front-end engineering more flexibility in requesting data, more robust type definitions, and more work to do with Typescript. However, with the support of the community, the reasonable use of the tools can greatly improve the efficiency and quality of the project on the premise of ensuring the safety of the front-end project type, and also solve some of the common problems of documentation and annotation from the side.

Refer to the directory

Apollo Grpahql (www.apollographql.com/)

Graphql-playground (Github.com/GraphQL/Gra…)

Apollo Client Devtools (Chrome.google.com/webstore/de…)

GraphQL VS Code Plugin (GraphQL – Visual Studio Marketplace)

Graphql-eslint (dotansimha/graphql-eslint)

Graphql-code-generator (www.graphql-code-generator.com/)

Graphql Orgnization (graphql.org/)

Graphql Config (graphql-config.com/)

                                                 

Author: Zhou Zhaoting/Front-end development engineer

Recruitment information

GrowingIO technology team is a dynamic and passionate team with multiple positions continuously open! We are looking for front end engineer/Big data engineer /Java engineer at 
. Interested students are welcome to submit their resume to [email protected] (please indicate the specific position name in the subject of email) 
. For more positions and information, please visit 
.

About GrowingIO

GrowingIO is a leading one-stop data growth engine solution provider in China. Founded in 2015, GrowingIO focuses on intelligent data analysis capabilities. By building a customer data platform, GrowingIO creates a closed-loop growth marketing system to help enterprises improve data-driven capabilities, enable business decisions and achieve business growth.