graphql-go

You can test the compatibility of your implementation using the @apollo/federation-subgraph-compatibility tool.

1. Ensure your GraphQL server is running (e.g., at http://localhost:4001).
2. Run the compatibility test command against your endpoint.

npx @apollo/federation-subgraph-compatibility@1.2.1 pm2 --endpoint http://localhost:4001

To run a simple GraphQL server locally, create a main.go file with a schema definition and a resolver struct. Use graphql.MustParseSchema to initialize the schema and github.com/graph-gophers/graphql-go/relay to handle HTTP requests.

package main

import (
    "log"
    "net/http"

    graphql "github.com/graph-gophers/graphql-go"
    "github.com/graph-gophers/graphql-go/relay"
)

type query struct{}

func (query) Hello() string { return "Hello, world!" }

func main() {
    s := `
        type Query {
                hello: String!
        }
    `
    schema := graphql.MustParseSchema(s, &query{})
    http.Handle("/query", &relay.Handler{Schema: schema})
    log.Fatal(http.ListenAndServe(":8080", nil))
}

To avoid name collisions when the same field name exists in different operations (e.g., Query.hello and Mutation.hello), you can define a root resolver that returns specialized resolvers for each operation using the Query(), Mutation(), and Subscription() methods.

type RootResolver struct{}
type QueryResolver struct{}
type MutationResolver struct{}

func(r *RootResolver) Query() *QueryResolver {
    return &QueryResolver{}
}

func(r *RootResolver) Mutation() *MutationResolver {
    return &MutationResolver{}
}

func (*QueryResolver) Hello() string {
    return "Hello query!"
}

func (*MutationResolver) Hello() string {
    return "Hello mutation!"
}

schema := graphql.MustParseSchema(sdl, &RootResolver{}, nil)

The Social App example demonstrates how to use struct fields as resolvers instead of methods. To run the server locally, execute the following command and then navigate to http://localhost:8080 in your browser to interact with it.

go run ./example/social/server/server.go

This example demonstrates how to integrate graphql-go as an Apollo Federation subgraph. To run the full federation setup, you need to start two subgraphs and one gateway.

Prerequisites:

• Go v1.18
• Node.js v16.14.2
• yarn 1.22.18

Steps:

1. Start the first subgraph: go run ./example/apollo-federation/subgraph-one/server.go
2. Start the second subgraph: go run ./example/apollo-federation/subgraph-two/server.go
3. Start the gateway: cd example/apollo-federation/gateway && yarn start
4. Access the gateway at localhost:4000 to interact with the federated graph.

The library supports tracing via OpenTelemetry and OpenTracing. You can provide a tracer using the graphql.Tracer() option during schema parsing.

OpenTelemetry Example:

import (
    "github.com/graph-gophers/graphql-go"
    otelgraphql "github.com/graph-gophers/graphql-go/trace/otel"
)

_, err := graphql.ParseSchema(sdl, nil, graphql.Tracer(otelgraphql.DefaultTracer()))

OpenTracing Example:

import (
    "github.com/graph-gophers/graphql-go"
    "github.com/graph-gophers/graphql-go/trace/opentracing"
)

_, err := graphql.ParseSchema(sdl, nil, graphql.Tracer(opentracing.Tracer{}))

Once the Apollo Federation example is running, you can execute the following query at localhost:4000 to verify that data is being correctly aggregated from both subgraphs:

query {
  hello
  hi
}

Expected Result:

{
  "data": {
    "hello": "Hello from subgraph one!",
    "hi": "Hi from subgraph two!"
  }
}

To avoid N+1 problems or build projection lists for databases, resolvers can inspect which immediate child fields were requested using the following helpers (requires field selection capturing to be enabled, which is the default):

• graphql.SelectedFieldNames(ctx) []string: Returns names of direct child schema fields.
• graphql.HasSelectedField(ctx, "name") bool: Returns true if a specific field was requested.
• graphql.SortedSelectedFieldNames(ctx) []string: Returns a sorted copy of selected field names.

Note: These helpers are shallow and exclude meta fields like __typename.

To include custom metadata in GraphQL error responses, implement the ResolverError interface. This allows you to add an extensions field to the error JSON.

type ResolverError interface {
    error
    Extensions() map[string]any
}

type droidNotFoundError struct {
    Code    string `json:"code"`
    Message string `json:"message"`
}

func (e droidNotFoundError) Error() string {
    return fmt.Sprintf("error [%s]: %s", e.Code, e.Message)
}

func (e droidNotFoundError) Extensions() map[string]any {
    return map[string]any{
        "code":    e.Code,
        "message": e.Message,
    }
}