go-graphql

Files (2)

• SKILL.md
• errors-auth-testing.md · references/

SKILL.md (first lines)

# Go GraphQL

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.

Detailed reference material, loaded on demand:

- `references/errors-auth-testing.md` — error presenter, field
  authorization directive, client-driven tests with query-count asserts.

Read a reference file only when the summary below is not enough.

## 1. Schema-First with gqlgen

The `.graphql` schema is the source of truth. gqlgen generates models,
resolver stubs, and the execution layer from it.

```bash
go get -tool github.com/99designs/gqlgen
go tool gqlgen init      # once
go tool gqlgen generate  # after every schema change
```

```yaml
# 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:

```bash
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.

## 2. Resolvers Stay Thin

A resolver translates a GraphQL request into a service call. It contains no
business logic and no SQL.

```go
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:

```go
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.

## 3. The N+1 Problem — the one that matters

A field resolver on a list type runs once per element.

```go
// ❌ 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.

```go
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.

```go

From eduardo-sl/go-agent-skills, MIT.

More from eduardo-sl/go-agent-skills