Guía para crear plantillas de FastAPI
Guía completa para añadir nuevas plantillas de proyecto FastAPI a FastAPI-fastkit.
🎯 Visión general
Añadir una plantilla nueva sigue un proceso de 5 pasos:
- 📋 Planificación y diseño — definir el propósito y la estructura de la plantilla
- 🏗️ Implementación de la plantilla — crear la estructura y los archivos requeridos
- 🔍 Validación local — validar la plantilla con el inspector
- 📚 Documentación — escribir el README y la guía de uso
- 🚀 Envío y revisión — crear el PR y obtener la revisión de la comunidad
📋 Paso 1: Planificación y diseño
Definir el propósito de la plantilla
Antes de crear una plantilla nueva, responde a estas preguntas:
- ¿Cuál es el valor único de esta plantilla?
- ¿En qué se diferencia de las plantillas existentes?
- ¿Qué grupo de usuarios es el público objetivo?
- ¿Qué stack tecnológico va a incluir?
Convención de nombres de plantillas
Ejemplos:
fastapi-microservice(plantilla de microservicio)fastapi-graphql(plantilla de integración GraphQL)fastapi-auth-jwt(plantilla de autenticación JWT)
Planificación del stack tecnológico
Define de antemano las tecnologías principales que vas a incluir:
# Ejemplo: plantilla fastapi-microservice
core_dependencies:
- fastapi
- uvicorn
- pydantic
- pydantic-settings
additional_features:
- sqlalchemy (ORM)
- alembic (migraciones)
- redis (caché)
- celery (tareas en segundo plano)
- pytest (pruebas)
development_tools:
- black (formateo de código)
- isort (ordenación de imports)
- mypy (chequeo de tipos)
- pre-commit (hooks de Git)
🏗️ Paso 2: Implementación de la plantilla
Estructura de directorios requerida
fastapi-{template-name}/
├── src/ # Código fuente de la aplicación
│ ├── main.py-tpl # ✅ Punto de entrada de la app FastAPI (requerido)
│ ├── __init__.py-tpl
│ ├── api/ # Routers de la API
│ │ ├── __init__.py-tpl
│ │ ├── api.py-tpl # Router principal de la API
│ │ └── routes/ # Rutas individuales
│ │ ├── __init__.py-tpl
│ │ └── items.py-tpl # Ruta de ejemplo
│ ├── core/ # Configuración central
│ │ ├── __init__.py-tpl
│ │ └── config.py-tpl # Gestión de ajustes
│ ├── crud/ # Lógica CRUD
│ │ ├── __init__.py-tpl
│ │ └── items.py-tpl
│ ├── schemas/ # Modelos Pydantic
│ │ ├── __init__.py-tpl
│ │ └── items.py-tpl
│ └── utils/ # Funciones utilitarias
│ ├── __init__.py-tpl
│ └── helpers.py-tpl
├── tests/ # ✅ Pruebas (requeridas)
│ ├── __init__.py-tpl
│ ├── conftest.py-tpl # Configuración de pytest
│ └── test_items.py-tpl # Pruebas de ejemplo
├── scripts/ # Scripts
│ ├── format.sh-tpl # Formateo de código
│ ├── lint.sh-tpl # Linting
│ ├── run-server.sh-tpl # Ejecución del servidor
│ └── test.sh-tpl # Ejecución de pruebas
├── pyproject.toml-tpl # ✅ Metadatos primarios (PEP 621, obligatorio)
├── requirements.txt-tpl # 🟡 Opcional si pyproject declara dependencias
├── setup.cfg-tpl # Configuración de herramientas de desarrollo
├── README.md-tpl # ✅ Documentación del proyecto (requerida)
├── .env-tpl # Plantilla de variables de entorno
└── .gitignore-tpl # Archivo Git ignore
Archivos mínimos requeridos. Una plantilla debe proporcionar:
- Un directorio
tests/ README.md-tplpyproject.toml-tpl(PEP 621)- Una declaración de
fastapicomo dependencia enpyproject.toml-tpl[project].dependencieso enrequirements.txt-tpl
requirements.txt-tpl no es necesario cuando pyproject.toml-tpl declara [project].dependencies — pero, si una plantilla incluye ambos, deben coincidir: la inspección falla si hay divergencia de dependencias entre ellos.
Las plantillas nuevas priorizan pyproject y no deben incluir setup.py-tpl. Desde v1.4.0 ninguna plantilla incluida lo trae. La inspección todavía acepta el archivo para que las plantillas externas sigan funcionando, pero es una vía heredada.
Apunta a Python 3.12 de forma coherente: requires-python = ">=3.12", black target-version = ["py312"], mypy python_version = "3.12" y python:3.12-slim para cualquier imagen base de Docker. La inspección comprueba que las tres versiones fijadas coinciden.
Nunca declares FastAPI-fastkit como dependencia de ejecución de un proyecto generado. La CLI es una herramienta de desarrollo; la lista de dependencias de una plantilla solo debe contener lo que importa la propia aplicación generada.
Guía de escritura de archivos
1. Escribir main.py-tpl
"""
Punto de entrada de la aplicación FastAPI
Este archivo es la aplicación principal del proyecto <project_name>
creado con FastAPI-fastkit.
"""
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from api.api import api_router
from core.config import settings
# Crear la app FastAPI (requerido por la validación del inspector)
app = FastAPI(
title="<project_name>",
description="Project created with FastAPI-fastkit",
version="1.0.0",
)
# Configuración del middleware CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Registrar el router de la API
app.include_router(api_router, prefix="/api/v1")
@app.get("/")
async def root():
"""Endpoint raíz"""
return {"message": "Hello from <project_name>!"}
@app.get("/health")
async def health_check():
"""Endpoint de health check"""
return {"status": "healthy"}
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
2. Escribir pyproject.toml-tpl (preferido)
Las plantillas modernas deberían declarar metadatos y dependencias con un pyproject.toml-tpl PEP 621. Como mínimo el archivo debe exponer una sección [project] con name, version, description y una lista dependencies que incluya fastapi. Las plantillas también deben llevar dos marcadores de identidad de FastAPI-fastkit para que is_fastkit_project() pueda distinguir los proyectos generados de otros proyectos FastAPI no relacionados dentro del espacio de trabajo del usuario:
- Prefijo
[FastAPI-fastkit templated]endescription - Una tabla específica
[tool.fastapi-fastkit]conmanaged = true
La detección acepta cualquiera de los dos marcadores (la comparación no distingue entre mayúsculas y minúsculas). La inyección de metadatos añadirá ambos al generar el proyecto si la plantilla los omite, pero los autores deberían incluirlos explícitamente.
[project]
name = "<project_name>"
version = "0.1.0"
description = "[FastAPI-fastkit templated] <description>"
authors = [
{name = "<author>", email = "<author_email>"},
]
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
"fastapi>=0.115.0",
"uvicorn[standard]>=0.34.0",
"pydantic>=2.10.0",
"pydantic-settings>=2.7.0",
"python-dotenv>=1.0.0",
]
[project.optional-dependencies]
dev = [
"pytest>=8.0.0",
"httpx>=0.28.0",
]
[tool.fastapi-fastkit]
managed = true
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
3. Escribir requirements.txt-tpl (opcional)
Opcional cuando pyproject.toml-tpl declara [project].dependencies. Sigue siendo útil para plantillas que prefieran flujos exclusivamente con pip.
# Dependencias FastAPI core (requeridas)
fastapi==0.104.1
uvicorn[standard]==0.24.0
# Validación de datos
pydantic==2.5.0
pydantic-settings==2.1.0
# Gestión de variables de entorno
python-dotenv==1.0.0
# Base de datos (si hace falta)
sqlalchemy==2.0.23
alembic==1.13.0
# Herramientas de desarrollo
pytest==7.4.3
pytest-asyncio==0.21.1
httpx==0.25.2
# Calidad de código
black==23.11.0
isort==5.12.0
mypy==1.7.1
4. Anclas de rutas
Las plantillas que incluyen un main.py-tpl o un módulo agregador de la API deben marcar dónde inserta código fastkit addroute:
from src.app.api import health
# fastkit:imports
api_router = APIRouter()
api_router.include_router(health.router)
# fastkit:routes
Sin las anclas, addroute recurre a una inserción basada en AST que localiza por sí misma el bloque de imports y los registros de routers — así que una plantilla que no las tenga sigue funcionando, pero el resultado es menos predecible. Mantén los comentarios en su sitio al editar estos archivos.
5. Escribir los archivos de pruebas
# tests/test_items.py-tpl
"""
Módulo de pruebas de la API de items
"""
import pytest
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_read_root():
"""Test del endpoint raíz"""
response = client.get("/")
assert response.status_code == 200
assert "message" in response.json()
def test_health_check():
"""Test del health check"""
response = client.get("/health")
assert response.status_code == 200
assert response.json() == {"status": "healthy"}
def test_create_item():
"""Test de creación de item"""
item_data = {
"name": "Test Item",
"description": "Test Description"
}
response = client.post("/api/v1/items/", json=item_data)
assert response.status_code == 200
data = response.json()
assert data["name"] == item_data["name"]
assert data["description"] == item_data["description"]
def test_read_items():
"""Test de listado de items"""
response = client.get("/api/v1/items/")
assert response.status_code == 200
assert isinstance(response.json(), list)
🔍 Paso 3: Validación local
Ejecutar los scripts de validación automatizada
Cuando tu plantilla nueva esté lista, valídala con estos comandos:
# Validar todas las plantillas
make inspect-templates
# Validar solo una plantilla concreta
make inspect-template TEMPLATES="fastapi-your-template"
# Validar con salida detallada
python scripts/inspect-templates.py --templates "fastapi-your-template" --verbose
# Ciclo local rápido: sin red, sin arrancar el servidor
python scripts/inspect-templates.py --templates "fastapi-your-template" \
--offline --no-smoke
# Comprobación completa antes de abrir un PR (añade mypy sobre el proyecto generado)
python scripts/inspect-templates.py --templates "fastapi-your-template" --mypy
--offline omite las consultas de actualidad de dependencias en PyPI, --no-smoke omite el arranque del proyecto generado (el paso más lento) y --mypy comprueba los tipos del proyecto generado. Consulta Aseguramiento de calidad de las plantillas para ver qué hace cada comprobación.
Note
Cuando envíes un PR, el flujo de trabajo Template PR Inspection se ejecutará automáticamente y validará tus cambios en la plantilla. Recibirás comentarios directamente en tu PR.
Checklist de validación
El inspector valida automáticamente lo siguiente:
✅ Validación de la estructura de archivos
- [ ] Existe el directorio
tests/ - [ ] Existe el archivo
README.md-tpl - [ ] Existe
pyproject.toml-tpl(sinsetup.py-tplen las plantillas nuevas)
✅ Validación de extensiones
- [ ] Todos los archivos Python usan la extensión
.py-tpl - [ ] No hay archivos con extensión
.py
✅ Validación de dependencias
- [ ]
fastapiestá declarado en al menos uno de:- [ ]
pyproject.toml-tplbajo[project].dependencies(preferido) - [ ]
requirements.txt-tpl
- [ ]
- [ ]
requirements.txt-tply[project].dependenciesno se contradicen - [ ]
FastAPI-fastkitno es una dependencia de ejecución
✅ Validación de la implementación de FastAPI
- [ ] Existe el import de
FastAPIenmain.py-tpl - [ ] Existe la creación de la app del estilo
app = FastAPI()enmain.py-tpl
✅ Validación de ejecución de pruebas
- [ ] La creación del entorno virtual es correcta
- [ ] La instalación de dependencias es correcta
- [ ] Todas las pruebas de pytest pasan
✅ Prueba de humo
- [ ] El proyecto generado arranca con uvicorn
- [ ]
/docsresponde - [ ]
/healthresponde
El objetivo de uvicorn se resuelve a partir de [tool.fastapi-fastkit].app_module en el pyproject.toml generado, después de app_module en template-config.yml y, por último, de las ubicaciones convencionales de main.py.
✅ Coherencia de la configuración
- [ ]
requires-python, eltarget-versionde black y elpython_versionde mypy indican Python 3.12 - [ ] No hay divergencia de dependencias entre
requirements.txt-tply[project].dependencies - [ ] No hay autodependencia de
FastAPI-fastkit
✅ Restos de marcadores
- [ ] Ningún
<placeholder>sobrevive a la generación del proyecto
✅ Pruebas automatizadas de plantillas
FastAPI-fastkit incluye pruebas automatizadas de plantillas que ejecutan pruebas integrales sobre todas las plantillas:
Cobertura de pruebas:
- ✅ Proceso de creación de la plantilla
- ✅ Inyección de metadatos del proyecto
- ✅ Configuración del entorno virtual
- ✅ Instalación de dependencias (todos los gestores)
- ✅ Validación básica de la estructura del proyecto
- ✅ Identificación del proyecto como FastAPI
Ejecución de las pruebas:
# Probar todas las plantillas automáticamente
$ pytest tests/test_templates/test_all_templates.py -v
# Probar una plantilla concreta
$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[your-template-name] -v
Descubrimiento automático de pruebas: Las plantillas nuevas se descubren automáticamente y se prueban sin configuración manual:
- ✅ Cero configuración: añade plantilla → pruebas automáticas
- ✅ Pruebas consistentes: mismos estándares de calidad para todas las plantillas
- ✅ Varios gestores de paquetes: se prueba con UV, PDM, Poetry y PIP
- ✅ Validación completa: estructura, metadatos y funcionalidad
Qué significa esto para ti:
- 🚀 No hace falta añadir archivos de prueba en el código principal de
FastAPI-fastkit: tu plantilla se prueba automáticamente - ⚡ Desarrollo más rápido: te concentras en el contenido de la plantilla, no en la configuración de las pruebas
- 🛡️ Aseguramiento de calidad: pruebas consistentes para todas las plantillas
- 🔄 Integración CI/CD: pruebas automáticas en los pull requests
Pruebas manuales que aún son necesarias:
- 🧪 Funcionalidad específica de la plantilla: lógica de negocio y features personalizadas
- 🔧 Pruebas de integración: servicios externos y flujos complejos
- 📱 Escenarios de extremo a extremo: flujos de usuario completos
Buenas prácticas de prueba:
# 1. Probar tu plantilla localmente
$ fastkit startdemo your-template-name
# 2. Ejecutar las pruebas automatizadas
$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[your-template-name] -v
# 3. Probar con distintos gestores de paquetes
$ fastkit startdemo your-template-name --package-manager poetry
$ fastkit startdemo your-template-name --package-manager pdm
$ fastkit startdemo your-template-name --package-manager uv
Checklist de validación manual
Además de la validación automatizada, comprueba a mano lo siguiente:
🔧 Calidad del código
- [ ] El código sigue la guía de estilo PEP 8
- [ ] Uso adecuado de type hints
- [ ] Nombres significativos para variables y funciones
- [ ] Comentarios y docstrings adecuados
🏗️ Arquitectura
- [ ] Separación de responsabilidades (API, lógica de negocio, acceso a datos)
- [ ] Diseño de componentes reutilizable
- [ ] Estructura escalable
- [ ] Buenas prácticas de seguridad aplicadas
📚 Documentación
- [ ]
README.md-tplsigue el formato de PROJECT_README_TEMPLATE.md - [ ] Métodos de instalación y ejecución indicados
- [ ] Documentación de la API (OpenAPI/Swagger)
- [ ] Explicación de las variables de entorno
📚 Paso 4: Documentación
Escribir el README.md-tpl
Escribe basándote en la guía de PROJECT_README_TEMPLATE.md.
Escribir la documentación de descripción de la plantilla
Añade una descripción de tu plantilla nueva en src/fastapi_fastkit/fastapi_project_template/README.md:
## fastapi-your-template
Escribe aquí una descripción breve y los casos de uso de tu plantilla nueva.
### Funcionalidades:
- Funcionalidad 1
- Funcionalidad 2
- Funcionalidad 3
### Casos de uso:
- Caso de uso 1
- Caso de uso 2
🚀 Paso 5: Envío y revisión
Checklist previo a la creación del PR
- [ ] Toda la validación automatizada pasada (
make inspect-templates) - [ ] Formato de código completado (
make format) - [ ] Comprobaciones de linting pasadas (
make lint) - [ ] Todas las pruebas pasadas (
make test) - [ ] Documentación completada
- [ ] Guía CONTRIBUTING.md seguida
Título y descripción del PR
[TEMPLATE] Add fastapi-{template-name} template
## Overview
Adds a new {purpose} template.
## Key Features
- Feature 1
- Feature 2
- Feature 3
## Validation Results
- [ ] Inspector validation passed
- [ ] All tests passed
- [ ] Documentation completed
## Usage Example
\```bash
fastkit startdemo
# Select template: fastapi-{template-name}
\```
## Related Issues
Closes #issue-number
Proceso de revisión
- Validación automatizada: GitHub Actions valida la plantilla automáticamente
- Template PR Inspection: ejecuta
inspect-changed-templates.pyen los PRs que modifican plantillas - Inspección semanal: validación completa de plantillas cada miércoles
- Template PR Inspection: ejecuta
- Revisión de código: mantenedores y comunidad revisan el código
- Pruebas: la plantilla se prueba en distintos entornos
- Revisión de la documentación: se revisa la precisión y el grado de completitud de la documentación
- Aprobación y merge: se fusiona en
maincuando se cumplen todos los requisitos
Note
Recibirás comentarios automáticos en tu PR con los resultados de la validación. ¡Revísalos antes de pedir revisión!
🎯 Buenas prácticas
Consideraciones de seguridad
- Gestiona la información sensible con variables de entorno
- Configuración CORS adecuada
- Validación de los datos de entrada
- Prevención de inyección SQL
Optimización del rendimiento
- Aprovechar el procesamiento asíncrono
- Optimizar las consultas a la base de datos
- Estrategias de caché adecuadas
- Configuración de compresión de respuestas
Mantenibilidad
- Estructura clara del código
- Cobertura de pruebas amplia
- Documentación detallada
- Configuración de logging y monitorización
🆘 ¿Necesitas ayuda?
- 📖 Guía de configuración de desarrollo
- 📋 Guía de código
- 💬 GitHub Discussions
- 📧 Contactar al mantenedor
Añadir una plantilla nueva es una gran contribución a la comunidad de FastAPI-fastkit. ¡Tus ideas y tu esfuerzo serán de gran ayuda para otros desarrolladores! 🚀