genqlient: a truly type-safe Go GraphQL client

This is a proof-of-concept of using code-generation to create a truly type-safe GraphQL client in Go. It is not yet ready for contributions (see docs/CONTRIBUTING.md).

What is genqlient?

genqlient is a Go library to easily generate type-safe code to query a GraphQL API. It takes advantage of the fact that both GraphQL and Go are typed languages to ensure at compile-time that your code is making a valid GraphQL query and using the result correctly, all with a minimum of boilerplate.

genqlient provides:

• Compile-time validation of GraphQL queries: never ship an invalid GraphQL query again!
• Type-safe response objects: genqlient generates the right type for each query, so you know the response will unmarshal correctly and never need to use interface{}.
• Production-readiness: genqlient is used in production at Khan Academy, where it supports millions of learners and teachers around the world.

How do I use genqlient?

You can download and run genqlient the usual way: go run github.com/Khan/genqlient. To set your project up to use genqlient, see the getting started guide, or the example. For more complete documentation, see the docs.

How can I help?

genqlient is not yet ready for contributions, but once it is, you'll be able to learn more in the (Contribution Guidelines), or file an issue on GitHub.

Why another GraphQL client?

Most common Go GraphQL clients have you write code something like this:

query := `query GetUser($id: ID!) { user(id: $id) { name } }`
variables := map[string]interface{}{"id": "123"}
var resp struct {
	Me struct {
		Name graphql.String
	}
}
client.Query(ctx, query, &resp, variables)
fmt.Println(query.Me.Name)
// Output: Luke Skywalker

This code works, but it has a few problems:

• While the response struct is type-safe at the Go level; there's nothing to check that the schema looks like you expect. Maybe the field is called fullName, not name; or maybe you capitalized it wrong (since Go and GraphQL have different conventions); you won't know until runtime.
• The GraphQL variables aren't type-safe at all; you could have passed {"id": true} and again you won't know until runtime!
• You have to write everything twice, or hide the query in complicated struct tags, or give up what type safety you do have and resort to interface{}.

These problems aren't a big deal in a small application, but for serious production-grade tools they're not ideal. And they should be entirely avoidable: GraphQL and Go are both typed languages; and GraphQL servers expose their schema in a standard, machine-readable format. We should be able to simply write a query and have that automatically validated against the schema and turned into a Go struct which we can use in our code. In fact, there's already good prior art to do this sort of thing: 99designs/gqlgen is a popular server library that generates types, and Apollo has a codegen tool to generate similar client-types for several other languages. (See docs/DESIGN.md for more prior art.)

genqlient fills that gap: you just specify the query, and it generates type-safe helpers, validated against the schema, that make the query.