golang-graphql

Files (3)

• SKILL.md
• gqlgen.md · references/
• graphql-go.md · references/

SKILL.md (first lines)

# Go GraphQL APIs

Work within the GraphQL implementation and schema workflow already selected by the project. Do not switch libraries or regenerate unrelated schema output.

## Establish the local contract

Before editing, inspect:

- `go.mod` and the selected GraphQL library version;
- schema files, generation configuration, generated-file policy, and generation command;
- HTTP/WebSocket construction, authentication middleware, authorization checks, and error presentation;
- resolver, batching, persistence, and test conventions.

Verify API names against the selected version's official documentation. Treat generated files as derived unless the repository documents otherwise.

## Follow the selected implementation

- For gqlgen generation, handler setup, error presentation, request-scoped loaders, and client tests, read [gqlgen recipes](references/gqlgen.md).
- For graph-gophers resolver signatures, scalar mapping, schema options, and direct execution tests, read [graph-gophers recipes](references/graphql-go.md).

Do not combine their resolver or middleware APIs: gqlgen validates generated interfaces at compile time, while graph-gophers validates reflected resolver signatures when the schema is parsed.

## Schema and resolver changes

- Preserve field nullability, pagination shape, error contract, and compatibility unless the user requests a breaking schema change.
- Make a field non-null only when the resolver contract can reliably supply it; remember that an error on a non-null field propagates null to a nullable ancestor.
- Treat omitted, explicit `null`, zero, and empty-list inputs as distinct when the schema does. Test coercion through the GraphQL executor rather than only calling the Go resolver.
- Keep resolvers focused on transport adaptation where the surrounding architecture separates domain logic.
- Avoid per-parent data access when a batch operation is available. Confirm batching with query-count or integration tests rather than assuming a loader removed N+1 behavior.
- Scope loader caches so data cannot cross user, tenant, request, or authorization boundaries. Per-request loaders are a common safe default, but a wider cache can be valid when its keying, invalidation, and access policy are explicitly correct.

## Authorization and error boundaries

Authentication at the transport layer does not authorize individual fields or objects. Enforce authorization at the layer that has the requested object and action, including nested resolvers and subscriptions. Test both allowed and denied paths.

Do not expose database errors, stack traces, secrets, or internal service details through GraphQL errors or extensions. Preserve useful public error codes while logging internal causes through the project's existing policy. Do not rely on introspection being disabled as an authorization control.

For browser clients using ambient credentials such as cookies, account for CSRF and origin policy on HTTP and WebSocket transports. Validate subscription identity for the lifetime required by the application's security model.

## Resource controls

Apply controls at the actual public trust boundary. Depending on the deployment, these may include:

- request body, variable, list-size, depth, complexity, concurrency, and execution-time limits;
- pagination caps and bounded batch sizes;
- rate limiting or operation allow-listing for exposed clients;
- bounded subscription counts, buffers, and cleanup on cancellation.

Choose limits from schema cost and workload measurements. Automatic persisted queries are a transport optimization unless the server separately enforces an operation allow-list; do not treat APQ alone as rejection of arbitrary queries.

Introspection policy is a product and operational decision. Disabling it may reduce casual discovery, but it does not replace authentication, authorization, validation, or resource limits.

## Subscriptions

Tie subscription work to the connection/request context. On cancellation, unsubscribe from upstream sources, stop owned goroutines, and close only channels owned by the resolver. Handle upstream channel closure explicitly; a receive from a closed channel must not become a busy loop. Define what happens when a client is slower than the producer instead of relying on an unbounded buffer.

## Verification

Use the project's generation command for schema changes, then compile and test the affected packages. Add focused tests for schema compatibility, resolver errors, authorization, batching, configured resource limits, subscription cancellation, and sanitized client errors. Execute a real query through the library test client or schema executor when coercion, directives, middleware, serialization, or error extensions matter; use HTTP/WebSocket only for transport behavior.

## Official references

- [gqlgen documentation](https://gqlgen.com/)
- [gqlgen package documentation](https://pkg.go.dev/github.com/99designs/gqlgen)
- [graph-gophers/graphql-go package documentation](https://pkg.go.dev/github.com/graph-gophers/graphql-go)
- [GraphQL specification](https://spec.graphql.org/)

From reagin/agent-skills, MIT.

More from reagin/agent-skills