Interceptadores HTTP - AWS SDK for Go v2
Comparação entre interceptadores e middlewareHooks de interceptadores disponíveisRegistro do interceptadorConfiguração do interceptador global

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Interceptadores HTTP

Você pode usar interceptadores para adicionar um hook à execução de solicitações e respostas de API. Os interceptadores são mecanismos abertos nos quais o SDK chama o código que você escreve para injetar comportamento no ciclo de vida da solicitação/resposta. Dessa maneira, é possível modificar uma solicitação em andamento, depurar o processamento da solicitação, visualizar exceções e muito mais.

Comparação entre interceptadores e middleware

O AWS SDK for Go v2 fornece interceptadores e middleware para personalizar o processamento de solicitações. Embora ambos tenham propósitos semelhantes, eles foram projetados para públicos e casos de uso diferentes:

  • Os interceptadores foram projetados para usuários do SDK que desejam personalizar o processamento de solicitações/respostas com uma API simples e focada em HTTP. Eles fornecem pontos de hook específicos no ciclo de vida da solicitação e trabalham diretamente com solicitações e respostas HTTP.

  • O middleware é um sistema mais avançado, independente do tipo de transporte, usado principalmente de forma interna pelo SDK. Embora seja potente, o middleware exige um conhecimento mais profundo dos componentes internos do SDK e envolve interfaces mais complexas.

Principais vantagens dos interceptadores em relação ao middleware para casos de uso comuns:

  • Foco em HTTP: os interceptadores trabalham diretamente com solicitações e respostas HTTP, eliminando a necessidade de verificação do tipo de transporte exigida pelo middleware.

  • Interfaces mais simples: cada hook do interceptador tem uma interface específica e focada, em vez do padrão genérico de middleware.

  • Modelo de execução mais claro: os interceptadores executam em pontos bem definidos no ciclo de vida da solicitação sem exigir conhecimento da ordenação da pilha de middleware.

nota

Os interceptadores são construídos sobre o sistema de middleware existente, para que ambos possam coexistir na mesma aplicação. O middleware permanece disponível para casos de uso avançados que exigem comportamento independente de transporte ou manipulação complexa de pilhas.

Hooks de interceptadores disponíveis

O AWS SDK for Go v2 fornece hooks de interceptadores em vários estágios do ciclo de vida da solicitação. Cada hook corresponde a uma interface específica que você pode implementar:

  • BeforeExecution: primeiro hook chamado durante a execução da operação

  • BeforeSerialization: antes de a mensagem de entrada ser serializada na solicitação de transporte

  • AfterSerialization: depois de a mensagem de entrada ser serializada na solicitação de transporte

  • BeforeRetryLoop: antes de entrar no loop de novas tentativas

  • BeforeAttempt: primeiro hook chamado dentro do loop de novas tentativas

  • BeforeSigning: antes da assinatura da solicitação de transporte

  • AfterSigning: depois da assinatura da solicitação de transporte

  • BeforeTransmit: antes da assinatura da solicitação de transporte

  • AfterTransmit: depois de receber a resposta de transporte

  • BeforeDeserialization: antes de a resposta de transporte ser desserializada

  • AfterDeserialization: depois de fazer unmarshalling da resposta de transporte

  • AfterAttempt: último hook chamado dentro do loop de novas tentativas

  • AfterExecution: último hook chamado durante a execução da operação

Você pode implementar várias interfaces em um único interceptador para fazer hook em vários estágios do ciclo de vida da solicitação.

Registro do interceptador

Você registra interceptadores ao construir um cliente de serviço ou ao substituir a configuração de uma operação específica. O registro difere dependendo se você deseja que o interceptador se aplique a todas as operações do cliente ou apenas a operações específicas.

Os interceptadores são gerenciados por meio de um registro de interceptadores que fornece métodos para adicioná-los e removê-los. O exemplo a seguir mostra um interceptador simples que adiciona um cabeçalho de ID de rastreamento do AWS X-Ray às solicitações enviadas antes do processo de assinatura: 

type recursionDetection struct{}

func (recursionDetection) BeforeSigning(ctx context.Context, in *smithyhttp.InterceptorContext) error {
    if traceID := os.Getenv("_X_AMZN_TRACE_ID"); traceID != "" {
        in.Request.Header.Set("X-Amzn-Trace-Id", traceID)
    }
    return nil
}

// use it on the client
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.Interceptors.AddBeforeSigning(recursionDetection{})
})

O registro do interceptador é adicionado às opções do cliente, o que viabiliza a configuração do interceptador por operação: 

// ... or use it per-operation
s3.ListBuckets(context.Background(), &s3.ListBucketsInput{
}, func(o *s3.Options) {
   o.Interceptors.AddBeforeSigning(recursionDetection{})
})

Configuração do interceptador global

Você também pode registrar interceptadores globalmente usando a função config.LoadDefaultConfig com as opções With* apropriadas para cada tipo de interceptador. Isso aplica o interceptador a todos os clientes de serviço da AWS criados com base nessa configuração: 

type myExecutionInterceptor struct{}

func (*myExecutionInterceptor) AfterExecution(ctx context.Context, in *smithyhttp.InterceptorContext) error {
    // Add your custom logic here
    return nil
}

cfg, err := config.LoadDefaultConfig(context.Background(),
    config.WithAfterExecution(&myExecutionInterceptor{}))
if err != nil {
    panic(err)
}

// every service client created from the above config
// will include this interceptor
svc := s3.NewFromConfig(cfg)