CustomLocalReply plug-in - Alibaba Cloud Service Mesh: Central de Documentação do Alibaba Cloud

Quando um gateway ASM ou sidecar proxy intercepta uma requisição e retorna uma resposta HTTP diretamente — sem encaminhá-la ao serviço upstream — o corpo da resposta padrão é uma mensagem genérica, como not found ou RBAC: Access Denied. O plug-in CustomLocalReply substitui essas respostas padrão por códigos de status, cabeçalhos e conteúdo de corpo personalizados. Assim, você pode redirecionar URLs obsoletas, aplicar sua marca às páginas de erro ou padronizar formatos de erro de API em todo o mesh.

Cenários

Se você quiser...	Consulte
Redirecionar URLs desatualizadas para um novo local	Redirecionar um 404 para outra URL
Retornar uma página de erro HTML personalizada em vez de texto simples	Retornar uma página 403 personalizada
Padronizar respostas de erro de API no formato JSON	Retornar uma resposta de erro JSON

Quando as respostas locais são geradas

O ASM gera uma resposta local (ignorando o serviço upstream) nas seguintes situações:

Gatilho	Código de status padrão	Corpo padrão
Nenhuma regra de roteamento corresponde à requisição	`404`	`not found`
Uma política de autorização rejeita a requisição	`403`	`RBAC: Access Denied`
Um `directResponse` está configurado no serviço virtual	Definido pelo usuário	Definido pelo usuário

O plug-in CustomLocalReply intercepta essas respostas antes que elas cheguem ao serviço downstream e aplica suas substituições.

Pré-requisitos

Antes de começar, verifique se você tem:

Um gateway de entrada implantado. Para mais informações, consulte Crie um gateway de entrada.
O serviço HTTPBin em execução no cluster do plano de dados. Consulte Implantar o aplicativo HTTPBin

Referência de configuração

Campos de nível superior

Campo	Tipo	Obrigatório	Valores válidos	Descrição
`patch_context`	String	Sim	`GATEWAY`, `SIDECAR_INBOUND`	Contexto de execução. Defina como `GATEWAY` para um gateway ASM ou `SIDECAR_INBOUND` para um sidecar proxy.
`custom_error_pages`	CustomErrorPage[]	Sim	--	Lista de substituições de páginas de erro. Cada entrada mapeia um código de status gerado localmente para uma resposta personalizada.

Campos CustomErrorPage

Campo	Tipo	Obrigatório	Padrão	Descrição
`match_status_code`	Integer	Sim	--	Código de status gerado localmente a ser interceptado. Quando o gateway ou sidecar gera este código, a substituição abaixo é aplicada.
`return_status_code`	Integer	Sim	--	Código de status retornado ao serviço downstream no lugar do código correspondente.
`content_type`	String	Sim	--	Valor do cabeçalho de resposta `content-type` (por exemplo, `text/html; charset=UTF-8` ou `application/json`).
`headers`	Map[string]string	Não	null	Cabeçalhos de resposta adicionais a serem incluídos na resposta personalizada.
`body`	String	Sim	--	Corpo da resposta retornado ao serviço downstream.

Redirecionar um 404 para outra URL

Este exemplo intercepta a resposta 404 gerada por uma regra directResponse e a transforma em um redirecionamento 301.

Etapa 1: Implantar um VirtualService com resposta direta

Aplique o seguinte VirtualService à sua instância ASM. Ele configura o gateway para retornar um código de status 404 com o corpo not found para todas as requisições.

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: httpbin
  namespace: default
spec:
  gateways:
    - httpbin-gateway
  hosts:
    - '*'
  http:
    - directResponse:
        body:
          string: not found
        status: 404

Etapa 2: Ative o plug-in CustomLocalReply

Aplique a seguinte configuração de plug-in ao gateway de entrada ASM chamado ingressgateway. Ela corresponde ao código de status 404 e o substitui por um redirecionamento 301 para https://www.aliyun.com.

patch_context: GATEWAY
custom_error_pages:
  - match_status_code: 404
    return_status_code: 301
    headers:
      location: 'https://www.aliyun.com'
    content_type: text/html; charset=UTF-8
    body: moved

Verifique o redirecionamento

Abra um navegador e acesse o endereço IP do gateway ASM. O navegador redireciona para https://www.aliyun.com, confirmando que a configuração do plug-in está ativa.

Retornar uma página 403 personalizada

Este exemplo substitui a mensagem padrão RBAC: Access Denied por uma página de erro HTML personalizada quando uma política de autorização rejeita uma requisição.

Aplique a seguinte configuração de plug-in ao gateway de entrada ASM chamado ingressgateway:

patch_context: GATEWAY
custom_error_pages:
  - match_status_code: 403
    return_status_code: 403
    content_type: text/html; charset=UTF-8
    body: |
      <!DOCTYPE html>
      <html>
      <head><title>Access Denied</title></head>
      <body>
        <h1>403 - Access Denied</h1>
        <p>You do not have permission to access this resource.
           Contact your administrator if you believe this is an error.</p>
      </body>
      </html>

Quando uma política de autorização rejeita uma requisição, o gateway retorna esta página HTML em vez da mensagem de texto simples RBAC: Access Denied.

Retornar uma resposta de erro JSON

Este exemplo retorna um corpo de erro JSON estruturado para respostas 404, o que é útil para serviços de API que exigem um formato de erro consistente.

Aplique a seguinte configuração de plug-in ao gateway de entrada ASM chamado ingressgateway:

patch_context: GATEWAY
custom_error_pages:
  - match_status_code: 404
    return_status_code: 404
    content_type: application/json
    body: |
      {
        "error": {
          "code": 404,
          "message": "The requested resource was not found.",
          "status": "NOT_FOUND"
        }
      }

Quando o gateway gera uma resposta 404, o serviço downstream recebe um corpo JSON com uma estrutura de erro padronizada em vez da mensagem de texto simples not found.

Múltiplas substituições em uma única configuração

Defina várias entradas em custom_error_pages para lidar com diferentes códigos de status em uma única configuração de plug-in. O exemplo a seguir substitui tanto as respostas 404 quanto as 403:

patch_context: GATEWAY
custom_error_pages:
  - match_status_code: 404
    return_status_code: 404
    content_type: application/json
    body: |
      {
        "error": {
          "code": 404,
          "message": "The requested resource was not found.",
          "status": "NOT_FOUND"
        }
      }
  - match_status_code: 403
    return_status_code: 403
    content_type: application/json
    body: |
      {
        "error": {
          "code": 403,
          "message": "Access denied by authorization policy.",
          "status": "FORBIDDEN"
        }
      }