JC4 - Per chi sviluppa

JC4.1 - Aggiungere una rotta

In una frase. Per far arrivare le richieste a un servizio nuovo basta una rotta nel Gateway: gli altri servizi non si toccano.

Una rotta è una riga che dice: le richieste che cominciano così vanno a quel servizio. Stanno tutte in una classe sola, quindi chi vuole sapere cosa è raggiungibile da fuori guarda in un posto solo. Aggiungerne una vuol dire copiare quelle che ci sono.

  1. Dai un nome al servizio. È il nome con cui si iscrive al Monitor servizi: tutto maiuscolo, con i trattini, per esempio NUOVO-SERVICE. Sta in spring.application.name del servizio.

  2. Aggiungi la rotta nel Gateway. Apri GatewayConfig e copia una rotta esistente. Cambiano tre cose: il nome della rotta (nuovo-service), l'inizio dell'indirizzo (/api/nuovo/**) e la destinazione (lb://NUOVO-SERVICE). Restano uguali stripPrefix(2) e il filtro authenticationFilter: vanno messi sempre.

  3. Nel servizio non ripetere l'inizio dell'indirizzo. Il Gateway toglie /api/nuovo prima di inoltrare. Se la pagina chiama /api/nuovo/clienti, il servizio riceve /clienti.

  4. Fai controllare il lasciapassare anche al servizio. Prendi come modello la SecurityConfig di un servizio esistente. Il nome utente lo leggi dall'intestazione X-User-Id, che scrive il Gateway.

  5. Ricostruisci e riavvia solo il Gateway. I servizi già accesi non vanno fermati.

  6. Prova. Chiama /api/nuovo/... dall'app. Un 503 vuol dire che il servizio non è ancora iscritto al Monitor servizi. Un 404 vuol dire che la rotta c'è ma il servizio non ha quell'indirizzo.

  7. Aggiorna la tabella delle rotte in docs/architettura/riferimento/ARCHITETTURA-MICROSERVIZI.md.

Il server web dell'app non va toccato: manda già al Gateway tutto ciò che comincia per /api/. Serve una regola in più solo per i collegamenti che restano aperti a lungo.

Attenzione.
• Con un numero diverso da 2 in stripPrefix il servizio riceve indirizzi sbagliati.
• Senza authenticationFilter il servizio non riceve il nome utente, e chi chiama potrebbe scriverne uno a piacere.
• Un servizio raggiungibile senza passare dal Gateway non può fidarsi di X-User-Id.

Per chi sviluppa.
• File: backend/middleware/it_gsba_api_gateway/src/main/java/it/gsba/api_gateway/config/GatewayConfig.java.
• Verifica: nella cartella del Gateway ./mvnw -o clean package -DskipTests, vale solo BUILD SUCCESS.
• Anche in sviluppo l'app manda già al Gateway tutto ciò che comincia per /api.
• Prima di cambiare le regole di sicurezza del Gateway si dice cosa cambia e perché: una modifica piccola può spegnere i controlli.

JC4.2 - Errori 401, 403 e 503: cosa vogliono dire

In una frase. Tre numeri dicono dove si è fermata una richiesta: all'ingresso (401), sul permesso (403) o davanti a un servizio spento (503).

Un errore con un numero sembra un guasto. Quasi sempre è una risposta precisa: dice chi ha fermato la richiesta e perché. Saper leggere questi tre numeri evita di chiamare l'assistenza quando basta rientrare o aspettare un minuto.

Numero Vuol dire Cosa fai
401 Il Gateway non sa chi sei: il lasciapassare manca o è scaduto Rientra con utente e password
403 Sei entrato, ma il tuo livello non basta per quella cosa Chiedi il livello a chi amministra
503 Il servizio che deve rispondere non è acceso o non è ancora pronto Aspetta un minuto e riprova

401: rientra. L'app ti riporta da sola alla pagina di accesso. Scrivi utente e password e riprendi.

La pagina di accesso: è qui che l'app ti riporta dopo un errore 401

La pagina di accesso: è qui che l'app ti riporta dopo un errore 401

403: è una questione di livello. Compare l'avviso Accesso negato. Non è un guasto e riprovare non serve: quella operazione chiede un livello più alto del tuo. Chi amministra può dartelo dalla pagina dei ruoli. I livelli sono in Cosa può fare ogni livello (libro «JB - Accesso e permessi», pagina «JB3.2 - Cosa può fare ogni livello»).

503: aspetta un minuto. Compare l'avviso Errore server 503. Il Gateway funziona, ma il servizio a cui è destinata la richiesta non è nell'elenco del Monitor servizi. Subito dopo un aggiornamento è normale: i servizi stanno ripartendo e si iscrivono uno alla volta. Se dopo qualche minuto l'errore c'è ancora, avvisa chi gestisce il server e di' quale pagina stavi aprendo: basta per capire quale servizio è fermo.

Nota. Il 401 e il 503 li decide il Gateway. Il 403 lo decide il servizio che riceve la richiesta, perché è lui che sa quale livello serve per ogni operazione.

Per chi sviluppa.
• Gli avvisi li mostra frontend/shell/src/shared/auth/error.interceptor.ts: 401 porta a /auth/login, 403 dà «Accesso negato», da 500 in su «Errore server» con il numero.
• 401 con un lasciapassare che sembra buono: controlla emittente, chiavi e SSO_CLIENT_AMMESSI (docs/devops/auth/AUTENTICAZIONE.md).
• 401 fra due servizi: la chiamata non porta il lasciapassare. Le regole sono in docs/devops/chiamate-fra-servizi.md.
• 502 al posto di 503: è fermo il Gateway, non un servizio.

JC4.3 - Se qualcosa non va

In una frase. I problemi più comuni con Gateway e Monitor servizi, come «vedo questo, faccio questo», e le parole da sapere.

Quando una pagina non risponde, la domanda utile è: dove si è fermata la richiesta? Il numero dell'errore lo dice quasi sempre. Qui trovi cosa fare caso per caso.

Per chi usa il gestionale

I tre numeri sono spiegati in Errori 401, 403 e 503: cosa vogliono dire.

Per chi gestisce il server

Parole da sapere

Per chi sviluppa. Lo stato si controlla con /actuator/health su Gateway e servizi. Variabili e porte: docs/devops/ENVIRONMENT.md e devops/deploy/README.md.