Resumen de Puntos Clave de gRPC y Protobuf

Cada punto clave de las 9 páginas de esta sección, reunido en una sola página y agrupado por la página de la que proviene.

gRPC en Go: Contratos, Streaming y Rendimiento

• Los esquemas de Protobuf son el contrato; los tipos Go generados lo aplican en tiempo de compilación
• La multiplexación HTTP/2 y el framing binario reducen la latencia en comparación con JSON REST
• El streaming unario, del servidor, del cliente y bidireccional se mapean a cuatro formas de RPC
• Los plazos y los códigos de estado propagan los fallos a través de los límites del servicio
• gRPC brilla en la comunicación este-oeste; los navegadores y las API públicas a menudo necesitan una puerta de enlace

Conceptos Básicos de gRPC

• Nunca reutilices números de campo proto una vez asignados para evitar romper la compatibilidad
• La directiva go_package controla la ruta de importación y el nombre del paquete de Go para el código generado
• Usa --go_out y --go-grpc_out por separado para generar mensajes y stubs de servicio
• Incrusta Unimplemented en los servidores para evitar fallos de compilación al agregar nuevas RPC
• Usa los accesores GetName() para el manejo seguro de mensajes nulos en implementaciones de servidor
• Llama a Close() en las conexiones del cliente al apagar para liberar los recursos de la conexión HTTP/2

Diseño de Esquemas de Protocol Buffers

• Los números de campo son permanentes; reutilizar etiquetas antiguas en contextos nuevos rompe la compatibilidad retroactiva
• Agrega campos opcionales con números nuevos; cambiar los tipos en etiquetas existentes siempre rompe la compatibilidad
• Renombra campos de forma segura manteniendo el número sin cambios; el formato de cable depende solo de la etiqueta y el tipo
• Reserva los números y nombres de campo eliminados para evitar su reutilización accidental en versiones futuras
• Los decodificadores ignoran los campos desconocidos, lo que hace que la compatibilidad hacia adelante sea automática sin actualizaciones del cliente
• Los valores cero de Enum deben ser UNSPECIFIED; nunca trates cero como un estado de negocio significativo

RPC Unarias, de Streaming y Bidireccionales

• Cuatro formas de RPC: unaria (1-1), flujo del servidor (1-N), flujo del cliente (N-1), bidireccional (N-N)
• Go modela los flujos con métodos Send/Recv en los tipos generados del cliente y del servidor
• El streaming del cliente termina cuando Recv devuelve io.EOF, el servidor responde con SendAndClose
• En el streaming bidireccional, ambos lados intercalan Send y Recv, el orden importa
• Devuelve un error no nulo para abortar la RPC con un tráiler de estado gRPC
• Pasa stream.Context() hacia abajo para que la desconexión del cliente cancele el trabajo del productor

Middleware, Interceptores y Metadatos de gRPC

• Los interceptores centralizan la autenticación, el registro, el rastreo y los reintentos antes de la ejecución del manejador
• Lee los metadatos entrantes usando metadata.FromIncomingContext en los interceptores del servidor
• Encadena múltiples interceptores a través de grpc.ChainUnaryInterceptor; el primero listado es el más externo
• Rechaza temprano con codes.Unauthenticated antes de que se ejecuten los manejadores para fallar rápidamente
• Agrega metadatos salientes en el contexto del cliente con metadata.AppendToOutgoingContext
• Los metadatos binarios usan claves con el sufijo -bin, codificados en base64 en el cable en algunas herramientas

Códigos de Error y Mapeo de Estado de gRPC

• Los errores cruzan los límites como códigos de estado, no como cadenas de error de Go; los clientes inspeccionan los códigos
• Los servidores devuelven status.Error; los clientes desempaquetan con status.FromError
• Dieciséis códigos estándar cubren la mayoría de los escenarios de sistemas distribuidos
• Adjunta detalles estructurados a través de status.New y WithDetails para campos legibles por máquina
• Usa FailedPrecondition para violaciones de reglas de negocio; NotFound para recursos faltantes
• errors.New simple se convierte en codes.Unknown a menos que se convierta explícitamente a estado gRPC

Guía de Compensación REST vs gRPC

• Los servicios internos usan gRPC para obtener verificaciones en tiempo de compilación y evitar la sobrecarga de serialización
• REST en el borde controla el tráfico público mientras que los servicios internos permanecen en protobuf
• Expón REST con OpenAPI para los webhooks de socios para evitar la fricción de la compilación de .proto
• El streaming gRPC con multiplexación HTTP/2 supera a REST por solicitud para la telemetría
• Construye un MVP con REST primero para validar el ajuste del producto antes de optimizar la eficiencia
• Usa gRPC más protobuf para flotas políglotas para habilitar stubs tipados entre lenguajes

gRPC Gateway y Transcodificación JSON

• Anota los archivos .proto con google.api.http para generar automáticamente rutas REST JSON
• Gateway deserializa JSON a protobuf, invoca el método gRPC, serializa la respuesta de vuelta
• Un proto genera servidores gRPC de Go, rutas REST y documentación OpenAPI
• Habilita credenciales TLS tanto en las conexiones de gateway a backend como de cliente a gateway
• Las limitaciones de streaming y encabezados de autenticación personalizados de Gateway complementan, no reemplazan, el gRPC nativo
• Las plantillas de ruta como {name} se enlazan a los campos del mensaje protobuf en las solicitudes transcodificadas

Mejores Prácticas de gRPC

• Trata los archivos .proto como migraciones de bases de datos con las comprobaciones de rotura de buf
• Establece plazos de cliente en cada RPC saliente
• Usa interceptores para autenticación, registro y recuperación, no para copiar y pegar en el manejador
• Registra comprobaciones de salud de gRPC para las sondas de Kubernetes
• Planifica el balanceo de carga consciente de la conexión para flujos HTTP/2