JC4 - Per chi sviluppa
- JC4.1 - Aggiungere una rotta
- JC4.2 - Errori 401, 403 e 503: cosa vogliono dire
- JC4.3 - Se qualcosa non va
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.
Dai un nome al servizio. È il nome con cui si iscrive al Monitor servizi: tutto maiuscolo, con i trattini, per esempio
NUOVO-SERVICE. Sta inspring.application.namedel servizio.Aggiungi la rotta nel Gateway. Apri
GatewayConfige 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 ugualistripPrefix(2)e il filtroauthenticationFilter: vanno messi sempre.Nel servizio non ripetere l'inizio dell'indirizzo. Il Gateway toglie
/api/nuovoprima di inoltrare. Se la pagina chiama/api/nuovo/clienti, il servizio riceve/clienti.Fai controllare il lasciapassare anche al servizio. Prendi come modello la
SecurityConfigdi un servizio esistente. Il nome utente lo leggi dall'intestazioneX-User-Id, che scrive il Gateway.Ricostruisci e riavvia solo il Gateway. I servizi già accesi non vanno fermati.
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.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
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
- Mi ritrovo alla pagina di accesso mentre lavoravo. Il lasciapassare non vale più. Rientra: è l'errore 401.
- Vedo «Accesso negato». Il tuo livello non basta per quella operazione. Chiedi a chi amministra: è l'errore 403.
- Vedo «Errore server 503» subito dopo un aggiornamento. I servizi stanno ripartendo. Aspetta un minuto e riprova.
- Vedo «Errore server 503» su una cosa sola, per esempio le stampe. È fermo quel servizio. Il resto puoi usarlo. Avvisa chi gestisce il server.
- Vedo «Server non raggiungibile» o «Errore server 502». Non risponde il Gateway, oppure è caduta la rete. Controlla la connessione, poi avvisa chi gestisce il server.
- Le pagine nuove non vanno, le maschere storiche sì. Può succedere: fanno due strade diverse. Il problema è dalla parte del Gateway.
I tre numeri sono spiegati in Errori 401, 403 e 503: cosa vogliono dire.
Per chi gestisce il server
- Un servizio dà 503 e non passa. Apri la pagina del Monitor servizi e guarda se è nell'elenco: vedi Vedere quali servizi sono accesi. Se manca, guarda il registro di quel servizio: non è partito o non raggiunge il Monitor servizi.
- Tutti i servizi danno 503. Controlla che il Monitor servizi sia acceso. Senza di lui i servizi non riescono a iscriversi.
- Tutti ricevono 401, anche appena entrati. Il Gateway non riesce a verificare i lasciapassare: controlla gli indirizzi dell'Accesso nella configurazione. Se mancano, li rifiuta tutti.
- Dal mio PC la pagina del Monitor servizi non si apre. È voluto: si apre solo dal server.
- Un servizio spento compare ancora nell'elenco. Il Monitor servizi aspetta prima di cancellarlo.
Parole da sapere
- Gateway. La porta unica: controlla chi sei e manda ogni richiesta al servizio giusto.
- Monitor servizi. L'elenco dei servizi accesi, con nome e indirizzo.
- Servizio. Un programma che fa una cosa sola: le stampe, i dati del gestionale, le schermate.
- Richiesta. Una domanda che la pagina fa a un servizio: «dammi questa tabella», «salva questo».
- Rotta. La regola del Gateway che lega l'inizio di un indirizzo a un servizio.
- Lasciapassare. La prova che sei entrato: lo firma l'Accesso, dice chi sei e che livello hai, scade dopo poco.
- Livello. Quello che puoi fare: lettore, base, avanzato, staff.
- Iscriversi. Quello che fa un servizio quando si accende: dice al Monitor servizi «sono qui».
- Ponte col COBOL. L'altra strada: porta le maschere storiche nel browser, senza passare dal Gateway.
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.