Spring for GraphQL - Quick Reference

Full Reference: See advanced.md for DataLoader configuration, custom scalars, pagination implementation, GraphQL testing patterns, and subscription controllers.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: spring-graphql for comprehensive documentation.

Dependencies

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-graphql</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-websocket</artifactId> </dependency>

Configuration

spring: graphql: graphiql: enabled: true path: /graphiql schema: locations: classpath:graphql/**/ path: /graphql websocket: path: /graphql

Schema Definition

type Query { bookById(id: ID!): Book allBooks: [Book!]! }

type Mutation { createBook(input: CreateBookInput!): Book! }

type Book { id: ID! title: String! author: Author! }

input CreateBookInput { title: String! authorId: ID! }

Query Controller

@Controller public class BookController {

@QueryMapping
public Book bookById(@Argument String id) {
    return bookRepository.findById(id).orElse(null);
}

@QueryMapping
public List<Book> allBooks() {
    return bookRepository.findAll();
}

@SchemaMapping(typeName = "Book", field = "author")
public Author author(Book book) {
    return authorRepository.findById(book.getAuthorId()).orElse(null);
}

}

Mutation Controller

@Controller public class BookMutationController {

@MutationMapping
public Book createBook(@Argument CreateBookInput input) {
    return bookService.create(input);
}

}

BatchMapping (Solve N+1)

@Controller public class OptimizedBookController {

@BatchMapping
public Map<Book, Author> author(List<Book> books) {
    List<String> authorIds = books.stream()
        .map(Book::getAuthorId)
        .distinct()
        .toList();

    Map<String, Author> authorsById = authorRepository.findAllById(authorIds)
        .stream()
        .collect(Collectors.toMap(Author::getId, a -> a));

    return books.stream()
        .collect(Collectors.toMap(
            book -> book,
            book -> authorsById.get(book.getAuthorId())
        ));
}

}

Input Validation

@MutationMapping public Book createBook(@Argument @Valid CreateBookInput input) { return bookService.create(input); }

public record CreateBookInput( @NotBlank @Size(min = 1, max = 200) String title, @NotNull String authorId ) {}

Error Handling

@Component public class CustomExceptionResolver extends DataFetcherExceptionResolverAdapter {

@Override
protected GraphQLError resolveToSingleError(Throwable ex, DataFetchingEnvironment env) {
    if (ex instanceof BookNotFoundException) {
        return GraphqlErrorBuilder.newError(env)
            .errorType(ErrorType.NOT_FOUND)
            .message(ex.getMessage())
            .build();
    }
    return null;
}

}

Security

@Controller public class SecuredBookController {

@QueryMapping
@PreAuthorize("hasRole('USER')")
public List<Book> allBooks() {
    return bookRepository.findAll();
}

@MutationMapping
@PreAuthorize("hasRole('ADMIN')")
public Book createBook(@Argument CreateBookInput input) {
    return bookService.create(input);
}

}

When NOT to Use This Skill

• REST APIs - Use standard Spring MVC controllers

• Standalone GraphQL - Use graphql-java directly

• Simple CRUD - May be overkill, consider REST

• File uploads - GraphQL isn't optimized for large binary data

Anti-Patterns

Anti-Pattern Problem Solution

No @BatchMapping N+1 queries on nested fields Use @BatchMapping or DataLoader

Unbounded lists Memory exhaustion Implement pagination

Exposing entities Schema tightly coupled to DB Use DTOs/projections

No error handling Stack traces exposed Custom ExceptionResolver

GraphiQL in prod Security risk Disable in production

Quick Troubleshooting

Problem Diagnostic Fix

N+1 queries Check SQL logs Add @BatchMapping

Field not resolved Check method name Verify @SchemaMapping matches schema

Subscription not working Check WebSocket config Enable WebSocket support

Validation not applied Check @Valid Add @Validated to controller

Auth not working Check security config Add @PreAuthorize annotations

Best Practices

Do Don't

Use @BatchMapping for N+1 Fetch nested data individually

Define clear schema contracts Over-expose internal models

Implement pagination Return unbounded lists

Use input types for mutations Use many scalar arguments

Add proper error handling Expose stack traces

Production Checklist

• Schema well defined

• N+1 solved with BatchMapping

• Input validation enabled

• Error handling configured

• Security annotations applied

• Pagination implemented

• GraphiQL disabled in prod

• Query complexity limits

• Introspection controlled

Reference Documentation

• Spring for GraphQL Reference