Compatibilidad directa

¿Qué es la compatibilidad directa

La compatibilidad directa (forward compatibility) es la capacidad del sistema para operar correctamente con clientes o datos más nuevos que aquellos bajo los cuales se diseñó originalmente. Más fácil: el servidor antiguo no se rompe cuando un nuevo cliente llega a él; el viejo consumidor no cae cuando se encuentra con un nuevo mensaje.

Desde la compatibilidad retroactiva (cuando el nuevo sistema admite clientes antiguos), el forward se diferencia en la dirección de responsabilidad: diseñamos protocolos y clientes para «sobrevivir» a futuras ampliaciones sin una actualización total de todo el ecosistema.

Principios

1. Tolerant reader & tolerant writer

Reader ignora los campos/encabezados desconocidos y permite nuevos valores enum con el back correcto.
Writer no envía nada que el servidor no haya declarado explícitamente como compatible (capabilities).

2. Capability negotiation

Intercambio explícito de capacidades (fichas/versiones/tipos de medios) en la etapa handshake. El cliente adapta su comportamiento a la respuesta del servidor.

3. Degradación por defecto

Las nuevas características se consideran opcionales: si el servidor/consumidor no las admite, el script todavía terminará con un mínimo útil (MGC).

4. Núcleo estable (MGC)

El contrato mínimo de garantía no se modifica; las innovaciones viven como extensiones.

5. Contratos de error como parte del protocolo

Los códigos/razones predecibles («ficha no soportada», «tipo de medios desconocidos») permiten al cliente retroceder automáticamente al modo soportado.

6. Versiones sin sorpresas

Las líneas mayores están separadas; las extensiones menores no requieren una actualización del servidor/consumidor.

Donde esto es

API públicas con integraciones de larga vida (partners, SDK en aplicaciones móviles).
Plataformas de eventos con muchos consumidores independientes.
Clientes móviles que se actualizan más lentamente que el backend.
Edge/IoT, donde una parte de la flota de dispositivos rara vez se cosen.

Patrones de implementación por estilo

REST/HTTP

• 'Accept'/mediatipos con parámetros (' application/vnd. example. order+json; v=1; profile=risk`).
• 'Prefer: include =...' para unidades opcionales.
• Título 'X-Capabilities: risk_score,item_details_v2'.

• Envía la solicitud en formato básico, extensiones - sólo si el servidor ha confirmado capability (a través de OPTIONS/desc/lead endpoint).
• Cuando '415/406/501' se retrotrae automáticamente a un formato/método compatible.
• Respuesta del servidor: configuración desconocida - ignorar; campos superfluos - permitidos; formato de error estable ('type/code/detail/trace _ id').

gRPC / Protobuf

Servicios estables: nuevos métodos/campos - aditivo; el servidor antiguo ignora silenciosamente los campos desconocidos de la solicitud.
Detección de características: el método 'GetCapabilities ()' devuelve listas de límites/fichas. El cliente no llama al «método v2» a menos que el servidor lo haya declarado.
Streaming: fijar el orden del conjunto mínimo de mensajes; los nuevos «marcos» marcan con extensiones/tipos que el cliente viejo ignora.

GraphQL

Forward-friendly: nuevos campos/tipos aparecen en el servidor - los antiguos clientes simplemente no los solicitan.
Las conjeturas están prohibidas: el cliente debe mantener el esquema (introspección/codógeno) y no enviar directivas/variables desconocidas.
Degradación: si el servidor no conoce la directiva personalizada/función - el cliente construye la solicitud sin ella.

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

Compatibilidad con esquemas FORWARD en el registro: Los consumidores antiguos pueden leer los mensajes escritos por el nuevo esquema.
Campos aditivos con impagos: los nuevos productores no rompen viejos consumers.
Core vs Enriched: el núcleo sigue siendo el mismo, la nueva información se publica en '.enriched' o como campos opcionales.

Prácticas de diseño

1. Contrato de solicitud mínima (MGC)

La operación debe tener un «cuello estrecho» que todos los servidores soportarán durante muchos años.

2. Banderas Ficha a nivel de contrato

Describa los ficheros como capacidades con nombre: 'risk _ score', 'pricing _ v2', 'strong _ idempotency'. El cliente los incluye explícitamente.

3. Códigos de error explícitos para «no soportados»

HTTP: `501 Not Implemented`, `415 Unsupported Media Type`, детальные `problem+json`.
gRPC: `UNIMPLEMENTED`/`FAILED_PRECONDITION`.
Eventos: ruta en DLQ con 'reason = unsupported _ feature'.

4. No confiar en el orden/listas completas

El cliente debe estar preparado para los nuevos valores de enum, la ausencia de nuevos campos y las propiedades «adicionales».

5. Identificadores y formatos estables

No cambie el formato de ID/llaves de partición dentro de la línea: esto rompe el forward del lado de los lectores.

6. Documentación «legible por máquina»

Hosting descriptors: OpenAPI/AsyncAPI/Proto descriptors/GraphQL SDL. Los clientes pueden comprobar la ayuda del fich.

Pruebas de compatibilidad avanzada

Schema-diff en modo FORWARD/FULL: el nuevo esquema valida el viejo consumidor/servidor.
Pruebas contractuales del cliente: el nuevo cliente se ejecuta contra un servidor antiguo con las fichas encendidas/apagadas.
Solicitudes de oro: un conjunto de solicitudes «nuevas» se ejecutan a través del servidor «viejo»; se espera una degradación sin errores críticos.
Chaos/latency: chequeo de temporizadores/retraídos: el nuevo cliente debe sobrevivir correctamente a los peores SLA del servidor antiguo.
Canary: parte de los nuevos clientes trabajan con la versión anterior del servidor: recopila telemetría de errores/degradaciones.

Observabilidad y métricas operativas

Porcentaje de solicitudes/mensajes con fichas sin soporte y sus revisiones automáticas.
Distribución por versiones de clientes (User-Agent/metadatos/claims).
Errores 'UNIMPLEMENTED/501/415' y rutas en DLQ con 'unsupported _ feature'.
Tiempo de degradación: p95/p99 para MGC contra respuesta «extendida».

Modos de compatibilidad en el Registro de esquemas

FORWARD: la nueva entrada es compatible con un lector antiguo (se necesitan impagos, opcionalidad).
FULL: и FORWARD, и BACKWARD; conveniente para los contratos públicos.
Recomendación: para eventos - BACKWARD en el productor y FORWARD en el consumer (vía tolerant reader), para APIs externas - FULL.

NAT (capabilities + degradación)

1. El cliente hace 'GET/meta/capabilities '→ '{«risk_score": false, «price_v2": true}'.
2. En 'POST/orders' se envían los campos base; 'risk _ score' no solicita porque el servidor no lo sabe.
3. Si ha enviado accidentalmente 'Prefer: include = risk _ score', el servidor responde 200 sin el campo 'risk _ score' (o'Preference-Applied: none '): el cliente no cae.

gRPC (discovery)

'GetCapabilities ()' devolvió la lista de métodos/fich. El cliente no llama a 'CaptureV2' si no lo hace, sino que utiliza 'Capture' y convierte localmente los datos de entrada a la vista admitida.

Eventos (FORWARD en el Registro)

El productor añadió el campo 'risk _ score' (nullable con default). El viejo consumista lo ignora; su lógica sólo utiliza campos de núcleo estables.

Antipattern

Cliente duro: filtra la respuesta a través de campos whitelist y cae sobre una propiedad desconocida.
Fiches implícitos: el cliente comienza a enviar un nuevo parámetro sin comprobar las capacidades.
El cambio de los formatos de ID/claves dentro de la línea → los servidores/consumidores antiguos dejan de entender las nuevas solicitudes/mensajes.
Suposiciones cosidas sobre la lista completa de enum (switch sin default).
Lógica como control de flujo: parcing líneas de error en lugar de códigos contractuales.

Lista de comprobación de implementación

• Definido por el MGC; las nuevas características están marcadas como opcionales.
• Se describe e implementa la capability negotiation (endpoint/metadatos/handshake).
• Los clientes ignoran campos desconocidos y procesan correctamente los nuevos enum (fallback).
• Los contratos de error registran «no soportado» previsiblemente (HTTP/gRPC/Event).
• El registro de esquemas está configurado en FORWARD/FULL para los artefactos correspondientes.
• Autotestas: schema-diff (FORWARD), pruebas contractuales del cliente contra el antiguo servidor, canario.
• Métricas: versión del cliente, fallo de ficha, proporción de degradación, p95 MGC.
• La documentación/SDK publica una lista de fichas y ejemplos de degradación.

FAQ

¿En qué se diferencia forward de backward en la práctica?
Backward: el nuevo servidor no rompe clientes antiguos. Forward: el antiguo servidor no se rompe de los nuevos clientes (o el antiguo consumer es de los nuevos mensajes). Lo ideal es que llegues a full.

¿Es necesario introducir siempre capabilities?
Si esperas una evolución activa sin lanzamientos sincrónicos - sí. Es más barato que mantener docenas de líneas mayores.

¿Qué hay de seguro?
Los nuevos fichajes deben requerir scopes/claims separados. Si el servidor no los soporta, el cliente no debe reducir la seguridad, sino que debe rechazar los fiches.

¿Se puede «adivinar» el soporte por servidor?
No es deseable. Es mejor preguntar explícitamente (capabilities) o mirar el mediatip/diagrama.

Resultado

La compatibilidad directa es una disciplina para negociar oportunidades y degradarse con seguridad. El núcleo estable, la capability negotiation, las extensiones aditivas y los errores predecibles permiten que los nuevos clientes y los datos se adapten a los antiguos servidores y consumidores, sin lanzamientos masivos ni migraciones nocturnas.