Como encaminhar as chamadas de um front Angular

Com um micro de backend, apontar uma dependência ao local, à nuvem ou a um mock é direto: o Aseptic injeta-lhe o URL resolvido ao arrancar, como propriedade do sistema (-D) ou como variável de ambiente. Um front Angular não tem onde o receber: as suas chamadas saem do navegador, e o URL para onde apontam foi decidido ao compilar ou vive num ficheiro que a própria app serve.

Por isso o Aseptic encaminha-o de outra forma. Há três vias, escolhidas por esta ordem, da menos à mais intrusiva. As duas primeiras não tocam no seu repositório.

1. Por proxy (o que acontece por omissão)

O Aseptic escreve um proxy.conf.json em .aseptic/.runtime/ —fora do seu repo— e passa-o ao ng serve com --proxy-config. Esse ficheiro mapeia o prefixo de API de cada dependência ao destino que o cenário resolveu para ela: o micro local, a nuvem ou o servidor de mocks.

Para funcionar, cada dependência do front tem de declarar como caminho local o prefixo com que a app chama (por exemplo /api/encomendas). É a única coisa a rever depois de dar entrada ao front: a autodeteção não o consegue adivinhar a partir do código, por isso deixa-o para si confirmar.

Não há nada a ativar. Se o cenário resolver a dependência como mock, o front fala com o mock sem que nem o front nem você deem por isso.

2. Quando o ng serve não aceita a flag

Alguns fronts não arrancam com o servidor de desenvolvimento do Angular mas com um builder próprio —o Module Federation é o caso típico—, e esse builder não conhece --proxy-config. Passar-lha não degrada o encaminhamento: impede o micro de arrancar, com um Error: Unknown argument: proxy-config. E como o que não sobe arrasta os que dele dependiam, o cenário acaba a apontar para outro sítio.

O Aseptic olha para o builder declarado no angular.json (ou workspace.json, no Nx) e só deixa de passar a flag quando tem prova de que não é aceite. Se não houver ficheiro, não se conseguir ler ou o projeto não se identificar, passa-a como sempre: tirá-la «por via das dúvidas» deixaria sem encaminhamento fronts que hoje funcionam, e essa falha silenciosa é pior do que a ruidosa que evita.

Quando não a passa, o cenário arranca na mesma e o log di-lo: esse front fica sem encaminhamento, e ali mesmo lhe indica por onde sair.

Em Micros → Configuração de arranque local pode forçá-lo com Encaminhamento pelo proxy do ng serve:

• Automático — deduzido do builder. É o normal.
• Sim, passar a flag — para um builder que a aceita e não está na lista.
• Nunca a passar — para um que não a aceita.

3. Por configuração em runtime

Se a sua app pede a configuração ao arrancar —o padrão do APP_INITIALIZER que faz um fetch a um caminho e daí tira os URL—, diga-o em Caminho de configuração em runtime. O Aseptic serve aí um JSON com os URL já resolvidos e encaminha esse caminho pelo mesmo proxy.

É um caminho virtual, não um ficheiro do seu repositório: é precisamente por isso que se pode intercetar. E há duas formas de o servir:

• JSON de dependências (por omissão): um objeto identificador de dependência → URL resolvido. É um contrato entre a sua app e o manifesto: a app tem de conhecer essas chaves.
• Relativa ao gateway: para as apps que já trazem a sua configuração num asset próprio (assets/config/environment.js) com os URL pendurados num API gateway. O Aseptic serve esse mesmo asset, tal e qual, mais um corte que em runtime converte a origem do gateway em caminho relativo, para que o proxy a capture por prefixo. Se o repo trouxer esse ficheiro, é autodetetado ao dar entrada ao micro e não há nada a configurar.

4. Reescrevendo o environment (último recurso)

Fica um caso a que nenhuma das anteriores chega: fronts que não aceitam a flag do proxy, não pedem configuração em runtime e resolvem o backend com URL compilados ao construir, dentro do environment do perfil ativo. Aí a única via é tocar nesse ficheiro.

O Aseptic fá-lo de forma delimitada e reversível, e só se você o pedir: declara-se no manifesto com stack.environmentRewrite, dizendo que ficheiro e que campos apontam para que dependência. Ao arrancar substitui o valor desses campos pelo URL resolvido; ao parar, deixa-o como estava. Não há controlo na interface de propósito: é opt-in e declara-se à mão.

Duas salvaguardas que convém conhecer:

• Aguenta fechos abruptos. O original é salvaguardado fora do repositório (.aseptic/.runtime/env-backups/) e restaurado tanto ao parar como ao voltar a arrancar: se a app foi morta com o ficheiro tocado, a primeira coisa que faz é devolvê-lo ao sítio.
• Melhor um perfil não versionado. O ficheiro fica modificado enquanto o cenário corre, por isso prefere-se um environment.local.ts ignorado pelo git. A verificação do ambiente avisa se o que declarou está versionado, ou se não existe.

Qual lhe calha

• O seu front arranca com ng serve e chama por um prefixo? A 1, sem fazer nada.
• Arranca mas não encaminha e o log fala do --proxy-config? A 2, e se o seu builder a aceitar, force-a.
• A sua app pede a configuração ao arrancar? A 3.
• Nenhuma das anteriores e os URL estão compilados lá dentro? A 4.

Ver também

• Dependências · Micro, manifesto e stack
• Secção Micros · Personalizar o arranque