Mejores prácticas de gRPC

Versionado de protos, plazos y balanceo de carga de gRPC en K8s.

Estas reglas mantienen los contratos estables, los RPCs observables y los despliegues seguros, desde el portátil hasta los clústeres de producción.

Cómo usar esta lista

• Aplique durante cambios de esquema, andamiaje de servicios y revisiones de plataforma.
• Ejecute buf breaking (o equivalente) en CI antes de fusionar ediciones de .proto.
• Empareje con golangci-lint y pruebas de integración que se conecten a servidores reales a través de bufconn.
• Revise cuando cambien las plataformas de entrada, malla o cliente.

A - Esquema y versionado

• Nunca reutilice ni renumeré campos de protobuf. Reserve las etiquetas y nombres eliminados en los archivos .proto.
• Versionar paquetes (v1, v2) para cambios incompatibles en la API. Ejecute servidores duales o RPCs duales durante las ventanas de migración.
• Ejecute la detección de cambios de rotura en CI contra la rama principal. Bloquee fusiones que cambien tipos de campo o números de cable.
• Mantenga estables las opciones go_package y package de Java. Mover las rutas de importación generadas rompe los módulos descendentes de forma silenciosa.
• Utilice optional o FieldMask para actualizaciones parciales. Distinga los campos no establecidos de los valores cero intencionales.

B - Implementación del servidor

• Incorpore Unimplemented<Service>Server en cada struct de servicio. Compatibilidad futura cuando se añadan RPCs.
• Devuelva status.Error con el código estándar más cercano. Reserve Internal para errores reales, no para fallos de validación.
• Adjunte detalles estructurados (ErrorInfo, BadRequest) para errores legibles por máquina. Las pasarelas y los clientes pueden ramificarse sin analizar cadenas.
• Respete la cancelación de context en manejadores largos y bucles de transmisión. Detenga el trabajo cuando los clientes se desconecten.
• Habilite la reflexión solo en entornos de depuración no de producción o autenticados. La reflexión expone toda su superficie de API.

C - Llamadas y resiliencia del cliente

• Establezca un plazo o tiempo de espera en cada contexto de cliente. El valor predeterminado "sin plazo" se cuelga para siempre detrás de backends lentos.
• Reintente solo RPCs unarios idempotentes en Unavailable con retroceso y jitter. Evite tormentas de reintentos durante las interrupciones.
• Reutilice grpc.ClientConn entre solicitudes. Marcar por RPC desperdicia apretones de manos TCP y TLS.
• Cierre las conexiones al apagar el proceso. Libere los recursos HTTP/2 limpiamente junto con GracefulStop en los servidores.
• Mapee códigos reintentables frente a fatales explícitamente en las bibliotecas cliente. Documente el comportamiento para los equipos de aplicaciones.

D - Interceptores, metadatos y seguridad

• Centralice la validación JWT/mTLS en interceptores unarios y de transmisión. Los manejadores asumen que la identidad ya ha sido verificada.
• Propague el contexto de traza a través de metadatos (traceparent o portadores OTel). Empareje con manejadores otelgrpc para spans.
• Mantenga los secretos en metadatos o TLS, no en campos de registro de protobuf. Redacte las cabeceras de autorización en los interceptores de registro.
• Utilice credenciales TLS en producción para clientes y servidores. Las credenciales insecure son solo para desarrollo local.
• Registre interceptores de recuperación de pánico en el límite del servidor. Los pánicos se convierten en Internal con rastros de pila registrados.

E - Streaming y rendimiento

• Elija por defecto RPCs unarios hasta que se demuestre que la transmisión es necesaria. Operaciones y balanceadores de carga más simples.
• Maneje io.EOF como fin normal de transmisión, no siempre como error. Devuelva el estado apropiado solo en las rutas de fallo.
• Limite el búfer en memoria en las transmisiones de cliente y servidor. Procese o descarte fragmentos en lugar de rebanadas ilimitadas.
• Ajuste los tamaños máximos de mensaje de manera consistente en clientes, servidores y pasarelas. Alinee los límites de extremo a extremo.
• Configure keepalive para NATs y balanceadores de carga L4 inactivos. Evite caídas silenciosas de TCP en conexiones HTTP/2 de larga duración.

F - Kubernetes y operaciones

• Registre grpc.health.v1 y conecte las sondas de liveness/readiness. Establezca NOT_SERVING hasta que las dependencias estén listas.
• Utilice balanceo de carga consciente de la conexión (Servicio headless, malla o xDS). La rotación L4 ingenua rompe los flujos HTTP/2.
• Llame a GracefulStop en SIGTERM con una reserva Stop acotada. Coincida con terminationGracePeriodSeconds del pod.
• Exponha grpc-gateway o BFF para clientes JSON en lugar de perforar gRPC a través de la entrada pública ciegamente.
• Documente los pasos de depuración de grpcurl para el personal de guardia. Incluya las cabeceras de metadatos requeridas y los puntos de conexión de staging.

Preguntas frecuentes

Relacionado

• gRPC en Go: Contratos, Streaming y Rendimiento - resumen de la sección
• Conceptos básicos de gRPC - patrones de configuración
• Diseño de esquemas de Protocol Buffers - reglas de evolución
• Middleware, Interceptores y Metadatos de gRPC - preocupaciones transversales
• Guía de compensación REST vs gRPC - decisiones de transporte

Enlaces externos relacionados

• pkg.go.dev - Sitio oficial de documentación y descubrimiento de paquetes.
• Effective Go - Guía oficial para escribir Go claro e idiomático.
• Go Blog (Oficial) - Anuncios oficiales, análisis profundos y notas de versión.
• Learning Go (2ª Edición) - Jon Bodner.
• The Go Programming Language (ebook) - Donovan & Kernighan.

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