go-graphqlBuild GraphQL servers in Go with gqlgen: schema-first generation, resolver structure, the N+1 problem and dataloaders, complexity and depth limits, error presentation, field-level authorization, and testing resolvers. Use when implementing or reviewing a GraphQL API, when a query fans out into hundreds of database calls, or when deciding what a resolver may…
Independent GitHub snapshot · Automated classification · Original documentation governs
GraphQL moves query planning to the client. That is the feature and the danger: one innocuous query can become ten thousand database round trips, and one over-permissive field can leak another tenant's data. Both are solved at the server, not in the schema review.
The .graphql schema is the source of truth. gqlgen generates models,
resolver stubs, and the execution layer from it.
go get -tool github.com/99designs/gqlgen
go tool gqlgen init # once
go tool gqlgen generate # after every schema change
# gqlgen.yml — bind generated types to your own models
models:
User:
model: github.com/myorg/app/internal/domain.User
ID:
model:
- github.com/99designs/gqlgen/graphql.ID
- github.com/99designs/gqlgen/graphql.Int64
Bind domain types explicitly. Left to itself gqlgen generates a parallel set of anaemic structs, and every resolver becomes a mapping function.
Commit generated code, and fail CI when it is stale:
go tool gqlgen generate && git diff --exit-code
Never edit generated.go or models_gen.go. resolver.go and the
*.resolvers.go files are yours.
A resolver translates a GraphQL request into a service call. It contains no business logic and no SQL.
func (r *queryResolver) User(ctx context.Context, id string) (*domain.User, error) {
u, err := r.users.Find(ctx, id)
if errors.Is(err, domain.ErrNotFound) {
return nil, nil // nullable field: absent, not an error
}
if err != nil {
return nil, fmt.Errorf("find user %s: %w", id, err)
}
return u, nil
}
Inject dependencies through the Resolver struct, never through package
globals:
type Resolver struct {
users UserService
orders OrderService
loader *Loaders
}
Always propagate ctx. It carries the request deadline, the authenticated
principal, and the per-request dataloaders.
A field resolver on a list type runs once per element.
// ❌ 1 query for the orders, then N queries for the users
func (r *orderResolver) Customer(ctx context.Context, obj *domain.Order) (*domain.User, error) {
return r.users.Find(ctx, obj.CustomerID)
}
Batch with a dataloader. It collects the keys requested within a short window and issues one query.
import "github.com/vikstrous/dataloadgen"
type Loaders struct {
UserByID *dataloadgen.Loader[string, *domain.User]
}
func NewLoaders(s UserService) *Loaders {
return &Loaders{
UserByID: dataloadgen.NewLoader(func(ctx context.Context, ids []string) ([]*domain.User, []error) {
return s.FindMany(ctx, ids) // ONE query for all ids
}, dataloadgen.WithWait(time.Millisecond)),
}
}
// ✅ 1 query for the orders, 1 for all customers
func (r *orderResolver) Customer(ctx context.Context, obj *domain.Order) (*domain.User, error) {
return loadersFrom(ctx).UserByID.Load(ctx, obj.CustomerID)
}
Loaders are per request, installed by middleware. A process-wide loader caches across users and leaks data between them.
func withLoaders(svc UserService, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ctx := context.WithValue(r.Context(), loadersKey{}, NewLoaders(svc))
next.ServeHTTP(w, r.WithContext(ctx))
})
}
The batch function must return results in the order of the keys it was given, with a nil entry and an error per missing key. Returning a shorter slice silently misaligns every result.
A public GraphQL endpoint without limits is a denial-of-service endpoint.
srv := handler.New(generated.NewExecutableSchema(cfg))
srv.AddTransport(transport.POST{})
srv.SetQueryCache(lru.New[*ast.QueryDocument](1000))
srv.Use(extension.FixedComplexityLimit(300))
srv.Use(extension.AutomaticPersistedQuery{Cache: lru.New[string](100)})
first. Start at a number your slowest legitimate query fits under,
then measure.user { orders { customer { orders ... } } })
must be bounded. gqlgen has no built-in depth limit; enforce it in an
operation middleware.extension.Introspection.
Do not install it in production, or gate it behind an authenticated role.Set srv.AroundOperations to enforce a per-operation timeout, and always run
behind an http.Server with ReadTimeout and WriteTimeout set.
GraphQL returns 200 with an errors array. Never leak internals into it.
srv.SetErrorPresenter(func(ctx context.Context, e error) *gqlerror.Error {
err := graphql.DefaultErrorPresenter(ctx, e)
var domainErr *domain.ValidationError
if errors.As(e, &domainErr) {
err.Message = domainErr.Message
err.Extensions = map[string]any{"code": "VALIDATION_FAILED"}
return err
}
slog.ErrorContext(ctx, "graphql resolver failed", "error", e)
err.Message = "internal server error" // stable, safe
err.Extensions = map[string]any{"code": "INTERNAL"}
return err
})
Use srv.SetRecoverFunc to convert a resolver panic into an error instead of
killing the connection, and log it with the stack.
Remember the nullability rule: an error on a non-null field nulls out its nearest nullable ancestor. Make a field non-null only when it can never legitimately be absent.
Object-level checks are not enough — a client can reach an object through several paths.
directive @hasRole(role: Role!) on FIELD_DEFINITION
type User {
id: ID!
email: String! @hasRole(role: ADMIN)
}
cfg.Directives.HasRole = func(ctx context.Context, obj any, next graphql.Resolver, role model.Role) (any, error) {
if !auth.FromContext(ctx).HasRole(role) {
return nil, gqlerror.Errorf("access denied")
}
return next(ctx)
}
Authenticate in HTTP middleware, before the GraphQL handler. Authorize in the directive or the resolver, using the principal from the context — never from a query argument.
func TestUserQuery(t *testing.T) {
c := client.New(handler.NewDefaultServer(generated.NewExecutableSchema(cfg)))
var resp struct {
User struct{ ID, Email string }
}
c.MustPost(`{ user(id: "u-1") { id email } }`, &resp)
require.Equal(t, "u-1", resp.User.ID)
}
Assert the query count for any resolver with a dataloader — that is the only way an N+1 regression fails a build rather than a dashboard:
require.Equal(t, 2, db.QueryCount(), "expected batched loads, got N+1")
gqlgen.ymlctx