Cambiar a la vez las versiones síncrona y asíncrona de una biblioteca cliente sin romper su API

## Identificar el comportamiento público que no debe cambiar antes de editar Antes de editar, identifica el comportamiento público, las versiones de ejecución compatibles, la arquitectura pertinente y el conjunto mínimo de archivos responsable del cambio. - Trata las firmas públicas, los nombres de argumentos, los valores predeterminados, los tipos de retorno, las excepciones y el comportamiento en casos límite como contratos de compatibilidad. - Localiza todas las implementaciones paralelas del mismo comportamiento, como los clientes síncronos y asíncronos. - Identifica las capas de enrutamiento, análisis, políticas, conexión y conformación de respuestas que puedan intervenir en el comportamiento. - Lee las implementaciones, pruebas y sobrecargas de tipos cercanas antes de elegir un patrón. - Conserva la semántica actual del protocolo y del servidor, salvo que el cambio solicitado exija explícitamente otra cosa. - No amplíes la tarea para incluir labores de limpieza que no estén relacionadas. Si el comportamiento solicitado entra en conflicto con una invariante documentada, detente y expón el conflicto en lugar de redefinir el contrato de forma silenciosa. ## Aplicar el mismo cambio en los clientes síncrono y asíncrono Cuando una biblioteca ofrezca pilas de cliente equivalentes, considera la paridad una propiedad obligatoria. 1. Asocia el símbolo síncrono modificado con su equivalente asíncrono, o viceversa. 2. Compara firmas, sobrecargas, anotaciones de tipos, valores predeterminados, formas de retorno, errores y efectos secundarios. 3. Aplica un comportamiento equivalente en ambas pilas, salvo que una diferencia documentada del entorno de ejecución lo haga imposible. 4. Mantén coherentes las interfaces de comandos compartidas, las tablas de enrutamiento, las devoluciones de llamada del analizador y los metadatos de políticas. 5. Añade pruebas emparejadas cuando ambas pilas expongan el comportamiento. Utiliza la sintaxis de tipos y las convenciones de sobrecarga establecidas en el código base. Si solo debe cambiar un lado, registra el motivo arquitectónico concreto y verifica que la asimetría sea intencionada. ## Cambiar solo la capa responsable y reutilizar las funciones auxiliares existentes Prefiere un cambio quirúrgico que reutilice las utilidades y convenciones existentes. - Modifica únicamente la capa responsable del comportamiento. - Conserva las API públicas y la semántica de los errores. - Evita dependencias nuevas, salvo que los recursos existentes no puedan satisfacer el requisito. - Evita abstracciones nuevas cuando una utilidad o patrón actual sea suficiente. - Mantén las importaciones al mínimo y en el ámbito del módulo, salvo que una importación diferida sea técnicamente necesaria. - Actualiza las cadenas de documentación cuando cambie el comportamiento y mantenlas coherentes con los tipos. La corrección es prioritaria. Optimiza solo después de que el comportamiento sea correcto y nunca sacrifiques la corrección para reducir asignaciones o acelerar la ejecución. ## No ralentizar las rutas críticas ni cambiar el comportamiento del protocolo Revisa los cambios en rutas críticas para detectar asignaciones evitables, análisis repetidos, trabajo duplicado y estructuras temporales grandes. - Reutiliza las utilidades establecidas y los metadatos almacenados en caché. - Conserva la selección del protocolo de comunicación de forma independiente del formato de las respuestas que ve el usuario. - Mantén las políticas de enrutamiento y agregación coherentes con la semántica de los comandos. - Cuando corresponda, trata de forma explícita las redirecciones, los reintentos, las diferencias de topología y la propagación de errores. - No normalices de manera silenciosa un caso límite que el servicio subyacente presenta como distinto. Los cambios de rendimiento deben conservar un comportamiento observable idéntico. Si una optimización complica la corrección o la paridad, prefiere la implementación correcta más sencilla. ## Probar desde un caso fallido hasta la matriz completa de pruebas Reúne pruebas ampliando el alcance de forma progresiva: 1. Añade o actualiza una prueba determinista que falle antes de la corrección. 2. Ejecuta la prueba o el conjunto de pruebas pertinente más pequeño. 3. Ejecuta la cobertura espejo de las variantes síncrona y asíncrona. 4. Comprueba combinaciones significativas de protocolo, modo de respuesta, topología o funciones opcionales. 5. Ejecuta los analizadores de código, las comprobaciones de formato y las comprobaciones de tipos exigidas por el proyecto. 6. Ejecuta la matriz completa de pruebas compatibles cuando el cambio pueda afectar a un comportamiento compartido. No debilites las aserciones, elimines cobertura ni reclasifiques fallos únicamente para que el conjunto de pruebas se apruebe. Las pruebas que necesiten infraestructura externa deben permanecer claramente separadas de los conjuntos locales predeterminados. ## Revisar las diferencias finales en busca de código de depuración y desajustes entre síncrono y asíncrono Antes de terminar, inspecciona el cambio completo y verifica lo siguiente: - solo se modificaron los archivos y las líneas pertinentes; - no quedan código de depuración, eliminaciones accidentales ni cambios de formato no relacionados; - las API públicas y el comportamiento de los errores no han cambiado, salvo que fuera una intención explícita; - las implementaciones espejo y las anotaciones de tipos siguen alineadas; - las pruebas cubren los casos correctos, los casos límite y las rutas de fallo; - los analizadores de código y los conjuntos de pruebas requeridos se aprueban; - la documentación coincide con el comportamiento implementado; - no se introdujo ninguna dependencia, asignación o abstracción innecesaria. Corrige cada problema detectado y repite las comprobaciones afectadas. Informa de qué cambió, qué se validó y cualquier escenario externo que no se haya probado explícitamente, sin afirmar que se realizó una verificación más amplia.