Mejores prácticas de net/http

Servicios HTTP sin framework que escalan y se apagan limpiamente.

Aplica estas reglas en la revisión de código, plantillas de servicios y pruebas de carga para que cada superficie de stdlib HTTP se comporte de manera predecible bajo tráfico de producción.

Cómo usar esta lista

• Marca las reglas a medida que tu plantilla de servicio las adopte.
• Codifica los elementos de Nivel A en bots de revisión de CI o pruebas unitarias de arquitectura cuando sea posible.
• Empareja las reglas de tiempo de espera con tablas de SLO documentadas por dependencia externa.
• Revisa al añadir gateways, WebSockets o nuevas APIs de salida.

A - Servidor y enrutamiento

• Construye http.NewServeMux() en main, no http.DefaultServeMux. Previene colisiones de rutas por importación entre paquetes.
• Establece ReadHeaderTimeout en cada http.Server de producción. Bloquea ataques de lentitud de cabeceras estilo slowloris antes de que se ejecuten los manejadores.
• Configura IdleTimeout para recuperar conexiones keep-alive. Detiene fugas de descriptores en clientes inactivos.
• Usa patrones de métodos y rutas de Go 1.22+ para rutas REST. Mantiene la coincidencia de métodos declarativa y testeable.
• Limita los cuerpos POST con http.MaxBytesReader. Rechaza cargas útiles sobredimensionadas antes del trabajo de decodificación JSON.

B - Ciclo de vida elegante

• Maneja SIGINT/SIGTERM y llama a server.Shutdown(ctx). Los despliegues continuos vacían el trabajo en curso en lugar de forzar el cierre.
• Vincula el contexto de apagado al período de gracia del orquestador. Evita colgarse más allá de los terminationGracePeriodSeconds de Kubernetes.
• Deja de aceptar nuevo trabajo antes de cerrar dependencias. Apaga primero el oyente HTTP, luego los pools y clientes de la base de datos.
• Expón un /health barato sin middleware de autenticación. Los balanceadores de carga necesitan una señal de liveness rápida.
• Documenta las rutas de streaming exentas de WriteTimeout. SSE y long polls necesitan excepciones explícitas de tiempo de espera.

C - Manejadores y contexto

• Pasa r.Context() como primer argumento a todas las llamadas bloqueantes posteriores. Honra la desconexión del cliente y los plazos del servidor.
• Retorna silenciosamente en context.Canceled cuando la respuesta no se puede enviar. Evita 500s engañosos después de que el cliente se ha ido.
• Establece Content-Type antes de escribir cuerpos JSON. Previene respuestas ambiguas y clientes rotos.
• Llama a WriteHeader una vez; usa http.Error para fallos. La primera Write bloquea el estado a 200 si las cabeceras no se enviaron.
• Cierra o lee completamente r.Body en cada ruta. Requerido para la reutilización de conexiones keep-alive en el lado del servidor.

D - Middleware

• Coloca la recuperación de pánicos más externamente en la cadena de middleware. Los pánicos internos se convierten en respuestas 500 sin salir del proceso.
• Autentica antes de los manejadores de negocio pero después de la recuperación/registro. La autenticación fallida se interrumpe sin tocar la lógica de dominio.
• Envuelve ResponseWriter para capturar el estado para métricas y registros de acceso. El escritor predeterminado oculta el estado final del middleware.
• Almacena metadatos de solicitud en el contexto con tipos de clave no exportados. Evita colisiones de claves de cadena entre bibliotecas.
• Permite explícitamente las rutas de salud y métricas en el middleware de autenticación. Las sondas no deberían necesitar credenciales de servicio.

E - Clientes de salida

• Inyecta un http.Client por dependencia externa. Aísla los tiempos de espera y la sintonización del transporte por SLA.
• Nunca llames a http.Get desde manejadores. http.DefaultClient no tiene tiempo de espera y es global para el proceso.
• Siempre defer resp.Body.Close() después de client.Do. Los cuerpos filtrados agotan los pools de conexiones.
• Vacía los cuerpos de respuesta de error antes de cerrar al reutilizar keep-alive. io.Copy(io.Discard, resp.Body) en rutas no 2xx.
• Establece MaxIdleConnsPerHost para servicios externos activos. Reduce el cambio de TLS y TCP bajo QPS constante.

F - Proxies, TLS y HTTP/2

• Establece un Transport personalizado en httputil.ReverseProxy. El transporte predeterminado se comparte y no está sintonizado para rutas de gateway.
• Implementa ErrorHandler en proxies inversos. Mapea los tiempos de espera de conexión y cabecera a 502/504 de manera consistente.
• Establece tls.Config.MinVersion a TLS 1.2 o superior. Documenta la postura de cifrado aceptable para oyentes externos.
• Conoce si los pods hablan HTTP/2, h2c o HTTP/1.1 detrás del ingress. La configuración incorrecta se manifiesta como errores latentes de multiplexación.
• Confía en X-Forwarded-* solo de balanceadores de carga conocidos. Previene metadatos de IP y esquema falsificados por el cliente.

Preguntas frecuentes

Relacionado

• net/http: La pila HTTP "Batteries-Included" de Go - ancla conceptual
• Conceptos básicos de net/http - ejemplos de inicio ejecutables
• Lista de verificación de configuración de net/http en producción - verificación previa al despliegue
• HTTP/2, Tiempos de espera y ReverseProxy - profundidad de tiempo de espera y proxy
• Cadenas de Middleware y Contexto de Solicitud - orden de middleware

Versiones de la pila: Esta página fue escrita para Go 1.26.x (predeterminado GC Green Tea, go fix modernizers - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de la placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).