Módulo 5: Migración de Frameworks y Lenguajes
Módulo 5: Migración de Frameworks y Lenguajes
Módulo 5: Migración de Frameworks y Lenguajes
Descripción de la cápsula
El módulo anterior te enseñó refactoring dentro de un mismo framework — cambiar estructura sin cambiar framework. Este módulo escala la ambición: ¿qué pasa cuando necesitas cambiar de framework completamente? Flask→FastAPI, sync→async, unittest→pytest, requests→httpx. Estas migraciones son los proyectos más costosos y riesgosos que enfrentan los equipos — y los más transformadores cuando se ejecutan bien.
Una migración de framework no es un refactoring grande — es una categoría diferente de trabajo. Involucra cambiar APIs, patrones, dependencias, y a menudo la estructura completa del proyecto. Sin un proceso, se convierte en un rewrite caótico. Con proceso, se convierte en una serie de pasos verificables.
En este módulo vas a aprender ese proceso: el ciclo plan → safety net → migrate → validate, el strangler fig pattern para coexistencia gradual, y cómo Claude Code acelera cada paso. El caso de estudio es Flask→FastAPI, pero el proceso aplica a cualquier migración.
Contexto del Módulo
¿Dónde estamos?
Guía #8, Phase 2: Refactoring, Módulo 5 de 6.
Phase 2: Refactoring (Módulos 4-6)
├── Módulo 4: Refactoring Multi-File ✅
│ → Rename, extract, move, interface changes
├── Módulo 5: Migración de Frameworks ← ESTÁS AQUÍ
│ → Flask→FastAPI, strangler fig, migration testing
└── Módulo 6: Context Management para Proyectos Grandes
→ 1M tokens, chunking, CLAUDE.md
Lo que ya sabes
Del Módulo 4 llegas con dominio de refactoring coordinado: rename, extract, move, interface changes, y tests de regresión. Una migración de framework usa todas estas técnicas — pero a escala de framework.
¿Hacia dónde vamos?
El Módulo 6 resuelve el problema práctico que emerge con migraciones de proyectos grandes: context management. Y el Módulo 8 integra migración como parte de la modernización completa de un proyecto legacy.
Objetivo Profesional
Al final de este módulo, serás capaz de planificar y ejecutar una migración de framework step-by-step, usando strangler fig pattern para coexistencia gradual y tests de equivalencia para validar que el comportamiento se preserva.
Al final de este módulo podrás:
- ✅ Diseñar un migration plan con phases, checkpoints, y rollback strategy
- ✅ Aplicar el ciclo de migración: plan → safety net → migrate → validate → repeat
- ✅ Ejecutar una migración Flask→FastAPI endpoint por endpoint
- ✅ Implementar strangler fig pattern para coexistencia old/new
- ✅ Escribir migration tests que verifican equivalencia entre versiones
- ✅ Planificar rollback para cuando algo sale mal
Progresión del Módulo
Mapa del Módulo
| Cápsula | Tema | Qué aprenderás |
|---|---|---|
| 02 | Migration Strategy | El ciclo plan→test→migrate→validate y cómo diseñar un migration plan |
| 03 | Flask→FastAPI Step-by-Step | Migración práctica endpoint por endpoint con Claude Code |
| 04 | Strangler Fig Pattern | Coexistencia old/new: migrar gradualmente sin big bang |
| 05 | Migration Testing | Tests que verifican equivalencia entre old y new |
| 06 | Proyecto: Migración Flask→FastAPI | Migrar una app completa step-by-step |
Flujo de aprendizaje
Empiezas con la estrategia (cómo planificar una migración), luego la ejecución práctica (Flask→FastAPI paso a paso), después el patrón de coexistencia (strangler fig), y finalmente testing (verificar que old=new). El proyecto integra todo en una migración real.
El Principio Central
Gradual siempre gana sobre big bang.
Nunca migres todo de una vez. Migra un endpoint, verifica, migra el siguiente. El strangler fig pattern es la forma correcta de migrar: old y new coexisten, el tráfico se mueve gradualmente, y el old se elimina cuando todo está migrado.
Una Migración Real: Big Bang vs Gradual
Para anclar el módulo, considera un caso típico:
Tarea: Migrar
payments-api(8 endpoints, ~3K líneas, en producción) de Flask 1.x a FastAPI. Plazo: dos semanas.
Enfoque A: Big Bang
Semana 1, lunes-jueves → Reescribir los 8 endpoints en FastAPI
Semana 1, viernes → Tests "manuales", parecen funcionar
Semana 2, lunes → Deploy a staging. Falla autenticación
(FastAPI maneja auth diferente).
Semana 2, martes → Arreglar auth. Falla validación
(Pydantic más estricto que Flask).
Semana 2, miércoles → Arreglar validación. Falla un endpoint
que nadie había probado en años.
Semana 2, jueves → Decisión de equipo: revertir staging.
"Vamos a reagendar la migración".
Resultado: 2 semanas perdidas, FastAPI no está en producción,
confianza del equipo afectada.
Enfoque B: Strangler Fig (este módulo)
Día 1 → Plan: orden de migración por complejidad ascendente.
/health → /version → /accounts → /transactions →
/reports → /payments (los que tocan dinero al final).
Día 2 → Setup proxy. Migrar /health.
Tests de equivalencia verde. 100% del tráfico de /health
ahora pasa por FastAPI.
Día 3-4 → Migrar /version y /accounts.
Cada uno con tests de equivalencia.
Si algo falla, FASTAPI_ROUTES = ROUTES - {endpoint}
(rollback de un endpoint en 30 segundos).
Día 5-7 → Migrar /transactions y /reports.
Tests pasan. Equipo gana confianza.
Día 8-9 → Migrar /payments con extra cuidado.
Tests de equivalencia exhaustivos (cada caso edge).
Día 10 → 24h de monitoring con 0 requests a Flask.
Cutover: eliminar Flask y el proxy.
Resultado: migración completa, cero incidents, confianza
reforzada, código FastAPI en producción.
Mismo trabajo. Mismo equipo. Resultados radicalmente distintos.
La diferencia no es velocidad de implementación — es secuencia, verificación, y rollback. Las cápsulas 02-05 te enseñan cada componente.
Conexión con Proyecto
Proyecto de este módulo: Migración Flask→FastAPI
Vas a recibir una aplicación Flask pequeña (4-6 endpoints) y migrarla a FastAPI step-by-step. Cada paso: migrar un endpoint, escribir test de equivalencia, verificar. Al final, ambas versiones producen respuestas idénticas.
Conexión con la guía
En el Módulo 8 (Proyecto Integrador), la migración puede incluir cambio de framework como parte de la modernización completa.
Límites: Qué NO Se Hará
- ❌ Migración de lenguaje (Python→Go) — Solo frameworks dentro del mismo lenguaje
- ❌ Migración de base de datos — Solo el layer de aplicación
- ❌ Deployment de la migración — Solo el código, no la infraestructura
- ❌ Performance benchmarking — Verificamos equivalencia funcional, no rendimiento
Trampas a Evitar al Cursar Este Módulo
Cinco malentendidos previsibles. Anticípalos antes de empezar.
1. "Migración = rewrite"
No. Migración preserva comportamiento mientras cambia framework. Rewrite empieza de cero y puede cambiar comportamiento. Mezclarlos es la causa #1 de proyectos de migración fallidos. La cápsula 02 desarrolla la distinción.
2. "Tests al final"
No. Tests de equivalencia van antes de cada endpoint migrado. Sin tests previos, no sabes si la migración preservó comportamiento. La cápsula 05 te enseña a escribirlos efectivamente.
3. "Big bang es más rápido"
No. Parece más rápido en el día 1, pero el costo total (debugging, rollback, incident) es 3-5× mayor. La cápsula 04 (strangler fig) muestra por qué gradual gana.
4. "Rollback se planifica si falla"
No. Rollback se planifica antes de migrar el primer endpoint. Si tienes que diseñar el rollback en medio de un incident, ya es tarde. La cápsula 04 te da el patrón.
5. "El framework nuevo es objetivamente mejor"
A veces. Migrar a FastAPI tiene ventajas concretas (async nativo, Pydantic, OpenAPI auto), pero también costos (curva de aprendizaje del equipo, migración del ecosistema). Validar que la migración tiene ROI claro antes de empezar es responsabilidad del que la propone, no asumida.
Diagnóstico: ¿Listo para el Módulo?
Pregunta 1: ¿Has migrado algún proyecto de framework antes? Si sí, ¿cómo te fue?
Si fue mal: anota qué falló. Probablemente fue big bang (cápsula 04) o sin tests de equivalencia (cápsula 05). El módulo te corrige el patrón.
Si nunca: este es tu primer aprendizaje. El proyecto del módulo es la práctica controlada.
Pregunta 2: ¿Sabes la diferencia entre migración y rewrite?
Si sí: vas a evitar la trampa #1.
Si no: la sección "Lo que NO se cubre" arriba es tu punto de partida.
Pregunta 3: ¿Diseñas plan de rollback antes de empezar a cambiar código?
Si sí: trabajas con seguridad profesional.
Si no: la trampa #4 te aplica. La cápsula 04 te da el patrón.
Evidencia de Éxito
Antes de avanzar al Módulo 6 (Context Management), deberías poder:
- ✅ Migrar un endpoint Flask→FastAPI con equivalencia verificada
- ✅ Implementar strangler fig para coexistencia gradual
- ✅ Escribir tests que verifican old==new para el mismo input
- ✅ Tener un plan de rollback antes de empezar
- ✅ Tu migration plan tiene phases con checkpoints claros
- ✅ Distinguir migración de rewrite con criterio claro
Conceptos Clave del Módulo
Vista previa de los conceptos centrales para que llegues con vocabulario:
Migration Strategy
El proceso disciplinado de plan → safety net → migrate → validate → repeat. No es un workflow rígido — es la secuencia que previene incidents al migrar. La cápsula 02 desarrolla cada fase.
Strangler Fig Pattern
Patrón de migración gradual donde old y new coexisten. Un proxy o middleware decide qué tráfico va a cada uno. El old se "estrangula" cuando 100% del tráfico va al new. La cápsula 04 te da la implementación.
Equivalence Tests
Tests que comparan old y new con los mismos inputs y verifican outputs equivalentes (status + body + side effects). Son tu safety net durante la migración. La cápsula 05 te enseña a escribirlos.
Cutover
El momento en que eliminas el old. Requiere cumplir checklist específica: 100% de endpoints migrados, 100% de tests verdes, 0 requests al old por X tiempo. La cápsula 04 desarrolla el cutover.
Rollback Strategy
Plan documentado para volver al old si algo falla. En strangler fig, el rollback de un endpoint es trivial (FASTAPI_ROUTES = ROUTES - {endpoint}). La cápsula 02 te enseña a documentarlo.
Migration Coexistence
Período donde old y new operan simultáneamente sirviendo distintos endpoints. Requiere decidir: ¿comparten DB? ¿comparten cache? ¿comparten sessions? La cápsula 04 desarrolla los trade-offs.
Resumen
- Este módulo escala el refactoring al nivel de frameworks completos
- Flask→FastAPI es el caso de estudio, pero el proceso aplica a cualquier migración
- Gradual > big bang — strangler fig pattern, endpoint por endpoint
- Tests de equivalencia verifican que old y new producen el mismo resultado
- Claude Code acelera la conversión pero la validación humana + tests son insustituibles
- Migración ≠ rewrite — preservar comportamiento es el corazón
- Plan de rollback se diseña antes del primer cambio, no durante un incident
- La diferencia entre las "2 semanas perdidas" y "migración limpia" del escenario inicial es exactamente este módulo
Siguiente cápsula: 02 — Migration Strategy — el ciclo plan→safety net→migrate→validate como columna vertebral de cualquier migración. Empezamos por aquí porque sin estrategia, el resto del módulo es ejecución sin dirección.
Migración como Decisión, No Como Reflejo
Antes de empezar el módulo, vale la pena nombrar algo: no toda migración debe hacerse. El instinto de "modernizar al stack más reciente" puede llevar a migraciones que no tienen ROI claro.
Antes de migrar, el equipo debería poder responder afirmativamente al menos a 2 de estas preguntas:
- ¿Hay un dolor concreto del framework actual? (Performance, scaling, mantenibilidad — no "Flask se siente viejo")
- ¿El equipo tiene capacidad técnica para el nuevo framework? (No solo "el lead lo conoce")
- ¿Las features del nuevo framework resuelven problemas reales? (Async nativo es relevante si el proyecto lo necesita)
- ¿El costo total (semanas de migración + curva de aprendizaje) es menor que el dolor actual?
- ¿La librería/ecosistema del nuevo framework es maduro para el caso de uso?
Si las respuestas son todas negativas, mejor postergar. Migrar un framework saludable porque "FastAPI está de moda" puede consumir 4-6 semanas del equipo sin retorno proporcional.
Este módulo te enseña a ejecutar bien una migración. La decisión de si migrar está fuera del scope técnico — pero es la pregunta más importante que se debería hacer antes de aplicar las técnicas que aprendes aquí.
Cómo Trabajar Este Módulo
- La cápsula 02 es el cimiento. Sin entender el ciclo plan→safety net→migrate→validate, las cápsulas técnicas son ejecución a ciegas.
- La cápsula 03 es la práctica concreta. Flask→FastAPI paso a paso — síguela con tu propio proyecto Flask abierto al lado.
- La cápsula 04 es donde pasa la magia operacional. Strangler fig + cutover. Léela aunque tengas urgencia de "ejecutar ya".
- La cápsula 05 es el seguro. Sin tests de equivalencia, no sabes si el "new" hace lo mismo que el "old".
- El proyecto integra todo — y es la única manera de internalizar el ciclo. Ejecutarlo con un proyecto chico te entrena para uno grande.
Tiempo estimado:
Cápsula 01 (esta) → 10 min lectura
Cápsula 02 → 20 min
Cápsula 03 → 30 min + práctica
Cápsula 04 → 20 min
Cápsula 05 → 20 min + ejercicios
Proyecto (06) → 3-4 hrs
Total: ~5-6 horas
Recursos Adicionales
- Strangler Fig Pattern - Martin Fowler - El patrón original de migración gradual
- FastAPI Documentation - Documentación oficial de FastAPI
- Flask Documentation - Documentación oficial de Flask
- Migrating Flask to FastAPI - Real Python - Guías prácticas de migración
- Database Migrations with Alembic - Para migraciones de schema que acompañan el cambio de framework
- Feature Flags for Safe Migrations - Feature flags como herramienta de migración gradual