net/http: La pila HTTP de Go con "baterías incluidas"
Go incluye un servidor y cliente HTTP completo en su biblioteca estándar.
//
Busca en todas las páginas de la documentación
Go incluye un servidor y cliente HTTP completo en su biblioteca estándar.
Puedes construir APIs, proxies y herramientas CLI que llamen a servicios remotos sin importar un framework web.
Fundamentos de net/http recopila fragmentos ejecutables; artículos hermanos cubren enrutamiento, clientes, middleware, HTTP/2, pruebas y configuración de producción.
net/http implementa servidores y clientes HTTP/1.1 y HTTP/2 con enrutamiento (ServeMux), interfaces de manejador, agrupación de conexiones, TLS y utilidades para pruebas y proxy.HTTP en Go se centra en una interfaz:
type Handler interface {
ServeHTTP(ResponseWriter, *Request)
}Cualquier cosa que pueda responder a una solicitud HTTP implementa ServeHTTP.
http.HandlerFunc adapta funciones simples, por lo que la mayoría de los manejadores son cierres o estructuras pequeñas.
En el lado del servidor, http.Server posee el listener, la configuración TLS y los campos de tiempo de espera.
http.ListenAndServe es un envoltorio de conveniencia que crea un Server predeterminado y se bloquea hasta que el proceso finaliza o el listener falla.
El enrutamiento pasa a través de http.ServeMux, que mapea patrones de host, método y ruta a manejadores.
Go 1.22 amplió la coincidencia de patrones para que rutas como GET /users/{id} y POST /items/ sean de primera clase sin un enrutador de terceros.
En el lado del cliente, http.Client envía solicitudes.
Cada cliente tiene un http.Transport que gestiona las conexiones TCP, los apretones de manos TLS, las conexiones persistentes y la actualización a HTTP/2 cuando está habilitado.
El http.DefaultClient predeterminado no tiene tiempo de espera para las solicitudes y reutiliza un transporte compartido; está bien para scripts rápidos, pero es arriesgado en servidores.
El middleware no es una palabra clave de la biblioteca estándar.
Es el patrón de envolver un http.Handler con otro: el registro, la autenticación, la recuperación de pánicos y los IDs de solicitud se componen como envoltorios anidados alrededor de tu manejador de negocio.
Una solicitud entra a través del listener, se analiza en *http.Request, se empareja por el mux y se despacha al manejador más interno.
El manejador escribe en http.ResponseWriter; las cabeceras y el estado deben establecerse antes de que se transmita el cuerpo.
r.Context() transporta la cancelación cuando el cliente se desconecta o se disparan los tiempos de espera del servidor.
El código descendente debe pasar ese contexto a las llamadas a bases de datos y RPC.
Cliente Servidor net/http
| |
|------ TCP / TLS ------------>|
| | ReadHeaderTimeout
| | coincidencia ServeMux
| | cadena de middleware
| | Handler.ServeHTTP
|<----- respuesta --------------|
Las llamadas salientes reflejan la ruta en orden inverso: Client.Do selecciona o marca una conexión del pool, escribe la solicitud, lee la respuesta y devuelve el cuerpo (que el llamador debe cerrar).
| Componente | Rol del servidor | Rol del cliente |
|---|---|---|
ServeMux | Enruta al manejador | N/A |
http.Server | Tiempos de espera, TLS, apagado | N/A |
http.Client | N/A | Envía solicitudes, respeta el contexto |
Transport | N/A | Agrupa conexiones, HTTP/2 |
httputil.ReverseProxy | Reenvía al upstream | N/A |
Los frameworks como chi, gin y echo todavía se basan en manejadores de net/http.
Agregan enrutamiento más rico, vinculación y registros de middleware, pero exportan puntos de entrada compatibles con http.Handler.
Los servicios de producción establecen tiempos de espera explícitos del servidor: ReadHeaderTimeout, ReadTimeout, WriteTimeout e IdleTimeout protegen contra diferentes modos de fallo.
Los ataques Slowloris, las cargas colgadas y las fugas de conexiones inactivas son problemas de la biblioteca estándar que resuelves con campos en http.Server, no con magia del framework.
HTTP/2 está habilitado por defecto para listeners TLS en versiones recientes de Go.
HTTP/2 en texto plano (h2c) requiere una configuración explícita cuando terminas TLS en un balanceador de carga y hablas h2c internamente.
httputil.ReverseProxy implementa patrones de gateway y BFF: reescribe rutas, inyecta cabeceras y transmite cuerpos sin almacenar en búfer cargas útiles completas.
Empareja esto con http.Transport ajustado para conexiones persistentes upstream.
Los ganchos de observabilidad se adjuntan en los límites del middleware: envuelve ResponseWriter para capturar códigos de estado, propaga IDs de traza desde las cabeceras al context y emite métricas por patrón de ruta.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
net/http puro | Dependencias mínimas, control total | Más código repetitivo para enrutamiento/características | APIs pequeñas, proxies, sidecars |
| chi / routers mux | Compatible con la biblioteca estándar, ligero | Todavía sin validación/ORM | Servicios REST que desean mejores rutas |
| gin / echo | Rápida experiencia de desarrollador, ayudantes de vinculación | Opiniones más pesadas | Equipos que desean "baterías incluidas" |
| gRPC + grpc-gateway | Contratos sólidos | No es nativo de HTTP | Mallas de servicios, RPC interno |
ListenAndServe está listo para producción de inmediato - Funciona para demostraciones, pero la falta de tiempos de espera, TLS y apagado elegante te afectará bajo tráfico real.func(http.Handler) http.Handler; los frameworks solo recopilan y ordenan envoltorios.http.Get está bien dentro de los manejadores - http.DefaultClient no tiene tiempo de espera y comparte estado global; usa un http.Client dedicado por dependencia.{id} sin gorilla/mux.La biblioteca estándar proporciona servidor, cliente, TLS, HTTP/2, ayudantes de prueba y utilidades de proxy inverso en una sola ruta de importación.
No incluye validación, plantillas más allá de ayudantes básicos ni andamiaje de proyectos.
Elige chi, gin o echo cuando desees rutas agrupadas, vinculación de parámetros o un gran ecosistema de middleware listo para usar.
Quédate con net/http puro cuando el recuento de dependencias y el control explícito importen más que los atajos de la experiencia del desarrollador.
Cada *http.Request transporta Context() que se cancela ante la desconexión del cliente y los límites de tiempo de espera del servidor.
Los manejadores deben pasarlo a todas las llamadas bloqueantes posteriores.
http.DefaultServeMux es un singleton global.
Prefiere un http.NewServeMux() dedicado por servicio para que las pruebas y las bibliotecas no registren rutas en conflicto.
Sí, para listeners TLS con negociación ALPN.
h2c en texto plano requiere una configuración explícita de Server y Transport.
Handler es una interfaz con ServeHTTP.
HandlerFunc es un tipo de función que implementa Handler, lo que te permite escribir manejadores func(w, r) sin una estructura.
Sí.
Termina TLS en el ingress o pod, establece ReadHeaderTimeout y usa Shutdown para implementaciones continuas.
httptest.ResponseRecorder captura respuestas en memoria.
httptest.NewServer inicia un listener real para pruebas de estilo de integración.
La agrupación de http.DefaultTransport se comparte y sus valores predeterminados pueden no coincidir con tus necesidades de latencia o TLS.
Un Transport dedicado por dependencia saliente aísla la optimización y los tiempos de espera.
Sí, cuando los manejadores evitan asignaciones por solicitud, reutilizan clientes y establecen límites de conexión inactiva.
Realiza perfiles antes de asumir que un framework es más rápido; a menudo, el cuello de botella es la lógica de la aplicación, no la biblioteca estándar.
La conexión se aborta a menos que el middleware de recuperación atrape el pánico y devuelva 500.
Siempre agrega recuperación en la capa de middleware más externa en producción.
Llama a server.Shutdown(ctx) para dejar de aceptar nuevas conexiones y esperar las solicitudes en curso.
Combínalo con el manejo de señales en main y un contexto de apagado limitado.
Versiones de la pila: Esta página se escribió para Go 1.26.x (predeterminado Green Tea GC, 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).
Revisado por Chris St. John·Última actualización: 16 jul 2026