goql
goql is a GraphQL client library with built-in two-way marshaling support via struct tags. This is key because it allows for strongly typed GraphQL queries as opposed to variables containing a string representation of the query. This also facilitates more advanced features, such as sparse field sets.
For complete documentation see the generated pkg.go documentation. For a complete guide on the struct tag syntax, see the documentation found below under Defining GraphQL Operations.
Installation
In the root of your project repository (same directory as your go.mod and go.sum files):
go get github.com/getoutreach/goql
After that you should be able to import it anywhere within your project.
Defining GraphQL Operations
GraphQL operations can be defined by using normal Go struct types along with the help of struct tags. For example:
,sort:$sort<[String]>,size:$size,before:$before,after:$after)"`
}
">
type QueryUserCollection struct { UserCollection struct { Collection []struct { ID string Name string } `goql:"keep"` } `goql:"userCollection(filter:$filter<[Filter]>,sort:$sort<[String]>,size:$size,before:$before },after:$after )"`
when passed through the GraphQL query marshaller renders the following string:
query($filter: [Filter], $sort: [String], $size: Int, $before: String, $after: String) {
userCollection(filter: $filter, sort: $sort, size: $size, before: $before, after: $after) {
collection {
id
name
}
}
}
Here's the high-level steps to go through when first defining a GraphQL operation:
- Create a struct that will act as a wrapper for the entire operation. The top-level model will be the only immediate child struct field of this wrapper struct (e.g.
QueryUserCollection's only immediate child isUserCollectionwhich together represents thequery($filter: [Filter], ...) { userCollection(filter: $filter, ...) { ... } }part of the output). - Define all of the fields and sub-models of the top-level model as struct fields within the top-level model (e.g.
UserCollectioncontains children fields[]Collection,ID, andName). All types should match the types described in the schema of the query.IDin GraphQL is astringin Go.- Any type with the non-null (
!) restriction in GraphQL should be a non-pointer type in Go. Conversely, any type in GraphQL without this restriction should be nullable (a pointer type) in Go. - If the field is an integral part of the operation, e.g.
UserCollection, andCollectionfields in the struct above, add thegoql:"keep"tag to them to tell the marshaler to always include these fields. This is necessary in order for sparse field sets to work. However, in the example above the keep tag can actually be omitted from theUserCollectionpart of the query as it already defines an operation declaration, which the marshaler already sees as an integral part of the operation and implicitly marks it to be kept (that is why thekeeptag is left off of that portion, but onCollectionstill).
- Iterate through the fields and add
goqlstruct tags to further define the structure of the operation by modifying declarations, adding aliases, variables, or directives to each field. See the immediately proceeding section, GraphQL Struct Tag Syntax, for more information on these struct tags and how to define them.
GraphQL Struct Tag Syntax
The following components can be used alone or together, separated by a comma within in the tag, to define a goql struct tag for a field or model on an operation:
modelName(arg:$var, arg2:$var2 - Defines the name and argument list for a model. This is close to what you would see in a normal GraphQL operation, with a little syntactic sugar added to define the types of variables since they're needed in the wrapper of the operation when defining the variables used throughout it. This component implicitly defines the keep tag for the field as well, given that operation declarations are necessary regardless of sparse fieldset instructions.
MyModel struct `goql:"myModel(page:$page->query($page: Int!) { myModel(page: $page) { ...
fieldNameOverride- Overrides the name of a field, by default the lower camel-case version of the name of the struct field is used.
Name string `goql:"username"`->username
@alias(desiredAlias)- Adds an alias for a field or model, which will change the returned key in the JSON response from the GraphQL server. See the GraphQL documentation on aliases for more information.
- An alias is required when an operation name set by a goql tag diverges from the struct field name. Without an alias in that situation the data would not be able to be marshaled back into the struct field after the operation succeeds, resulting in a silent "error". As an example,
Role *Role `goql:"createRole(...)"`would need an alias since createRole (operation name) != Role (struct field name). Name string `goql:"@alias(username)"`->username: name
@include($flag)- Adds an include directive to the field or model. See the GraphQL documentation on directives for more information. Note that the variable passed to this directive in the struct tag does not have a type proceeding it in square brackets. This is because these directive variables always have the type of
Boolean!, so it is implied and therefore not necessary. Name string `goql:"@include($withName)"`->name @include(if: $withName)
- Adds an include directive to the field or model. See the GraphQL documentation on directives for more information. Note that the variable passed to this directive in the struct tag does not have a type proceeding it in square brackets. This is because these directive variables always have the type of
@skip($flag)- Adds a skip directive to the field or model. See the GraphQL documentation on directives for more information. Note that the variable passed to this directive in the struct tag does not have a type proceeding it in square brackets. This is because these directive variables always have the type of
Boolean!, so it is implied and therefore not necessary. Name string `goql:"@skip($withoutName)"`->name @skip(if: $withoutName)
- Adds a skip directive to the field or model. See the GraphQL documentation on directives for more information. Note that the variable passed to this directive in the struct tag does not have a type proceeding it in square brackets. This is because these directive variables always have the type of
keep- Tells the marshaler to keep this field regardless of what is requested in terms of sparse field sets.
Here is an example of using multiple struct tags together:
Name string `goql:"@alias(username),@include($withName)"` -> username: name @include(if: $withName)
Rules:
- The same component cannot be defined more than once in a singular struct tag.
Name string `goql:"@include($withName),@include($withName2)"`would result in an error because an include directive was defined twice on the same struct tag.
- All defined variables must only have one type each associated with them.
MyModel struct `goql:"myModel(page:$pagewould result in an error, since $page is defined to have both the type of)"` Int!andInt.MyModel struct `goql:"myModel(page:$pagewould also result in an error, since $page is defined to have the type of bothInt!andBoolean!(implicit when used in the include directive).
