API do Zero

Imagine o balcão de uma oficina. O cliente entrega uma ordem de serviço com o que deseja; a pessoa no balcão lê o pedido e preenche uma resposta. Ela não dirige até a casa do cliente nem controla a rua. Seu trabalho começa quando recebe o pedido e termina quando registra o resultado. Um handler HTTP ocupa essa fronteira: recebe uma requisição e escreve uma resposta.

Essa separação resolve um problema concreto. Se a regra de resposta depende de abrir uma porta TCP, escolher uma porta livre e fazer uma chamada pela rede, cada teste fica lento e sujeito ao ambiente. Em Go, o contrato central é a interface http.Handler, com o método ServeHTTP(http.ResponseWriter, *http.Request). Você pode executar esse contrato inteiramente em memória. O servidor de produção e o teste entregam os mesmos dois argumentos.

*http.Request descreve o que chegou: método, caminho, headers, corpo e contexto. http.ResponseWriter é o destino da resposta. Primeiro você ajusta headers; depois escolhe o status; por fim escreve o corpo. A primeira escrita do corpo envia implicitamente 200 OK quando nenhum status foi informado. Essa conveniência também cria uma armadilha: tentar mudar o status depois de escrever já é tarde.

O handler não devolve uma resposta como valor. Ele produz efeitos no ResponseWriter. Em produção, esses efeitos viram bytes na conexão. Com httptest.NewRecorder, viram campos inspecionáveis: Code, Header() e Body. A mesma função fica útil no trabalho e verificável sem rede, sem espera e sem processo auxiliar.

Há três detalhes de protocolo que merecem uma inspeção mais lenta. O status representa o resultado da operação, não o estado geral do processo. Um endpoint de saúde pode usar 204 porque não precisa entregar representação; uma criação costuma usar 201; uma entrada inadequada usa 400. Escolher sempre 200 força todo consumidor a abrir o corpo para saber se a operação funcionou e piora métricas de erro.

Headers descrevem como interpretar ou tratar a resposta. Content-Type fala do corpo enviado; Allow informa quais métodos um recurso aceita. Eles não são comentários opcionais. Um navegador, proxy ou SDK pode decidir comportamento com base neles. No teste, afirmar headers impede uma regressão que não apareceria ao comparar somente texto.

O corpo é uma sequência de bytes. Converter string em []byte deixa essa fronteira explícita. Para texto pequeno, a alocação é aceitável; para respostas estruturadas, um encoder escreverá no writer. O importante agora é perceber que chamadas sucessivas a Write concatenam partes da mesma resposta, não criam respostas separadas.

Também há diferença entre função handler e valor handler. Uma função comum com a assinatura certa ganha o método ServeHTTP por meio de http.HandlerFunc. Esse adapter é um tipo da biblioteca, não geração mágica. Já um struct pode implementar ServeHTTP diretamente e guardar logger, store ou configuração. Comece com função; migre para struct quando dependências justificarem estado nomeado.