Spring Boot 4 Complete Guide · Lezione

Subscription, errori e sicurezza dello schema

Trasmetta aggiornamenti in tempo reale tramite subscription e rafforzi lo schema con l’autorizzazione a livello di campo.

Subscription, errori e sicurezza dello schema è una lezione Spring Boot 4 Complete Guide gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Spring Boot 4 Complete Guide, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Spring Boot 4 Complete Guide include 4 lezioni in totale.

Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.

Beyond Query and Mutation

Spring for GraphQL supports three root operation types. So far you have used Query (read) and Mutation (write). The third is Subscription — a long-lived stream that pushes data to the client whenever a server-side event occurs.

Query/Mutation: one request, one response.
Subscription: one request, many responses over time.

In this lesson you will stream live updates with subscriptions, shape GraphQL errors cleanly, and lock down individual fields with method security.

Declaring a Subscription in the Schema

Subscriptions are declared in the GraphQL schema just like queries. Each subscription field describes a stream of a given type. Below, messageAdded streams a Message for a particular room.

The transport for subscriptions is typically WebSocket (graphql-ws protocol), so make sure your client connects over ws:// rather than plain HTTP POST.

type Subscription {
  messageAdded(roomId: ID!): Message!
}

type Message {
  id: ID!
  roomId: ID!
  text: String!
  author: String!
}

A Subscription Returns a Reactive Stream

In Spring for GraphQL, a method annotated with @SubscriptionMapping must return a Reactive Streams Publisher — most commonly a Project Reactor Flux. Each element the Flux emits is delivered to the subscribed client as a separate GraphQL response.

The method name maps to the subscription field (messageAdded).
Arguments come from @Argument, exactly like queries.
The Flux stays open until it completes, errors, or the client disconnects.

@Controller
public class ChatSubscriptionController {

    private final ChatService chatService;

    public ChatSubscriptionController(ChatService chatService) {
        this.chatService = chatService;
    }

    @SubscriptionMapping
    public Flux<Message> messageAdded(@Argument String roomId) {
        return chatService.streamMessages(roomId);
    }
}

Backing the Stream with a Sink

Where does the Flux come from? A common pattern is a Reactor Sinks.Many as a hot multicast source. Mutations push new events into the sink with tryEmitNext, and every active subscriber receives them.

Use multicast().onBackpressureBuffer() so multiple subscribers can share one source, and filter per room so each client only gets its own messages.

@Service
public class ChatService {

    private final Sinks.Many<Message> sink =
            Sinks.many().multicast().onBackpressureBuffer();

    public Message publish(Message message) {
        sink.tryEmitNext(message);
        return message;
    }

    public Flux<Message> streamMessages(String roomId) {
        return sink.asFlux()
                .filter(m -> m.roomId().equals(roomId));
    }
}

Wiring a Mutation to the Stream

A subscription only emits when something feeds it. Here a @MutationMapping creates a message and publishes it into the sink. Any client subscribed to that room receives the new message immediately.

This decoupling — mutation writes, subscription reads from the same sink — is the backbone of real-time GraphQL.

@Controller
public class ChatMutationController {

    private final ChatService chatService;

    public ChatMutationController(ChatService chatService) {
        this.chatService = chatService;
    }

    @MutationMapping
    public Message postMessage(@Argument String roomId,
                               @Argument String text,
                               @Argument String author) {
        Message message = new Message(
                UUID.randomUUID().toString(), roomId, text, author);
        return chatService.publish(message);
    }
}

Enabling the WebSocket Transport

Subscriptions need the WebSocket endpoint enabled. With Spring Boot 4 and the GraphQL starter, set the path in application.yml. The HTTP endpoint (/graphql) stays for queries and mutations; the WebSocket endpoint (/graphql over ws) handles subscriptions.

Without this property the WebSocket handler is not registered and subscription clients fail to connect.

spring:
  graphql:
    websocket:
      path: /graphql
      connection-init-timeout: 60s
    schema:
      printer:
        enabled: true

Why Default GraphQL Errors Leak Detail

When an exception escapes a controller method, Spring for GraphQL turns it into a GraphQL error. By default many exceptions surface as INTERNAL_ERROR with a generic message, but stack traces and unexpected exception messages can leak implementation details if you are not careful.

The fix is a DataFetcherExceptionResolver: map your domain exceptions to clean, well-classified GraphQLError objects with the right ErrorType.

Mapping Exceptions with @GraphQlExceptionHandler

The simplest approach is an @GraphQlExceptionHandler method inside a @Controller (or a @ControllerAdvice for global scope). It works like Spring MVC exception handling: catch a specific exception and return a GraphQLError.

ErrorType.NOT_FOUND → resource missing.
ErrorType.BAD_REQUEST → invalid input.
ErrorType.FORBIDDEN → authorization failure.

The extensions map carries machine-readable detail the client can act on.

@ControllerAdvice
public class GraphQlExceptionAdvice {

    @GraphQlExceptionHandler
    public GraphQLError handleNotFound(MessageNotFoundException ex) {
        return GraphQLError.newError()
                .errorType(ErrorType.NOT_FOUND)
                .message(ex.getMessage())
                .extensions(Map.of("code", "MESSAGE_NOT_FOUND"))
                .build();
    }
}

Field-Level Authorization with @PreAuthorize

GraphQL exposes a single endpoint, so you cannot rely on URL-based security. Instead secure individual fields at the method level. With Spring Security's method security enabled (@EnableMethodSecurity), annotate controller methods with @PreAuthorize.

If the check fails, the field resolves to null and an authorization error is added to the GraphQL errors array — sibling fields still resolve normally.

@Controller
public class AdminController {

    @QueryMapping
    @PreAuthorize("hasRole('ADMIN')")
    public List<AuditEntry> auditLog() {
        return auditService.findAll();
    }

    @SchemaMapping(typeName = "Message", field = "author")
    @PreAuthorize("isAuthenticated()")
    public String author(Message message) {
        return message.author();
    }
}

Propagating Security to Reactive Subscriptions

Subscriptions run on the reactive WebSocket transport, so the SecurityContext must travel through the reactive chain. Spring Security populates the Reactor context; access the authenticated principal with ReactiveSecurityContextHolder rather than the thread-local SecurityContextHolder.

This lets you filter a subscription stream by the current user — for example, only emitting messages from rooms the user belongs to.

@SubscriptionMapping
@PreAuthorize("isAuthenticated()")
public Flux<Message> messageAdded(@Argument String roomId) {
    return ReactiveSecurityContextHolder.getContext()
            .map(ctx -> ctx.getAuthentication().getName())
            .flatMapMany(user ->
                    chatService.streamMessages(roomId, user));
}

A Standalone Flux Stream Demo

You do not need a running server to understand how a subscription stream behaves. The example below uses a plain Reactor Flux with a filter — exactly the shape streamMessages returns — and prints each emitted element, mimicking what a subscribed client would receive.

Notice how only messages matching the room pass through, just like server-side per-room filtering.

import reactor.core.publisher.Flux;

public class StreamDemo {
    record Message(String roomId, String text) {}

    public static void main(String[] args) {
        Flux<Message> source = Flux.just(
                new Message("general", "hi"),
                new Message("random", "noise"),
                new Message("general", "streaming works"));

        source.filter(m -> m.roomId().equals("general"))
              .subscribe(m -> System.out.println("Push -> " + m.text()));
    }
}

Quick Check: Securing a Field

You want only users with the ADMIN role to be able to read the auditLog query field, while every other field in the same response keeps resolving normally for all users. Which approach fits GraphQL best?

Recap

You now have the real-time and security toolkit for Spring for GraphQL:

Subscriptions are declared in the schema and implemented with @SubscriptionMapping returning a reactive Flux/Publisher.
A Sinks.Many hot source lets mutations push events that subscribers stream, filtered per room.
Enable the WebSocket transport via spring.graphql.websocket.path.
Map domain exceptions to clean GraphQLErrors with @GraphQlExceptionHandler and the right ErrorType.
Secure individual fields with @PreAuthorize; failures null the field and add an error without breaking siblings.
For subscriptions, read the principal from the reactive ReactiveSecurityContextHolder.

Domande Frequenti

La lezione «Subscription, errori e sicurezza dello schema» è gratuita?

Sì — il testo completo di «Subscription, errori e sicurezza dello schema» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Spring Boot 4 Complete Guide, passa a CoddyKit PRO. Il corso Spring Boot 4 Complete Guide include 4 lezioni in totale.

Cosa imparerò in «Subscription, errori e sicurezza dello schema»?

Trasmetta aggiornamenti in tempo reale tramite subscription e rafforzi lo schema con l’autorizzazione a livello di campo. Eserciti Spring Boot 4 Complete Guide con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Spring Boot 4 Complete Guide?

Non è richiesta alcuna esperienza precedente. Spring Boot 4 Complete Guide su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.

Quanto tempo richiede la lezione «Subscription, errori e sicurezza dello schema»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Spring Boot 4 Complete Guide?

Sì. Ogni lezione Spring Boot 4 Complete Guide include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Progettazione schema-first e mapping dei tipi
Data fetcher e associazione degli argomenti
Risoluzione del problema N+1 con i batch loader
Subscription, errori e sicurezza dello schema

← Torna a Spring Boot 4 Complete Guide