Ben Kraft
3a5bf46da4
## Summary: If your type implements an interface, we add getter methods for the shared fields, so that those may be accessed via the interface. But it turns out occasionally it's useful to have these getter methods when they don't implement a GraphQL interface, so you can use two genqlient-generated types in the same function if they have the same fields. (This comes up most often when you have a GraphQL union that maybe should really be an interface, or if you don't yet support interfaces implementing other interfaces (indeed our parser doesn't either). But one can imagine other use cases.) We can't predict how you want to do that, so we can't generate the interface, but we can generate the methods, so you can define the interface and do a type assertion from there. Since these methods are pretty simple to generate, we just do it always. (As with #120, if binary size becomes an issue we could later add an option to only generate methods that are truly needed but including them seems like the better default.) This also fixes a subtle and rare bug, which would have become much more common (indeed existing tests caught it). Specifically, if you have a query like ```graphql fragment FragmentOne on T { id } fragment FragmentTwo on T { id } query Q { f { # interface type T ...FragmentOne ...FragmentTwo } } ``` since both `FragmentOne` and `FragmentTwo` request some common field, say `id`, we generate a method `GetId` on each one. But since `FragmentOne` and `FragmentTwo` are both on `T`, we also include their interfaces in the interface we generate for the type of `f`, `QFT`. So `QFT` includes a method `GetId`. But on the implementations, the two methods conflict, and neither gets promoted; this causes various code to fail to compile. With this change, this would have happened much more frequently -- even if only one of the two fragments is on `T`, as long as both request the field. Anyway, we now generate explicit methods on each struct for all of its recursively emebedded fields -- using the logic from #120 to compute them -- so that we don't need to rely on method-promotion. ## Test plan: make tesc Author: benjaminjkraft Reviewers: csilvers, dnerdy, aberkan, jvoll, mahtabsabet, MiguelCastillo, StevenACoffman Required Reviewers: Approved By: csilvers, dnerdy Checks: ✅ Test (1.17), ✅ Test (1.16), ✅ Test (1.15), ✅ Test (1.14), ✅ Lint, ✅ Test (1.17), ✅ Test (1.16), ✅ Test (1.15), ✅ Test (1.14), ✅ Lint Pull Request URL: https://github.com/Khan/genqlient/pull/126
genqlient: a truly type-safe Go GraphQL client
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 welcomes contributions! Check out 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, notname; 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.