Il registro

Decine di servizi cambiavano contratto, con il frontend in produzione.

Una rete sanitaria privata

Sanità · Migrazione API · Strangler fig · Serverless

Una rete sanitaria privata ha decine di microservizi REST e un frontend, sito e prenotazione online, che dipende dai loro contratti. La direzione tecnica ha scelto GraphQL come strato comune tra applicazioni. Il passaggio doveva avvenire con il servizio acceso, senza riscrivere le interfacce e senza cambiare una risposta che i pazienti vedono.

Un gateway serverless in Node fa da strato di traduzione. Ogni handler è stato portato uno a uno con test di parità, l'integrazione con l'ERP è governata da un interruttore e le firme dei token sono passate a chiavi asimmetriche durante la revisione.

1:1
handler portati con parità verificata sul comportamento
0
modifiche richieste al frontend durante la migrazione
RS256
firme dei token passate a chiavi asimmetriche in revisione

Il contesto

Negli anni la piattaforma si è distribuita: un core Laravel che governa anagrafiche e prenotazioni, un proxy serverless che espone dati alle applicazioni, microfrontend per calendario e prenotazione online, servizi dedicati per referti, consensi e ticket. Molti di questi parlano REST con contratti propri, e il frontend li conosce uno per uno.

Portare tutto su uno schema GraphQL comune semplifica la vita a chi costruisce nuove applicazioni. Ma se il frontend dovesse cambiare insieme ai servizi, ogni migrazione diventerebbe un rilascio coordinato di più team, con il rischio concentrato in un giorno.

Il vincolo

Tre cose non potevano rompersi: la prenotazione online, la consultazione dei referti e l'area privacy dei pazienti. Per ciascuna, il frontend doveva ricevere le stesse risposte di prima, compresi i codici di errore e i casi limite, come un 404 su una disponibilità inesistente o un tentativo che va ripetuto su più settimane.

In più, una parte del flusso di onboarding dei medici scriveva su un ERP attraverso un'applicazione Laravel 7 con dipendenze bloccate da due anni. L'ERP stava cambiando a sua volta, e quelle scritture dovevano poter essere spente in modo controllato senza fermare il resto del processo.

La decisione

Abbiamo adottato il pattern strangler fig con uno strato anticorruzione: un gateway serverless in Node che espone al frontend il contratto che già conosce e, dietro, risolve sul nuovo schema GraphQL. Il frontend continua a chiamare ciò che chiamava; quello che cambia è chi risponde.

La regola per ogni handler è stata portare la logica uno a uno, senza ragionare su cosa migliorare durante il trasporto. Le migliorie sono un lavoro successivo, con il vecchio già spento. Anche il retry multi-settimana della ricerca disponibilità è stato replicato tale e quale, perché il comportamento visibile era parte del contratto.

Per l'ERP la decisione è stata un interruttore esplicito: con le scritture disattivate, il processo completa comunque la verifica e l'archiviazione dei documenti e manda un'email alle persone che gestiscono il caso a mano. Il flusso si degrada in modo leggibile invece di fallire.

L'intervento

Prima il livello di base del gateway, così che il team interno potesse aggiungere endpoint senza ridiscutere l'architettura: struttura serverless, resolver, log strutturato con contesto, gestione del refresh dei token con tentativi a intervallo crescente, propagazione degli errori applicativi dai servizi al frontend. Poi la migrazione per domini: consensi e archivio referti, poi la ricerca disponibilità e la prenotazione.

Ogni dominio è passato da una serie di revisioni incrociate. Una di queste ha trovato che un handler migrato in parità firmava i token con una chiave simmetrica: è stato corretto verso chiavi asimmetriche e i segreti sono usciti dal codice verso la configurazione, entro i limiti dell'ambiente. Un'altra ha chiarito la logica di cache delle risorse su Redis e in che ordine si cercano le chiavi prima di interrogare il core.

Sul lato ERP, la mappa di tutte le integrazioni nel flusso di onboarding è stata scritta prima di toccare il codice. Da quella mappa, la disattivazione controllata: verifica e archiviazione dei documenti su S3 continuano, le scritture verso l'ERP si fermano dietro il flag, e il codice cliente che prima veniva generato dall'ERP viene fornito a mano insieme ai dati. È lavoro di integrazione tra sistemi e di infrastruttura serverless insieme.

FRONTEND → GATEWAY (contratto invariato) → SCHEMA GRAPHQL → SERVIZI · CORE · ERP (interruttore)

Schema semplificato. Dettagli architetturali e integrazioni non pubblicati per riservatezza.

Il risultato

La migrazione procede per domini e il servizio non si è mai fermato. Il frontend non ha richiesto modifiche; il team del cliente aggiunge i nuovi endpoint sull'architettura impostata, con la stessa struttura per ognuno. Le firme dei token sono passate a chiavi asimmetriche durante la revisione, prima di arrivare in produzione.

L'integrazione con l'ERP può essere spenta e riaccesa con una variabile, e quando è spenta le persone giuste ricevono ciò che serve per completare il caso a mano. Nessun processo è rimasto appeso a un sistema in transizione.

Dopo il rilascio

Con il gateway in piedi, il costo di ogni dominio successivo è più basso del precedente: la struttura è la stessa, cambiano i resolver. Il vecchio proxy si spegne un handler alla volta. Il lavoro rientra nel nostro settore sanità, dove la continuità del servizio decide l'architettura.

Dentro un ecosistema di quaranta microservizi →

Descrivici il sistema. Ti diciamo cosa vediamo.

Dieci minuti, una domanda alla volta. Alla fine, la nostra lettura onesta del caso. È il filtro, prima ancora della call.