Compatibilidad inversa

¿Qué es la compatibilidad retroactiva?

Compatibilidad inversa (backward compatibility): propiedad del sistema de aceptar y manejar correctamente clientes/consumidores antiguos cuando el sistema se actualiza. Más fácil: está lanzando una nueva versión del servicio/evento, y las integraciones ya existentes continúan funcionando sin cambios.

Clave: no romper los arreglos. Cualquier evolución es a través de la adición, no de la alteración de lo ya lanzado.

Principios básicos

1. Additive-first

Los nuevos campos/métodos/eventos se agregan opcionalmente. Nada existente se elimina y no cambia de sentido.

2. Contrato de garantía mínima (MGC)

Definir kernel: un conjunto de campos/operaciones sin los cuales el script pierde sentido. El núcleo es estable. Todo lo demás son extensiones.

3. Tolerant reader

Los clientes ignoran campos desconocidos y manejan correctamente los nuevos valores de enum (fallback).

4. Directiva de versiones

Los cambios rompedores son sólo a través de la línea mayor ('/v2 ',' pagos. v2`, `event. v2`). Los menores son aditivos.

5. Observabilidad - parte del contrato

En los logs/tries y métricas se ve la versión del cliente, el formato, las banderas de capability. Esto le permite administrar la migración.

Cambios peligrosos seguros vs

Normalmente seguros (BC-OK)

Agregar campos opcionales (JSON/Avro/Protobuf 'optional '/' nullable').
Agregar nuevos endpoints/métodos/eventos.
Extensión enum con valores adicionales (en tolerant reader).
Atenuar la validación (aumentar los máximos, añadir formatos alternativos).
Agregar títulos/metadatos que no afecten al significado.

Peligros

Eliminar/cambiar el nombre de los campos, cambiar el tipo o la obligatoriedad de los campos existentes.
Cambio de semántica de estados/códigos de error.
Vuelva a utilizar las etiquetas protobuf en otros campos.
Cambia la clave de partición del evento (rompe el orden del agregado).
Endurecimiento de los SLA/Timeout, lo que hace que los viejos clientes empiecen a caer.

Por estilos de

REST/HTTP + JSON

Aditividad: los nuevos campos son 'optional', el servidor no los requiere de clientes antiguos.
Versiones: mayor - en ruta ('/v2 ') o mediatipo; minor - a través de extensiones y '? include = '/'? fields ='.
Errores: formato único; no cambiar códigos/semántica sin mayor.
ETag/If-Match: para apdates seguros sin carreras.
Idempotencia: 'Idempotency-Key' para POST: los clientes antiguos no «duplican» el efecto de retraerse.

gRPC / Protobuf

Las etiquetas no cambian. No se pueden volver a utilizar las etiquetas eliminadas.
Los nuevos campos son 'optional '/' repeated'; los valores predeterminados se procesan correctamente con el código antiguo.
Streaming: no cambiar el orden/obligatoriedad de los mensajes dentro del minor.
Errores: conjunto estable de estados; nueva semántica → nuevo método/servicio ('.v2').

Event-driven (Kafka/NATS/Pulsar) + Avro/JSON/Proto

Nomenclatura: 'domain. action. v{major}`.
Core vs Enriched: el núcleo es estable; enriquecimiento - tipos/temas separados ('.enriched').
Modo de compatibilidad de esquemas: más comúnmente BACKWARD; CI bloquea los cambios incompatibles.
Partición: la clave (por ejemplo, 'payment _ id') es parte del contrato; cambiarlo - breaking.

GraphQL

Agregar campos/tipos - Aceptar; eliminación/cambio de nombre - a través de '@ deprecated' y la ventana de migración.
No aumente «nullable → no nullable» sin mayor.
Controle complexity/depth: cambiar los límites = cambiar el contrato.

Patrones que ayudan a guardar BC

Modelo de pirámide inversa: estabilizar el núcleo, expandir opcionalmente.
Capability negotiation: el cliente informa de las capacidades soportadas ('X-Capabilities '/handshake), el servidor se ajusta.
Dual-run/dual-emit: mantenga el 'v1' y el 'v2' al mismo tiempo mientras dure la migración.
Adaptadores: proxy/gateway traduce solicitudes de 'v1↔v2' para clientes «pesados».
Expand-and-contract (para BD): primero agregue uno nuevo, comience a escribir/leer, solo después elimine el antiguo.

Gobierno y proceso

1. Catálogo de contratos (registro de esquemas): una única fuente de verdad con políticas de compatibilidad.
2. Linters y cheques diff en CI/CD: OpenAPI-diff, Buf-breaking, validación de compatibilidad Avro/JSON Schema.
3. Contratos CDC/Consumer-Driven: el proveedor es examinado por los contratos reales de los consumidores.
4. Muestras de oro: consultas de referencia/respuestas/eventos de regresión.
5. Gestión de cambios: RFC/ADR en breaking, planes sunset, comunicación.

Deprechate y eliminación de versiones antiguas

Marque obsoleto ('@ deprecated', descripciones, encabezados 'Deprecation', 'Sunset').
Ventana de migración: fecha previamente anunciada, banco de pruebas, código de ejemplo.
Telemetría de uso: ¿quién más en 'v1'? segmentar métricas/registros por versión.
Dual-run a cero tráfico, a continuación, eliminar.

Observabilidad y métricas operativas

Porcentaje de solicitudes/mensajes por versión.
Porcentaje de errores/tiempos de espera en clientes antiguos después de la liberación.
Porcentaje de payload incompatible (validación del esquema en la puerta de enlace/filtros de flujo).
Lag de migración de consumidores (cuántos más escuchan 'v1').

Pruebas de compatibilidad retroactiva

Schema-diff: fail при remove/rename/type-change.
Pruebas de contrato: los antiguos SDK/clientes se enfrentan a una nueva implementación.
E2E-canario: parte del tráfico antiguo a la nueva versión, comparación p95/p99, códigos, retraídas.
Replay de eventos: las proyecciones se recogen con una nueva lógica desde el viejo registro sin discrepancias.
Fault-injection: retardos/respuestas parciales: los clientes antiguos no caen.

NAT (aditivo)

json
{ "id": "p1", "status": "authorized" }

json
{ "id": "p1", "status": "authorized", "risk_score": 0. 12 }

Los clientes antiguos, ignorando 'risk _ score', siguen funcionando.

Protobuf (etiquetas)

proto message Payment {
string id = 1;
string status = 2;
optional double risk_score = 3 ;//new field, safe
}
//Tags 1 and 2 cannot be changed/deleted without v2

Eventos (núcleo + enriquecimiento)

`payment. authorized. v1 'es el núcleo (mínimo de hechos).
`payment. enriched. v1 '- Piezas; los consumidores del núcleo son independientes del enriquecimiento.

Antipattern

Swagger-wash: ha actualizado el esquema, pero el servicio se comporta de forma antigua (o viceversa).
Roturas ocultas: cambiaron el significado del campo/estado sin versión.
Reutilización de etiquetas protobuf: corrupción de datos «silenciosa».
Clientes duros: caen en campos/enum desconocidos; No tolerant reader.
Mega-endpoint: un todo-en-uno - cualquier cambio se convierte en una fractura potencial.

Lista de comprobación antes de su lanzamiento

• Los cambios son aditivos; el núcleo (MGC) no está tocado.
• Se han pasado los cheques de linterna/diff; no hay banderas de breaking.
• Los SDK de cliente están actualizados (o no son necesarios para la extensión aditiva).
• Se incluye un lector de tolerantes en los clientes; enum-fallback probado.
• Las métricas/registros contienen la versión y las banderas capability.
• Para una posible ruptura, hay '/v2 ', dual-run y plan sunset.
• Documentación/ejemplos actualizados, hay conjuntos de oro.

FAQ

Backward vs forward - ¿Cuál es la diferencia?
Backward: los nuevos servidores funcionan con clientes antiguos. Forward: los nuevos clientes funcionan correctamente con los servidores antiguos (a expensas del lector tolerante y los impagos ordenados). El círculo completo es plena compatibilidad.

¿Es necesario hacer siempre '/v2 'para grandes cambios?
Sí, si se rompen invariantes/tipos/claves/semánticas. De lo contrario - mantener la línea y evolucionar aditivamente.

¿Qué pasa con el enum?
Agrega nuevos valores sin cambiar el significado de los antiguos. Los clientes deben tener un valor desconocido.

¿Qué pasa si ya han «roto»?
Retroceso, adaptador hot-fix, lanzamiento 'v2' con dual-run, comunicación y hyde migratorio.

Resultado

La compatibilidad inversa es una disciplina de evolución: estabilizar el núcleo, expandir aditivamente, introducir un lector tolerante, automatizar las verificaciones y llevar un deprechate consciente. Así podrá desarrollar rápidamente la plataforma sin dejar a los clientes bajo los escombros de los cambios «imperceptibles».