---

name: spring-graphql description: | Spring for GraphQL - building GraphQL APIs with Spring Boot. Covers queries, mutations, subscriptions, @BatchMapping, DataLoader, and security.

USE WHEN: user mentions "spring graphql", "@QueryMapping", "@MutationMapping", "@SubscriptionMapping", "@BatchMapping", "GraphQL Spring Boot", "N+1 GraphQL"

DO NOT USE FOR: REST APIs - use standard Spring MVC, standalone GraphQL - use graphql-java skill allowed-tools: Read, Grep, Glob, Write, Edit

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