Usar Dev Proxy em cenários CI/CD

De relance
Objetivo: Integrar Proxy de Desenvolvimento em CI/CD
Tempo: 30 minutos
Plugins: Vários
Pré-requisitos:Configurar o Proxy de Desenvolvimento

Usar o Dev Proxy em cenários de CI/CD é uma ótima maneira de testar seus aplicativos em um ambiente controlado. Ao combinar o Proxy de Desenvolvimento com testes que geram solicitações de API em seu aplicativo, você pode cobrir uma ampla variedade de cenários: desde garantir que seu aplicativo não use APIs de sombra ou de não produção até verificar se ele usa permissões mínimas do Microsoft Graph. Embora as etapas exatas de configuração variem dependendo do seu sistema de CI/CD, aqui estão alguns princípios gerais que você deve seguir.

Na maioria dos casos, seu corredor não tem o Dev Proxy instalado. Então, antes de poder usar o Dev Proxy, você precisa instalá-lo. As etapas de instalação dependem do sistema operacional que seu corredor usa.

Ao instalar o Dev Proxy numa configuração de CI/CD, normalmente pretendes especificar a versão do Dev Proxy que instalas. Definir a versão garante que o seu pipeline utilize sempre a mesma versão do Dev Proxy sempre que o executa. As etapas exatas para fixar uma versão dependem do sistema operacional do seu corredor. Aqui está um exemplo de como você pode fixar a versão do Dev Proxy em um corredor baseado em Linux:

# install Dev Proxy v1.0.0
bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)" -- v1.0.0

Flags de CI recomendadas

Num pipeline CI/CD, inicia o Dev Proxy sempre com o mesmo conjunto de opções, para que corra em segundo plano, não altere a configuração do runner e não espere pela entrada do utilizador. Recomendamos as seguintes opções:

Além disso, antes de começares o Dev Proxy, define a variável de ambiente DEV_PROXY_API_TOKEN com um token que geras. Desta forma, sabes o token que precisas para chamar à API do Dev Proxy sem teres de o recuperar do Dev Proxy. O token deve ter pelo menos 32 caracteres. Para os requisitos completos, veja Proxy API.

# generate an API token for this run
export DEV_PROXY_API_TOKEN=$(openssl rand -hex 32)

Os exemplos neste artigo utilizam estas opções e a variável de ambiente DEV_PROXY_API_TOKEN.

Obter uma configuração para gravar chamadas à API

Se quiser registar quais as APIs que a sua aplicação chama durante uma execução de CI, não precisa de construir uma configuração do zero. Descarregue o api-inventory preset da galeria de exemplos do Dev Proxy usando o config get comando:

./devproxy/devproxy config get api-inventory

O preset combina o UrlDiscoveryPlugin e o ExecutionSummaryPlugin com repórteres, e não regista Dev Proxy como proxy do sistema. Quando iniciar o Dev Proxy, passe o ficheiro de configuração do preset, sobrescreve os URLs para observar com as APIs que a tua app chama e usa os flags de CI recomendados:

./devproxy/devproxy --config-file "~dataFolder/configs/api-inventory/.devproxy/devproxyrc.json" --urls-to-watch "https://api.contoso.com/*" --detach --as-system-proxy false --install-cert false --no-first-run --no-watch

Para mais informações sobre predefinições, consulte Utilizar configurações predefinidas.

Iniciar Dev Proxy

Depois de instalar o Dev Proxy, você precisa iniciá-lo. Ao iniciar o Dev Proxy em um pipeline de CI/CD, é importante iniciá-lo em segundo plano. Caso contrário, seu pipeline será bloqueado até que você pare o Dev Proxy.

Inicie o Proxy de Desenvolvimento em segundo plano usando os flags de CI recomendados:

# start Dev Proxy in detached mode
./devproxy/devproxy --detach --as-system-proxy false --install-cert false --no-first-run --no-watch

O Proxy de Desenvolvimento imprime informações de arranque, incluindo o ID do processo (PID), URL do Proxy, URL da API e caminho do ficheiro de registo:

Dev Proxy started in background.

  PID:       6456
  Proxy URL: http://127.0.0.1:8000
  API URL:   http://127.0.0.1:8897
  Log file:  /home/runner/.local/dev-proxy/logs/devproxy-6456-2026-03-05.log

Para saída legível por máquina, use --output json para obter JSONL:

./devproxy/devproxy --detach --as-system-proxy false --install-cert false --no-first-run --no-watch --output json

{"type":"result","data":{"pid":6456,"proxyUrl":"http://127.0.0.1:8000","apiUrl":"http://127.0.0.1:8897","logFile":"/home/runner/.local/dev-proxy/logs/devproxy-6456-2026-03-05.log"},"timestamp":"2026-03-05T14:22:42.0000000Z"}

Alternativamente, se estiver a usar um runner baseado em Linux, pode iniciar o Dev Proxy em segundo plano usando o controlo de jobs da shell:

# start Dev Proxy in the background
./devproxy/devproxy --as-system-proxy false --install-cert false --no-first-run --no-watch > devproxy.log 2>&1 &

Aguarde até que o Dev Proxy inicie

Quando inicias o Dev Proxy em segundo plano, o teu script continua imediatamente. No entanto, o Dev Proxy precisa de algum tempo para começar. Para garantir que o Dev Proxy está pronto antes de começar a emitir pedidos, espere até que a API dele responda a um pedido GET /proxy:

api_url=http://127.0.0.1:8897

echo "Waiting for Dev Proxy to start..."
until curl -sf -o /dev/null "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"; do
  sleep 1
done

# the rest of your script

A sondagem da API funciona independentemente da porta em que o Dev Proxy escuta, incluindo quando usas --port 0.

Confie no certificado raiz do Dev Proxy

Depois de iniciar o Dev Proxy, precisas de confiar no certificado raiz do Dev Proxy antes de enviar pedidos, porque o Dev Proxy usa um certificado raiz auto-assinado.

Dependendo das suas permissões, pode ser necessário criar a ~/.config/dev-proxy/rootCert pasta onde o Dev Proxy armazena o seu certificado raiz, antes de iniciar o Dev Proxy:

# ensure the rootCert folder
echo "Ensuring the Dev Proxy rootCert folder"
mkdir -p ~/.config/dev-proxy/rootCert

Para obter a chave pública do certificado raiz, descarregue-a usando a API Dev Proxy. Se estiver a usar um runner baseado em Linux, pode então instalar o certificado copiando-o para a loja de certificados de CA de confiança do sistema:

# download the Dev Proxy's Root Certificate
echo "Downloading the Dev Proxy's Root Certificate"
curl -sf -o dev-proxy-ca.crt "$api_url/proxy/rootCertificate?format=crt" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"

# install root certificate
echo "Installing the Dev Proxy's Root Certificate"
sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/

# update CA certificates
echo "Updating the CA certificates"
sudo update-ca-certificates

Configurar variáveis de ambiente proxy

Muitos aplicativos e bibliotecas usam as http_proxy variáveis e https_proxy de ambiente para determinar o servidor proxy a ser usado para solicitações HTTP e HTTPS. Como começas Dev Proxy com --as-system-proxy false, tens de definir estas variáveis de ambiente para apontarem para a instância Dev Proxy para garantir que a tua aplicação usa Dev Proxy.

export http_proxy=http://127.0.0.1:8000
export https_proxy=http://127.0.0.1:8000

Proxy de Controlo de Desenvolvimento

Quando você executa o Dev Proxy em um pipeline de CI/CD, não é possível controlá-lo interativamente. Em vez disso, você pode controlá-lo enviando solicitações para a API de proxy de desenvolvimento.

Todos os pedidos de API do Dev Proxy requerem um bearer token no cabeçalho Authorization. Se definires a DEV_PROXY_API_TOKEN variável de ambiente como recomendado, usa o seu valor. Caso contrário, como o Dev Proxy não imprime o token no arranque quando a CI variável de ambiente está definida, recupere-o usando o comando API token :

export DEV_PROXY_API_TOKEN=$(./devproxy/devproxy api token)

Se quiser analisar pedidos de API emitidos pela sua aplicação, pode enviar um POST pedido ao /proxy endpoint para começar a gravar:

curl -sf -X POST "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN" -H "Content-Type: application/json" -d '{"recording": true}'

Para parar a gravação, envie um POST pedido ao /proxy endpoint com recording definido para false:

curl -sf -X POST "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN" -H "Content-Type: application/json" -d '{"recording": false}'

Para parar o Dev Proxy, você pode enviar uma POST solicitação para o /proxy/stopproxy ponto de extremidade:

curl -sf -X POST "$api_url/proxy/stopproxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"

Depois de parar o processo de Proxy de Desenvolvimento, pode levar um momento para que ele feche totalmente. Para garantir que o Dev Proxy tenha terminado, espere que o seu ficheiro de log, que o Dev Proxy imprime quando começa em modo destacado, contenha uma das mensagens de conclusão, por exemplo:

echo "Waiting for Dev Proxy to complete..."
while true; do
  if grep -q -e "DONE" -e "No requests to process" -e "An error occurred in a plugin" "$log_file"; then
    break
  fi
  sleep 1
done

Quando todos os plug-ins de gravação terminam de ser executados, o Dev Proxy imprime a mensagem DONE na saída. Se não houver solicitações para processar, o Dev Proxy imprimirá a mensagem No requests to process. Se ocorreu um erro em um plugin, o Dev Proxy imprimirá a mensagem An error occurred in a plugin. Quando você vir qualquer uma dessas mensagens, você pode ter certeza de que o Dev Proxy terminou de processar as solicitações gravadas.

Exemplo de script de início

Aqui está um exemplo de script bash que podes usar para iniciar Dev Proxy num pipeline CI/CD. O script utiliza as flags de CI recomendadas, lê o URL do proxy, o URL da API e o caminho do ficheiro de registo a partir da saída JSON, espera até que a API do Dev Proxy responda e confia no certificado raiz descarregado da API. É usado jq para analisar a saída JSON.

echo "Generating the Dev Proxy API token"
export DEV_PROXY_API_TOKEN=$(openssl rand -hex 32)

echo "Ensuring Dev Proxy rootCert folder"
mkdir -p ~/.config/dev-proxy/rootCert

echo "Starting Dev Proxy"
result=$(./devproxy/devproxy --detach --as-system-proxy false --install-cert false --no-first-run --no-watch --output json | jq -c 'select(.type == "result")')
if [ -z "$result" ]; then
  echo "Failed to start Dev Proxy"
  exit 1
fi

proxy_url=$(echo "$result" | jq -r '.data.proxyUrl')
api_url=$(echo "$result" | jq -r '.data.apiUrl')
log_file=$(echo "$result" | jq -r '.data.logFile')

echo "Waiting for Dev Proxy to start..."
until curl -sf -o /dev/null "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"; do
  sleep 1
done

echo "Downloading the Dev Proxy's Root Certificate"
curl -sf -o dev-proxy-ca.crt "$api_url/proxy/rootCertificate?format=crt" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"

echo "Installing the Dev Proxy's Root Certificate"
sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/

echo "Updating the CA certificates"
sudo update-ca-certificates

echo "Set proxy variables"
export http_proxy=$proxy_url
export https_proxy=$proxy_url

Consulte também

• Usa o Proxy Dev com GitHub Actions
• Utilize Dev Proxy com Azure Pipelines
• Dev Proxy API
• Registrar e exportar a atividade de proxy
• Usar configurações predefinidas