Spring Boot 4 Complete Guide · Leçon

Récupérateurs de données et liaison des arguments

Implémentez des gestionnaires @QueryMapping et @MutationMapping avec liaison des arguments et des entrées.

Leçon 2 sur 413 étapes

Récupérateurs de données et liaison des arguments est une leçon Spring Boot 4 Complete Guide gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Spring Boot 4 Complete Guide, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Spring Boot 4 Complete Guide comprend 4 leçons au total.

Certaines parties de cette leçon n'ont pas encore été traduites et s'affichent en anglais.

What a Data Fetcher Is

In Spring for GraphQL, every field in your schema is resolved by a data fetcher (the GraphQL-Java term for a resolver). When a client asks for a field, the engine invokes the fetcher bound to it.

Instead of registering raw DataFetcher beans, Spring lets you write annotated controller methods. The framework maps each method to a schema field and handles argument binding, return values, and async wrapping for you.

@QueryMapping resolves a field under the root Query type.
@MutationMapping resolves a field under the root Mutation type.
@SchemaMapping resolves any field (including nested object fields).

The Schema Drives Everything

Spring for GraphQL is schema-first. You declare your types and operations in an SDL file under src/main/resources/graphql/ (for example schema.graphqls), and your controller methods bind to those field names.

Consider this schema. The book and books fields live under Query, so each needs a @QueryMapping handler.

type Query {
    books: [Book!]!
    book(id: ID!): Book
}

type Mutation {
    addBook(input: AddBookInput!): Book!
}

type Book {
    id: ID!
    title: String!
    pages: Int!
}

input AddBookInput {
    title: String!
    pages: Int!
}

Your First @QueryMapping

A @Controller class holds your handlers. By default, Spring infers the schema field name from the method name, so books() binds to the books query.

The return value is matched against the schema's return type. Here List<Book> satisfies [Book!]!.

@Controller
public class BookController {

    private final BookService bookService;

    public BookController(BookService bookService) {
        this.bookService = bookService;
    }

    @QueryMapping
    public List<Book> books() {
        return bookService.findAll();
    }
}

Binding a Single Argument with @Argument

When a query field takes arguments, bind each one with @Argument. Spring matches the GraphQL argument name to the parameter name and coerces the value to the Java type.

For book(id: ID!), the ID scalar arrives as a String by default. Spring can also coerce it to Long if your parameter is typed that way.

@QueryMapping
public Book book(@Argument Long id) {
    return bookService.findById(id)
            .orElseThrow(() -> new BookNotFoundException(id));
}

When Argument and Parameter Names Differ

Parameter-name matching depends on debug symbols being present in the compiled class. If they are stripped, or if you simply want a different Java name, set the argument name explicitly.

@Argument("id") binds the schema argument id to whatever parameter you declare.
Compiling with the -parameters flag (the Spring Boot starter parent enables it) keeps names available, so the explicit form is often optional.

@QueryMapping
public Book book(@Argument("id") Long bookId) {
    return bookService.findById(bookId)
            .orElseThrow(() -> new BookNotFoundException(bookId));
}

Binding Input Objects to a POJO

For mutations that accept an input object, you do not bind each field separately. Instead, @Argument binds the whole GraphQL input type to a Java class. Spring populates the object field-by-field using the matching property names.

The target class just needs fields (or a constructor) matching the input's keys. A record works perfectly.

public record AddBookInput(String title, int pages) {}

@MutationMapping
public Book addBook(@Argument AddBookInput input) {
    Book created = bookService.create(input.title(), input.pages());
    return created;
}

@MutationMapping in Practice

@MutationMapping works exactly like @QueryMapping but resolves fields under the root Mutation type. Use it for operations that change state: create, update, delete.

You can mix simple scalar arguments and input objects freely. Below, an update takes both an ID and an input payload.

@MutationMapping
public Book updateBook(@Argument Long id, @Argument UpdateBookInput input) {
    Book existing = bookService.findById(id)
            .orElseThrow(() -> new BookNotFoundException(id));
    existing.setTitle(input.title());
    existing.setPages(input.pages());
    return bookService.save(existing);
}

Whole-Argument-Map Binding with @Arguments

Sometimes you want the complete set of arguments bound to a single object rather than calling @Argument repeatedly. The @Arguments (plural) annotation binds all field arguments onto one target class at once.

This is handy when a query has many filter parameters that map cleanly to a criteria object.

public record BookFilter(String titleContains, Integer minPages, Integer maxPages) {}

@QueryMapping
public List<Book> searchBooks(@Arguments BookFilter filter) {
    return bookService.search(filter);
}

Validating Bound Arguments

Spring for GraphQL integrates with Bean Validation. Annotate the controller method argument or the input record components with constraints, and add @Valid so violations are checked before your method body runs.

A failed constraint produces a GraphQL error rather than executing your business logic, keeping bad data out of the service layer.

public record AddBookInput(
        @NotBlank String title,
        @Positive int pages) {}

@MutationMapping
public Book addBook(@Argument @Valid AddBookInput input) {
    return bookService.create(input.title(), input.pages());
}

Accessing the Raw Arguments Map

For dynamic cases you can skip typed binding and inject the DataFetchingEnvironment (or an @Argument Map<String, Object>). The environment exposes the raw arguments, the selection set, and context.

Use this sparingly — typed binding with @Argument is clearer and safer. Reach for the environment only when you genuinely need engine-level details.

@QueryMapping
public Book book(DataFetchingEnvironment env) {
    Long id = Long.valueOf(env.getArgument("id").toString());
    return bookService.findById(id)
            .orElseThrow(() -> new BookNotFoundException(id));
}

A Standalone Argument-Coercion Demo

Argument binding is, at its core, coercing incoming values into Java types. The snippet below mimics that idea without any framework: it parses an ID-like string argument into a long and looks it up — exactly what @Argument Long id does under the hood.

This runs on a plain online judge to make the concept concrete.

import java.util.Map;

public class Main {
    record Book(long id, String title) {}

    public static void main(String[] args) {
        Map<Long, Book> store = Map.of(
            1L, new Book(1, "Spring in Action"),
            2L, new Book(2, "Effective Java")
        );

        String rawIdArgument = "2"; // as it would arrive from GraphQL
        long id = Long.parseLong(rawIdArgument);

        Book found = store.get(id);
        System.out.println(found != null ? found.title() : "not found");
    }
}

Quick Check

You have a mutation addBook(input: AddBookInput!): Book! where AddBookInput has fields title and pages. You want to bind the entire input object to a single Java record in one handler. What is the correct signature?

Réponds-y dans la leçon interactive

Recap

You can now wire GraphQL fields to Java handlers in Spring for GraphQL:

@QueryMapping and @MutationMapping bind controller methods to root Query/Mutation fields, inferring the field name from the method name.
@Argument binds a single GraphQL argument or an entire input object to a Java type; use the explicit name form when parameter names are unavailable.
@Arguments binds the full set of field arguments onto one target object.
@Valid plus Bean Validation constraints reject bad input before your service runs.
The DataFetchingEnvironment exposes raw arguments for dynamic cases, but typed binding should be your default.

Gratuit pour commencer

Apprends Java avec un tuteur IA — gratuit

Écris et exécute du vrai code dans ton navigateur, obtiens de l'aide instantanée d'un tuteur IA disponible 24h/24, et reprends là où tu t'es arrêté sur le web ou dans l'app.

Cours: 21
Leçons: 84

Commencer gratuitement Voir le cours complet

Questions Fréquemment Posées

La leçon « Récupérateurs de données et liaison des arguments » est-elle gratuite ?

Oui — le texte complet de « Récupérateurs de données et liaison des arguments » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Spring Boot 4 Complete Guide, passe à CoddyKit PRO. Le cours Spring Boot 4 Complete Guide comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Récupérateurs de données et liaison des arguments » ?

Implémentez des gestionnaires @QueryMapping et @MutationMapping avec liaison des arguments et des entrées. Tu pratiques Spring Boot 4 Complete Guide avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer Spring Boot 4 Complete Guide ?

Aucune expérience préalable n'est requise. Spring Boot 4 Complete Guide sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.

Combien de temps prend la leçon « Récupérateurs de données et liaison des arguments » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon Spring Boot 4 Complete Guide ?

Oui. Chaque leçon Spring Boot 4 Complete Guide inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

Conception centrée sur le schéma et mappage des types
Récupérateurs de données et liaison des arguments
Résolution du problème N+1 avec des chargeurs par lots
Abonnements, erreurs et sécurité du schéma

← Retour à Spring Boot 4 Complete Guide