Spring Boot 4 Complete Guide · Lektion

Schema-First-Design und Typzuordnung

Definieren Sie ein GraphQL-Schema und ordnen Sie Typen, Queries und Mutations Java-Controller-Methoden zu.

Schema-First-Design und Typzuordnung ist eine kostenlose Spring Boot 4 Complete Guide-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des Spring Boot 4 Complete Guide-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der Spring Boot 4 Complete Guide-Kurs umfasst insgesamt 4 Lektionen.

Teile dieser Lektion wurden noch nicht übersetzt und werden auf Englisch angezeigt.

Schema-First in Spring for GraphQL

Spring for GraphQL is schema-first: you describe your API in a .graphql Schema Definition Language (SDL) file, and your Java code maps onto it.

The schema is the single source of truth for the API contract.
Clients ask for exactly the fields they need.
Your controllers provide the data behind each field.

By convention, Spring Boot auto-discovers .graphqls / .graphql files under src/main/resources/graphql/.

Defining Object Types in SDL

A GraphQL object type describes the shape of an entity. Each field has a name and a type.

ID, String, Int, Float, Boolean are the built-in scalars.
A trailing ! marks a field as non-null.
[Type] denotes a list.

Place this in src/main/resources/graphql/schema.graphqls.

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

type Author {
    id: ID!
    name: String!
    books: [Book!]!
}

The Query Root Type

Every read operation lives under the special Query root type. Each field of Query is an entry point a client can call.

Fields can take arguments, e.g. bookById(id: ID!).
The return type can be a single object, a list, or a scalar.

A nullable return (no !) is appropriate when the entity may not exist.

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

Mapping a Query to a Controller

Spring for GraphQL maps schema fields to Java methods using annotated controllers. A class annotated with @Controller exposes handler methods with @QueryMapping.

The method name must match the schema field, or you set @QueryMapping("fieldName").
Arguments are bound with @Argument.

This is framework code (it needs the Spring runtime), so it is not standalone-runnable.

@Controller
public class BookController {

    private final BookRepository books;

    public BookController(BookRepository books) {
        this.books = books;
    }

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

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

Type Mapping: SDL to Java

Spring maps GraphQL types to Java types by field name, not by inheritance. Your POJO (record or class) just needs matching accessors.

SDL String → Java String
SDL Int → Java int / Integer
SDL ID → usually String (or Long coerced)
SDL [Book!]! → List<Book>

A Java record is the cleanest representation of a GraphQL object type.

public record Book(
    String id,
    String title,
    Integer pageCount,
    String authorId
) {}

public record Author(
    String id,
    String name
) {}

Argument Binding Details

The @Argument annotation binds a named schema argument to a method parameter.

By default the parameter name must match the argument name (requires -parameters compilation, on by default in Spring Boot).
Override explicitly with @Argument("titleContains").
Complex input types bind to a Java record or class automatically.

Spring coerces the incoming GraphQL value to your parameter's Java type.

@QueryMapping
public List<Book> searchBooks(@Argument("titleContains") String fragment) {
    return books.findAll().stream()
        .filter(b -> b.title().toLowerCase().contains(fragment.toLowerCase()))
        .toList();
}

Resolving Nested Fields with @SchemaMapping

When a field needs extra work beyond a simple getter (e.g. Book.author must be looked up), use @SchemaMapping. The source object is passed as a parameter.

The method's class/type is inferred from the parameter type, or set via @SchemaMapping(typeName = "Book").
This solves the N+1 concern by letting you batch later with @BatchMapping.

Here, each Book resolves its author field on demand.

@SchemaMapping
public Author author(Book book) {
    return authorRepository.findById(book.authorId())
        .orElseThrow(() -> new IllegalStateException("Author missing"));
}

Defining Mutations in SDL

Write operations live under the Mutation root type. They typically accept an input object and return the created or updated entity.

Use a dedicated input type for arguments — input types cannot have fields that reference object types.
Returning the mutated entity lets clients re-fetch fresh state in one round trip.

input AddBookInput {
    title: String!
    pageCount: Int
    authorId: ID!
}

type Mutation {
    addBook(input: AddBookInput!): Book!
    deleteBook(id: ID!): Boolean!
}

Mapping a Mutation to a Controller

Mutations map with @MutationMapping. A GraphQL input type binds cleanly to a Java record via @Argument.

The record field names must match the SDL input field names.
Return the entity to satisfy the non-null Book! result.

Still framework code — needs Spring's GraphQL runtime, so not standalone-runnable.

public record AddBookInput(String title, Integer pageCount, String authorId) {}

@MutationMapping
public Book addBook(@Argument AddBookInput input) {
    Book created = new Book(
        UUID.randomUUID().toString(),
        input.title(),
        input.pageCount(),
        input.authorId()
    );
    return books.save(created);
}

Pure Type Mapping in Plain Java

The data-shaping logic behind a resolver is plain Java — you can reason about it without any server. Below, a search filter (the body of searchBooks) runs as a complete standalone program.

This mirrors exactly what your @QueryMapping method does internally.
No Spring, no schema engine — just type mapping and filtering.

import java.util.List;

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

    static List<Book> searchBooks(List<Book> all, String fragment) {
        return all.stream()
            .filter(b -> b.title().toLowerCase().contains(fragment.toLowerCase()))
            .toList();
    }

    public static void main(String[] args) {
        List<Book> catalog = List.of(
            new Book("1", "Spring in Action", 600),
            new Book("2", "GraphQL Basics", 220),
            new Book("3", "Effective Java", 412)
        );
        searchBooks(catalog, "graphql").forEach(b -> System.out.println(b.title()));
    }
}

Where Schema and Code Meet

At startup Spring validates that every schema field is satisfiable. If a field has no getter and no @SchemaMapping, you may get an unresolved-field error at query time.

Properties on your record resolve automatically by name.
Computed / fetched fields need an explicit mapping method.
Use the GraphiQL UI (enable spring.graphql.graphiql.enabled=true) to explore the live schema.

Keeping SDL and Java field names aligned is the core discipline of schema-first design.

Quick Check

You have a schema field Book.author: Author!, but a Book record only stores authorId and no author property. What is the correct schema-first way to resolve it?

Recap

You mapped a GraphQL schema to Spring controllers, schema-first:

SDL files under src/main/resources/graphql/ define object, input, Query, and Mutation types.
@QueryMapping handles reads, @MutationMapping handles writes, both binding args with @Argument.
@SchemaMapping (and @BatchMapping) resolve nested/computed fields from a source object.
Types map by field name: records are the cleanest representation, and SDL scalars map to their natural Java types.

Keep SDL and Java names aligned, and the schema stays the single source of truth.

Häufig gestellte Fragen

Ist die Lektion „Schema-First-Design und Typzuordnung“ kostenlos?

Ja — der vollständige Text von „Schema-First-Design und Typzuordnung“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des Spring Boot 4 Complete Guide-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der Spring Boot 4 Complete Guide-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Schema-First-Design und Typzuordnung“?

Definieren Sie ein GraphQL-Schema und ordnen Sie Typen, Queries und Mutations Java-Controller-Methoden zu. Du übst Spring Boot 4 Complete Guide mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um Spring Boot 4 Complete Guide zu starten?

Keine Vorkenntnisse erforderlich. Spring Boot 4 Complete Guide auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.

Wie lange dauert die Lektion „Schema-First-Design und Typzuordnung“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser Spring Boot 4 Complete Guide-Lektion Code schreiben und ausführen?

Ja. Jede Spring Boot 4 Complete Guide-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

Schema-First-Design und Typzuordnung
Data Fetcher und Argumentbindung
N+1 mit Batch Loadern lösen
Subscriptions, Fehler und Schema-Sicherheit

← Zurück zu Spring Boot 4 Complete Guide