La primera versión del contrato de un servicio es fácil. Lo difícil es la versión cuatro, cuando tres equipos dependen de la forma anterior, un consumidor sigue en una versión móvil del año pasado y el campo que quieres renombrar sostiene todo.

gRPC te da herramientas potentes para esto. No te da disciplina.

Diseña para evolucionar, no para la pureza

Protobuf está construido alrededor del cambio aditivo. Aprovéchalo:

  • Agrega campos; no reutilices los existentes.
  • Reserva números y nombres de campo cuando elimines algo.
  • Mantén los enums abiertos manejando valores desconocidos, o pon un valor nuevo detrás de una bandera de capacidad.
  • Prefiere optional y tipos wrapper cuando “sin definir” es distinto de cero.

Un esquema un poco redundante que sobrevive tres años de cambios es mejor que uno elegante que obliga a un despliegue sincronizado de todos los consumidores.

Las fronteras siguen a la propiedad

Un fallo común es un paquete de protos “compartido” que todos los servicios importan y todos los equipos editan. En un trimestre contiene campos que nadie posee y comentarios que contradicen el código.

Pon los contratos junto al equipo dueño del dominio, publícalos como artefactos versionados y trata un cambio incompatible como un cambio de API pública, porque lo es. Si dos servicios necesitan negociar el mismo esquema a diario, probablemente son un solo servicio con un salto de red caro.

Los errores son parte del contrato

Los códigos de estado HTTP no bastan. Define tu modelo de errores explícitamente con detalles de google.rpc.Status o un payload de error del dominio. Los consumidores necesitan distinguir:

  • fallo transitorio reintentable,
  • entrada inválida que el cliente puede corregir,
  • fallo de autorización,
  • y “esto nunca va a funcionar, deja de reintentar”.

Si el cliente no puede distinguirlos, reintentará todos.

Prueba las fronteras

Las pruebas de contrato detectan fallos que las pruebas unitarias no ven: renombres de campos, deriva de enums y un valor por defecto que cambia de significado en silencio. Genera clientes en CI y compila contra el artefacto publicado. No es glamoroso y es el seguro más barato que comprarás este trimestre.

Las buenas fronteras son aburridas. Las peticiones son rápidas, los fallos son legibles y nadie necesita una reunión para agregar un campo.