Come instradare le chiamate di un front Angular

Con un micro di backend, puntare una dipendenza al locale, al cloud o a un mock è diretto: Aseptic gli inietta l’URL risolto all’avvio, come proprietà di sistema (-D) o come variabile d’ambiente. Un front Angular non ha dove riceverlo: le sue chiamate partono dal browser, e l’URL a cui puntano è stato deciso in compilazione o vive in un file che serve l’app stessa.

Per questo Aseptic lo instrada in un altro modo. Ci sono tre vie, scelte in quest’ordine, dalla meno alla più invasiva. Le prime due non toccano il tuo repository.

1. Via proxy (quello che succede di default)

Aseptic scrive un proxy.conf.json in .aseptic/.runtime/ —fuori dal tuo repo— e lo passa a ng serve con --proxy-config. Quel file mappa il prefisso di API di ogni dipendenza alla destinazione che lo scenario ha risolto per essa: il micro locale, il cloud o il server di mock.

Perché funzioni, ogni dipendenza del front deve dichiarare come percorso locale il prefisso con cui l’app chiama (per esempio /api/ordini). È l’unica cosa da rivedere dopo aver aggiunto il front: il rilevamento automatico non può indovinarlo dal codice, e quindi lo lascia a te da confermare.

Non c’è nulla da attivare. Se lo scenario risolve la dipendenza a mock, il front parla con il mock senza che né il front né tu ve ne accorgiate.

2. Quando ng serve non accetta il flag

Alcuni front non si avviano con il server di sviluppo di Angular ma con un builder proprio —Module Federation è il caso tipico—, e quel builder non conosce --proxy-config. Passarglielo non degrada l’instradamento: impedisce al micro di avviarsi, con un Error: Unknown argument: proxy-config. E poiché quello che non si alza trascina con sé quelli che dipendevano da lui, lo scenario finisce per indicare un altro punto.

Aseptic guarda il builder dichiarato in angular.json (o workspace.json, su Nx) e smette di passare il flag solo quando ha la prova che non è accettato. Se non c’è il file, non si riesce a leggere o il progetto non si identifica, lo passa come sempre: toglierlo «per sicurezza» lascerebbe senza instradamento front che oggi funzionano, e quel guasto silenzioso è peggio di quello rumoroso che evita.

Quando non lo passa, lo scenario si avvia lo stesso e il log lo dice: quel front resta senza instradamento, e lì stesso ti indica da dove uscire.

In Micros → Configurazione di avvio locale puoi forzarlo con Instradamento via proxy di ng serve:

• Automatico — dedotto dal builder. È la norma.
• Sì, passa il flag — per un builder che lo accetta e non è nell’elenco.
• Non passarlo mai — per uno che non lo accetta.

3. Via configurazione a runtime

Se la tua app chiede la sua configurazione all’avvio —il pattern dell’APP_INITIALIZER che fa un fetch a un percorso e da lì ricava gli URL—, dillo in Percorso di configurazione a runtime. Aseptic serve lì un JSON con gli URL già risolti e instrada quel percorso attraverso lo stesso proxy.

È un percorso virtuale, non un file del tuo repository: proprio per questo si può intercettare. E ci sono due modi di servirlo:

• JSON di dipendenze (default): un oggetto identificatore di dipendenza → URL risolto. È un contratto tra la tua app e il manifesto: l’app deve conoscere quelle chiavi.
• Relativa al gateway: per le app che portano già la loro configurazione in un asset proprio (assets/config/environment.js) con gli URL appesi a un API gateway. Aseptic serve quello stesso asset, tale e quale, più un ritaglio che a runtime converte l’origine del gateway in percorso relativo, perché il proxy la catturi per prefisso. Se il repo porta quel file, viene rilevato automaticamente all’aggiunta del micro e non c’è nulla da configurare.

4. Riscrivendo l’environment (ultima risorsa)

Resta un caso a cui nessuna delle precedenti arriva: front che non accettano il flag del proxy, non chiedono configurazione a runtime e risolvono il backend con URL compilati in fase di build, dentro l’environment del profilo attivo. Lì l’unica via è toccare quel file.

Aseptic lo fa in modo circoscritto e reversibile, e solo se glielo chiedi: si dichiara nel manifesto con stack.environmentRewrite, dicendo quale file e quali campi puntano a quale dipendenza. All’avvio sostituisce il valore di quei campi con l’URL risolto; alla fermata, lo lascia com’era. Non c’è un controllo nell’interfaccia di proposito: è opt-in e si dichiara a mano.

Due salvaguardie da conoscere:

• Regge le chiusure brusche. L’originale viene salvato fuori dal repository (.aseptic/.runtime/env-backups/) e ripristinato sia alla fermata sia al riavvio successivo: se l’app è stata uccisa con il file modificato, la prima cosa che fa è rimetterlo a posto.
• Meglio un profilo non versionato. Il file resta modificato mentre lo scenario gira, quindi si preferisce un environment.local.ts ignorato da git. Il controllo dell’ambiente avvisa se quello che hai dichiarato è versionato, o se non esiste.

Quale tocca a te

• Il tuo front si avvia con ng serve e chiama tramite un prefisso? La 1, senza fare nulla.
• Si avvia ma non instrada e il log parla di --proxy-config? La 2, e se il tuo builder lo accetta, forzalo.
• La tua app chiede la configurazione all’avvio? La 3.
• Nessuna delle precedenti e gli URL sono compilati dentro? La 4.

Vedi anche

• Dipendenze · Micro, manifesto e stack
• Sezione Micros · Personalizzare l’avvio