¿Qué starter elegir?
FastAPI-fastkit ofrece varias formas de arrancar un proyecto. Esta página es una ayuda para decidir dirigida a quienes empiezan: elige un camino aquí y luego salta a Inicio rápido para crear realmente el proyecto.
Si no lo tienes claro, la respuesta corta es:
Empieza con
fastkit init --interactivey elige el presetdomain-starter. Es la opción recomendada para las APIs modernas.
El resto de esta página explica por qué y cuándo elegir otra cosa.
TL;DR — elige por tipo de usuario
| Eres... | Empieza por |
|---|---|
| Nuevo en FastAPI y quieres una guía paso a paso | fastkit init --interactive (preset: domain-starter) |
| Quieres una demo CRUD funcionando para leerla y modificarla | fastkit startdemo fastapi-default |
| Quieres el scaffold más pequeño posible | fastkit init --interactive (preset: minimal) |
| Escribes un prototipo rápido / un script de un solo archivo | fastkit init --interactive (preset: single-module) |
| Necesitas una base de datos real (PostgreSQL + SQLAlchemy + Alembic) | fastkit startdemo fastapi-psql-orm |
| Quieres persistencia asíncrona con migraciones y CRUD genérico | fastkit startdemo fastapi-sqlmodel |
| Necesitas cuentas de usuario, login y rutas protegidas desde el primer día | fastkit startdemo fastapi-auth-jwt |
| Construyes un backend de chat LLM con streaming y herramientas | fastkit startdemo fastapi-llm-agent |
| Quieres un layout de dominio orientado a producción para una API mediana | fastkit init --interactive (preset: domain-starter) |
startdemo vs init --interactive — ¿en qué se diferencian?
Estas son las dos puertas de entrada principales. Sirven a propósitos distintos.
fastkit startdemo <template>
Deja en disco un proyecto de ejemplo completo y funcional basado en una de las plantillas que se distribuyen (fastapi-default, fastapi-async-crud, fastapi-psql-orm, fastapi-domain-starter, ...). El código fuente de la plantilla se pega tal cual, con los marcadores de metadatos (<project_name>, etc.) rellenados.
- ✅ El camino más rápido a una demo ejecutable.
- ✅ Todo el código es real y legible — ideal para aprender con ejemplos.
- ❌ La pila y la estructura de la plantilla son fijas; por ejemplo, no puedes activar CORS y a la vez dejar fuera la autenticación al generar el proyecto.
$ fastkit list-templates # ver lo disponible
$ fastkit startdemo fastapi-default # generar un proyecto a partir de una
fastkit init --interactive
Te guía con un asistente paso a paso: metadatos del proyecto → preset de arquitectura → selección de funcionalidades (base de datos, autenticación, testing, despliegue, ...) → gestor de paquetes → confirmación. El generador elige una plantilla base adecuada para cada preset y añade encima las funcionalidades que selecciones.
- ✅ Tú armas la pila que realmente quieres.
- ✅ El preset de arquitectura define la estructura del proyecto (single-file, layered, orientada a dominios, ...).
- ❌ Los presets más completos que conservan
main.py(classic-layered,domain-starter) generan módulos de configuración, pero esperan que conectes tú mismo esos módulos al router incluido. Consulta la matriz de presets / features para ver el contrato de cada preset y de cada funcionalidad.
Los cuatro presets de arquitectura
Estos aparecen dentro de fastkit init --interactive tras los prompts de información del proyecto. Usa esta sección para decidir cuál elegir.
minimal — empezar lo más simple posible y crecer después
La app FastAPI viable más pequeña. Scaffold vacío + un único src/main.py regenerado a partir de tus banderas de features. CORS, rate limiting e instrumentación con Prometheus se conectan automáticamente en main.py si los seleccionas.
- 👤 Para quién: gente que quiere añadir estructura por su cuenta a medida que el proyecto crece, o que está explorando FastAPI sin opiniones predefinidas sobre el layout.
- 📦 Plantilla base:
fastapi-empty. - 🧠 Modelo mental: "dame un archivo con FastAPI importado y déjame averiguar el resto".
single-module — prototipo estilo script
Todo vive en un solo módulo. Misma capa de regeneración de main.py que minimal.
- 👤 Para quién: cuando escribes un script de pegamento, un webhook pequeño o un prototipo de un día que no necesita fronteras entre paquetes.
- 📦 Plantilla base:
fastapi-single-module. - 🧠 Modelo mental: "quiero un único archivo de Python que pueda ejecutar y leer de una sentada".
classic-layered — partición en capas (api / crud / schemas / core)
El layout "estilo Django" divide el código horizontalmente por responsabilidad: todos los routers en api/, toda la lógica CRUD en crud/, todos los esquemas Pydantic en schemas/ y toda la configuración en core/. El main.py que trae la plantilla se conserva (ya incluye CORS); las configuraciones generadas de base de datos y autenticación se guardan en src/core/.
- 👤 Para quién: equipos familiarizados con layouts estilo Django/Rails, proyectos con muchos endpoints pequeños que comparten la misma cañería CRUD.
- 📦 Plantilla base:
fastapi-default. - 🧠 Modelo mental: "divide el código por qué es".
domain-starter — orientado a dominios (opción recomendada)
El código se divide verticalmente por concepto de negocio: cada dominio agrupa su propio router, service, repository y schemas dentro de src/app/domains/<concept>/. Incluye un endpoint /health y un dominio de ejemplo items que puedes copiar y renombrar para cada concepto nuevo. El main.py que trae la plantilla (en src/app/) se conserva; las configuraciones generadas se guardan en src/app/core/.
- 👤 Para quién: APIs medianas que crecerán con varios conceptos distintos (users, orders, billing, ...). Es la opción moderna recomendada.
- 📦 Plantilla base:
fastapi-domain-starter. - 🧠 Modelo mental: "divide el código por qué hace para el negocio".
Matriz de comparación
Comparativa rápida en paralelo.
minimal |
single-module |
classic-layered |
domain-starter |
|
|---|---|---|---|---|
| Plantilla base | fastapi-empty |
fastapi-single-module |
fastapi-default |
fastapi-domain-starter |
| Punto de entrada del proyecto | src/main.py |
src/main.py |
src/main.py |
src/app/main.py |
| Ubicación de los routers | (los añades tú) | (dentro de main.py) |
src/api/routes/ |
src/app/domains/<concept>/router.py |
| Carpetas por dominio | ❌ | ❌ | ❌ | ✅ |
Endpoint /health integrado |
✅ | ✅ | ❌ | ✅ |
main.py regenerado desde features |
✅ | ✅ | ❌ | ❌ |
CORS pre-conectado en main.py |
añadido si se selecciona | añadido si se selecciona | sí (vía env) | sí (vía env) |
| pyproject-first | opcional | opcional | opcional | ✅ |
| Ideal para | "haré crecer mi propia estructura" | "prototipo en un archivo" | "dividir por preocupación" | "dividir por concepto de negocio" |
Para ver el contrato completo, funcionalidad por funcionalidad (rutas de destino de las configuraciones de base de datos y auth, qué selecciones necesitan cableado manual y cuáles se conectan solas, cuándo saltan los avisos), consulta la matriz de presets de arquitectura.
Elegir una plantilla de startdemo
fastkit startdemo <template> es la mejor opción cuando quieres un ejemplo completo y ejecutable en lugar de un ensamblaje guiado. La mayoría de las plantillas se corresponden aproximadamente con uno de los cuatro presets de arriba, pero añaden código de ejemplo extra (endpoints CRUD sobre un almacén mock, manejo personalizado de respuestas, herramientas de Docker, etc.).
| Plantilla | Preset más cercano | Cuándo elegirla |
|---|---|---|
fastapi-default |
classic-layered |
Demo CRUD que funciona con el layout en capas. Buen primer paso. |
fastapi-empty |
minimal |
Scaffold pelado; la misma forma a la que llega minimal. |
fastapi-single-module |
single-module |
Demo en un solo archivo. |
fastapi-domain-starter |
domain-starter |
Opción moderna recomendada; trae un dominio de ejemplo items. |
fastapi-auth-jwt |
domain-starter |
Tu API necesita cuentas. Access/refresh tokens, hash argon2id, roles y scopes, migraciones con Alembic. |
fastapi-sqlmodel |
domain-starter |
Persistencia asíncrona ante todo: SQLModel + SQLAlchemy asíncrono, migraciones, una base CRUD genérica y listas paginadas. |
fastapi-llm-agent |
domain-starter |
Un backend de chat Claude con streaming, un bucle real de llamadas a herramientas y tests sin conexión. |
fastapi-custom-response |
classic-layered |
Demuestra envelopes / formato de respuesta personalizados. |
fastapi-psql-orm |
(sin preset directo) | PostgreSQL + SQLAlchemy + Alembic, síncrono. Elígela cuando quieras un stack de Compose alrededor de una base de datos real. |
fastapi-mcp |
(sin preset directo) | Integración con Model Context Protocol. |
fastapi-async-crud |
classic-layered |
⚠️ Obsoleta. Equivalente async a fastapi-default; mejor usa fastapi-sqlmodel. |
fastapi-dockerized |
classic-layered |
⚠️ Obsoleta. Añade un Dockerfile al layout default; todas las plantillas actuales ya traen uno. |
Los tres starters nuevos
Añadidos en v1.4.0, los tres siguen la forma de domain-starter (src/app/ con carpetas por concepto), así que encajan con lo que ya conoces de ese preset.
fastapi-auth-jwt — autenticación que aguanta el contacto con producción. Los access tokens duran poco; los refresh tokens rotan en cada uso y se registran por su jti en la base de datos, de modo que un token reutilizado se rechaza en lugar de aceptarse en silencio. Las contraseñas se hashean con argon2id mediante pwdlib. El logout es real: revoca una sesión o todas las sesiones de un usuario. Los guards vienen como dependencias — get_current_user, get_current_active_superuser y una fábrica require_scopes(...). Funciona sobre SQLite sin servicios externos y pasa a PostgreSQL definiendo DATABASE_URL. Recorrido completo: Autenticación JWT.
fastapi-sqlmodel — una definición de modelo por concepto. Una clase SQLModel es a la vez la tabla de SQLAlchemy y el esquema pydantic, así que una columna nueva se declara una vez y todos los esquemas de petición/respuesta la heredan. Asíncrono de principio a fin, migraciones asíncronas con Alembic, un CRUDBase que proporciona create / read / list / count / update / delete para que cada dominio solo escriba lo que le es propio, y endpoints de listado envueltos en un envoltorio de página. Recorrido completo: Persistencia con SQLModel.
fastapi-llm-agent — un backend de chat, no un envoltorio de POST /completion. Los tokens llegan al cliente en streaming por SSE, y un bucle de llamadas a herramientas se ejecuta hasta que el modelo termina o salta el límite de iteraciones. El historial de conversación está detrás de una interfaz ConversationStore, así que pasar del diccionario incluido a Redis es cuestión de una implementación. La suite de tests sustituye el cliente de Anthropic por un objeto falso con guion — determinista, sin conexión, sin API key. Recorrido completo: Agente LLM.
Sobre las plantillas obsoletas
fastapi-async-crud y fastapi-dockerized se siguen distribuyendo y siguen generando proyectos que funcionan — no se rompe nada si las usas. Están marcadas como obsoletas porque el motivo para elegirlas ha desaparecido:
fastapi-dockerizedexistía para añadir un Dockerfile. Todas las plantillas actuales traen uno, y la selección de despliegue interactiva genera archivos de Docker para cualquier preset.fastapi-async-crudmostraba endpoints asíncronos sobre un almacén mock.fastapi-sqlmodelhace lo mismo contra una base de datos asíncrona real, con migraciones.
Los proyectos existentes generados a partir de cualquiera de las dos no necesitan ninguna acción.
fastkit list-templates muestra la lista viva con descripciones de una línea.
Preguntas frecuentes
P. ¿Tengo que elegir un preset / plantilla desde el principio? No — siempre puedes reorganizar a mano el código generado más tarde. Los presets son puntos de partida, no contratos. No le des demasiadas vueltas a la elección.
P. ¿Cuál es la opción "moderna"?
domain-starter. Es pyproject-first, trae un endpoint /health y usa el layout al que convergen la mayoría de los proyectos FastAPI medianos bien mantenidos.
P. ¿Puedo pasar de classic-layered a domain-starter más tarde?
Sí, pero es una refactorización manual — no hay comando de migración. Si crees que tu proyecto va a crecer lo suficiente como para necesitar carpetas de dominio, empieza ahí.
P. ¿Y si solo quiero aprender FastAPI?
Empieza con fastkit startdemo fastapi-default — lee el código, ejecuta los tests, cambia algunos endpoints. Cuando te sientas cómodo, fastkit init --interactive con el preset domain-starter es el paso natural siguiente.
P. ¿Dónde veo los archivos exactos que genera cada preset? La matriz de presets de arquitectura es la página de referencia para eso.
Próximos pasos
- Inicio rápido — crear de verdad tu primer proyecto.
- Crear proyectos — recorrido más profundo de los flags de la CLI.
- Tutorial de Autenticación JWT, tutorial de Persistencia con SQLModel y tutorial de Agente LLM — recorridos de principio a fin de los tres starters añadidos en v1.4.0.
- Tutorial del proyecto orientado a dominios — si elegiste
domain-starter, este es el recorrido de principio a fin del árbol generado, el ejemploitemsincluido y cómo añadir tu siguiente dominio. - Matriz de presets de arquitectura — el contrato completo por preset y por feature.