การออกแบบแบบสคีมาเป็นหลักและการแมปชนิด

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/.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.