go-graphql

Go GraphQL

Both production-grade Go GraphQL libraries are schema-first: write SDL (.graphql), bind Go resolvers. Pick the library, write the schema deliberately, and treat DataLoaders + complexity limits as non-optional.

Core Rules

1. Schema is the contract. Design nullability and pagination once; clients depend on it forever. A change from nullable to non-null is a breaking change.
2. Resolvers are thin. Translate GraphQL input → domain call → GraphQL output. No SQL, no business logic.
3. DataLoaders are per-request. Construct in HTTP middleware, stash in context. A package-level DataLoader is a cross-tenant data leak.
4. Authenticate in middleware, authorize in the schema. HTTP middleware extracts identity; schema directives (or resolver checks) enforce per-field rules.
5. Subscriptions respect context. Every subscription goroutine selects on ctx.Done() and defer close(ch). Otherwise a disconnected client leaks a goroutine forever.
6. Production limits are non-optional. Set complexity caps; gate introspection by environment; never expose raw internal errors.

Library Decision

Library	Approach	Type safety	Build step	Pick when
github.com/99designs/gqlgen	Codegen	Compile-time	go generate	Large schemas, Federation, strict types
github.com/graph-gophers/graphql-go	Reflection	Parse-time	None	Small/medium schemas, simple pipeline
github.com/graphql-go/graphql	Code-first	Runtime	None	Avoid — verbose, no SDL

Read references/gqlgen.md for the codegen workflow, gqlgen.yml, DataLoaders, and Federation. Read references/graph-gophers.md for the reflection model, type mapping, and tracing.

Schema Design

type User {
  id: ID!                # opaque scalar; never expose Int
  email: String!         # server can always return this → non-null
  bio: String            # may be unset → nullable
  posts(first: Int = 10, after: String): PostConnection!
}

type CreateUserPayload {  # mutation envelope: business errors as data
  user: User
  errors: [UserError!]!
}

type PostConnection {     # Relay cursor pagination
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}