Utiliser les modèles

FastAPI-fastkit propose des modèles de projet prêts à l'emploi pour vous aider à démarrer rapidement avec différentes piles techniques.

Modèles disponibles

Consultez les modèles disponibles avec la commande list-templates :

$ fastkit list-templates
                      Available Templates
┌─────────────────────────┬───────────────────────────────────┐
│ fastapi-custom-response │ Async Item Management API with    │
│                         │ Custom Response System            │
│ fastapi-dockerized      │ Dockerized FastAPI Item           │
│                         │ Management API                    │
│ fastapi-empty           │ No description                    │
│ fastapi-async-crud      │ Async Item Management API Server  │
│ fastapi-psql-orm        │ Dockerized FastAPI Item           │
│                         │ Management API with PostgreSQL    │
│ fastapi-default         │ Simple FastAPI Project            │
└─────────────────────────┴───────────────────────────────────┘

Descriptions des modèles

1. `fastapi-default`

Projet FastAPI simple

Configuration FastAPI basique avec les fonctionnalités essentielles
Gestion d'items avec des données factices
Idéal pour apprendre et pour les API simples
Inclut les opérations CRUD de base

Idéal pour :

Débutants en FastAPI
API web simples
Apprentissage et prototypage

2. `fastapi-async-crud`

Serveur d'API asynchrone de gestion d'items

Application FastAPI entièrement asynchrone
Opérations CRUD avancées avec async/await
Meilleure performance pour les opérations d'E/S
Stockage de données factices avec motifs asynchrones

Idéal pour :

Applications haute performance
Opérations intensives en E/S
Développement Python asynchrone moderne

3. `fastapi-custom-response`

API asynchrone de gestion d'items avec système de réponse personnalisé

Modèles de réponse personnalisés et formatage
Gestion avancée des erreurs
Prise en charge de la pagination
Codes d'état HTTP et réponses personnalisés

Idéal pour :

API nécessitant des formats de réponse spécifiques
Besoins avancés en gestion d'erreurs
Logique métier personnalisée dans les réponses

4. `fastapi-dockerized`

API FastAPI de gestion d'items conteneurisée avec Docker

Conteneurisation Docker complète
Configuration de déploiement prête pour la production
Builds Docker multi-étapes
Configuration basée sur l'environnement

Idéal pour :

Déploiements en production
Environnements conteneurisés
Pipelines DevOps et CI/CD

5. `fastapi-psql-orm`

API FastAPI conteneurisée de gestion d'items avec PostgreSQL

Intégration de la base de données PostgreSQL
ORM SQLAlchemy avec migrations Alembic
Docker Compose pour le développement local
Opérations CRUD complètes en base de données

Idéal pour :

Applications pilotées par une base de données
Stockage de données de qualité production
Relations de données complexes

6. `fastapi-empty`

Projet FastAPI minimal

Configuration FastAPI minimale
Aucune fonctionnalité ajoutée à l'avance
Page blanche pour du développement personnalisé

Idéal pour :

Démarrer de zéro
Dépendances minimales
Exigences d'architecture personnalisée

Créer un projet à partir d'un modèle

Utilisez la commande startdemo pour créer un projet à partir d'un modèle :

$ fastkit startdemo
Enter the project name: my-blog-api
Enter the author name: John Doe
Enter the author email: john@example.com
Enter the project description: Blog API with PostgreSQL

Available Templates:
           fastapi-default
┌─────────────┬──────────────────────┐
│ Description │ Simple FastAPI       │
│             │ Project              │
│ Stack       │ FastAPI, Uvicorn     │
│ Database    │ Mock Data            │
│ Features    │ Basic CRUD           │
└─────────────┴──────────────────────┘

           fastapi-psql-orm
┌─────────────┬──────────────────────┐
│ Description │ Dockerized FastAPI   │
│             │ Item Management API  │
│             │ with PostgreSQL      │
│ Stack       │ FastAPI, PostgreSQL, │
│             │ SQLAlchemy, Docker   │
│ Database    │ PostgreSQL           │
│ Features    │ Full ORM, Migrations │
└─────────────┴──────────────────────┘

Select template (fastapi-default, fastapi-async-crud, fastapi-custom-response, fastapi-dockerized, fastapi-psql-orm, fastapi-empty): fastapi-psql-orm

           Project Information
┌──────────────┬─────────────────────┐
│ Project Name │ my-blog-api         │
│ Author       │ John Doe            │
│ Author Email │ john@example.com    │
│ Description  │ Blog API with       │
│              │ PostgreSQL          │
└──────────────┴─────────────────────┘

       Template Dependencies
┌──────────────┬───────────────────┐
│ Dependency 1 │ fastapi           │
│ Dependency 2 │ uvicorn           │
│ Dependency 3 │ sqlalchemy        │
│ Dependency 4 │ alembic           │
│ Dependency 5 │ psycopg2-binary   │
│ Dependency 6 │ python-dotenv     │
│ Dependency 7 │ pytest            │
└──────────────┴───────────────────┘

Available Package Managers:
                   Package Managers
┌────────┬────────────────────────────────────────────┐
│ PIP    │ Standard Python package manager            │
│ UV     │ Fast Python package manager                │
│ PDM    │ Modern Python dependency management        │
│ POETRY │ Python dependency management and packaging │
└────────┴────────────────────────────────────────────┘

Select package manager (pip, uv, pdm, poetry) [uv]: uv
Do you want to proceed with project creation? [y/N]: y

✨ FastAPI project 'my-blog-api' from 'fastapi-psql-orm' has been created successfully!

Comparaison des fonctionnalités des modèles

Fonctionnalité	Default	Async CRUD	Custom Response	Dockerized	PostgreSQL ORM	Empty
FastAPI de base	✅	✅	✅	✅	✅	✅
Données factices	✅	✅	✅	✅	❌	❌
Support asynchrone	Basique	✅	✅	✅	✅	❌
Réponses personnalisées	❌	❌	✅	❌	❌	❌
Docker	❌	❌	❌	✅	✅	❌
Base de données	Factice	Factice	Factice	Factice	PostgreSQL	Aucune
ORM	❌	❌	❌	❌	SQLAlchemy	❌
Migrations	❌	❌	❌	❌	Alembic	❌
Tests	✅	✅	✅	✅	✅	❌
Idéal pour	Apprentissage	Performance	API personnalisées	Production	Applications avec base de données	Personnalisé

Configuration spécifique à chaque modèle

Utiliser `fastapi-psql-orm`

Ce modèle inclut une configuration PostgreSQL complète. Après la création :

Démarrer PostgreSQL avec Docker :

$ cd my-blog-api
$ docker-compose up -d postgres
Starting my-blog-api_postgres_1 ... done

Exécuter les migrations de base de données :

$ source .venv/bin/activate
$ alembic upgrade head
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [alembic.runtime.migration] Running upgrade -> bedcdc35b64a, first alembic

Démarrer le serveur d'API :

$ fastkit runserver
INFO:     Uvicorn running on http://127.0.0.1:8000

Utiliser `fastapi-dockerized`

Ce modèle offre un support Docker complet :

Construire l'image Docker :

$ cd my-dockerized-api
$ docker build -t my-dockerized-api .
Successfully built abc123def456
Successfully tagged my-dockerized-api:latest

Exécuter le conteneur :

$ docker run -p 8000:8000 my-dockerized-api
INFO:     Uvicorn running on http://0.0.0.0:8000

Utiliser `fastapi-custom-response`

Ce modèle inclut une gestion avancée des réponses :

Modèles de réponse personnalisés :

from src.helper.pagination import PaginatedResponse
from src.schemas.base import StandardResponse

@router.get("/", response_model=PaginatedResponse[Item])
def read_items(skip: int = 0, limit: int = 10):
    items = items_crud.get_multi(skip=skip, limit=limit)
    total = items_crud.count()

    return PaginatedResponse(
        data=items,
        total=total,
        page=skip // limit + 1,
        pages=(total + limit - 1) // limit
    )

@router.post("/", response_model=StandardResponse[Item])
def create_item(item: ItemCreate):
    new_item = items_crud.create(item)
    return StandardResponse(
        data=new_item,
        message="Item created successfully",
        status_code=201
    )

Gestion d'erreurs améliorée :

from src.helper.exceptions import ItemNotFoundError, ValidationError

@router.get("/{item_id}", response_model=StandardResponse[Item])
def read_item(item_id: int):
    try:
        item = items_crud.get(item_id)
        return StandardResponse(data=item)
    except ItemNotFoundError:
        raise HTTPException(
            status_code=404,
            detail=f"Item with id {item_id} not found"
        )

Structure des projets de modèle

Chaque modèle suit une structure cohérente mais adaptée :

Structure de `fastapi-default`

my-project/
├── src/
│   ├── main.py
│   ├── core/config.py
│   ├── api/
│   │   ├── api.py
│   │   └── routes/items.py
│   ├── crud/items.py
│   ├── schemas/items.py
│   └── mocks/mock_items.json
├── tests/
├── scripts/
└── requirements.txt

Structure de `fastapi-psql-orm`

my-project/
├── src/
│   ├── main.py
│   ├── core/
│   │   ├── config.py
│   │   └── db.py
│   ├── api/
│   │   ├── api.py
│   │   ├── deps.py
│   │   └── routes/items.py
│   ├── crud/items.py
│   ├── schemas/items.py
│   ├── alembic/
│   │   ├── env.py
│   │   └── versions/
│   └── utils/
├── tests/
├── scripts/
├── docker-compose.yml
├── Dockerfile
├── alembic.ini
└── requirements.txt

Personnaliser les modèles

Après avoir créé un projet à partir d'un modèle, vous pouvez le personnaliser :

1. Ajouter de nouvelles routes

$ fastkit addroute posts my-blog-api
$ fastkit addroute users my-blog-api
$ fastkit addroute comments my-blog-api

2. Modifier la configuration

Modifiez src/core/config.py selon vos besoins :

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    PROJECT_NAME: str = "My Blog API"
    VERSION: str = "1.0.0"
    API_V1_STR: str = "/api/v1"

    # Database settings (for PostgreSQL templates)
    DATABASE_URL: str = "postgresql://user:password@localhost/dbname"

    # Security settings
    SECRET_KEY: str = "your-secret-key-here"
    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30

    class Config:
        env_file = ".env"

settings = Settings()

3. Ajouter des variables d'environnement

Créez un fichier .env à la racine de votre projet :

# .env
PROJECT_NAME=My Blog API
VERSION=1.0.0
DEBUG=True

# Database (for PostgreSQL templates)
DATABASE_URL=postgresql://user:password@localhost:5432/myblogdb
POSTGRES_USER=user
POSTGRES_PASSWORD=password
POSTGRES_DB=myblogdb

# Security
SECRET_KEY=your-super-secret-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=30

Tests des modèles

Chaque modèle est livré avec des tests préconfigurés :

$ cd my-blog-api
$ source .venv/bin/activate
$ python -m pytest

======================== test session starts ========================
tests/test_items.py::test_create_item PASSED
tests/test_items.py::test_read_items PASSED
tests/test_items.py::test_read_item PASSED
tests/test_items.py::test_update_item PASSED
tests/test_items.py::test_delete_item PASSED
======================== 5 passed in 0.23s ========================

Flux de développement avec les modèles

1. Choisir le bon modèle

Apprentissage / API simples : fastapi-default
Haute performance : fastapi-async-crud
Formats de réponse personnalisés : fastapi-custom-response
Déploiement en production : fastapi-dockerized
Applications avec base de données : fastapi-psql-orm
Architecture personnalisée : fastapi-empty

2. Créer et configurer

$ fastkit startdemo
# Follow the prompts
$ cd your-project
$ source .venv/bin/activate

3. Développement

# Démarrer le serveur de développement
$ fastkit runserver

# Exécuter les tests
$ python -m pytest

# Ajouter de nouvelles fonctionnalités
$ fastkit addroute new-resource your-project

4. Déploiement

Pour les modèles destinés à la production (fastapi-dockerized, fastapi-psql-orm) :

# Build for production
$ docker build -t your-app .

# Deploy with Docker Compose
$ docker-compose up -d

Bonnes pratiques

1. Choisir les modèles judicieusement

Commencez par les modèles plus simples pour apprendre
Utilisez les modèles avec base de données pour les applications pilotées par les données
Utilisez les modèles Docker pour les déploiements en production

2. Gestion de l'environnement

Utilisez toujours des fichiers .env pour la configuration
Ne committez jamais de données sensibles dans le contrôle de version
Utilisez des environnements différents pour développement / production

3. Stratégie de personnalisation

Ajoutez de nouvelles routes avec fastkit addroute
Modifiez le code existant pour l'adapter à votre logique métier
Gardez la structure du projet organisée

4. Tests

Exécutez les tests régulièrement pendant le développement
Ajoutez des tests pour les nouvelles fonctionnalités que vous implémentez
Utilisez la structure de tests fournie comme guide

Dépannage

Problèmes de connexion à la base de données (modèles PostgreSQL)

Si vous n'arrivez pas à vous connecter à PostgreSQL :

Vérifiez que Docker tourne :

$ docker ps

Vérifiez le conteneur PostgreSQL :

$ docker-compose logs postgres

Vérifiez les variables d'environnement :

DATABASE_URL=postgresql://user:password@localhost:5432/dbname

Échecs de build Docker

Si le build Docker échoue :

Vérifiez la syntaxe du Dockerfile
Vérifiez que tous les fichiers sont présents
Vérifiez que le démon Docker tourne

Dépendances manquantes

Si vous obtenez des erreurs d'import :

Activez l'environnement virtuel :
```
$ source .venv/bin/activate
```
Installez les dépendances :
```
$ pip install -r requirements.txt
```

Étapes suivantes

Maintenant que vous comprenez les modèles :

Votre premier projet : construire une application complète
Ajouter des routes : étendre votre projet basé sur un modèle
Référence CLI : maîtriser toutes les commandes disponibles

Astuces sur les modèles

Les modèles sont d'excellents points de départ, pas des solutions finales
Personnalisez les modèles pour qu'ils correspondent à vos besoins spécifiques
Étudiez le code des modèles pour apprendre les bonnes pratiques de FastAPI
Utilisez le contrôle de version pour suivre vos personnalisations

Utiliser les modèles

Modèles disponibles

Descriptions des modèles

1. fastapi-default

2. fastapi-async-crud

3. fastapi-custom-response

4. fastapi-dockerized

5. fastapi-psql-orm

6. fastapi-empty

Créer un projet à partir d'un modèle

Comparaison des fonctionnalités des modèles

Configuration spécifique à chaque modèle

Utiliser fastapi-psql-orm

Utiliser fastapi-dockerized

Utiliser fastapi-custom-response

Structure des projets de modèle

Structure de fastapi-default

Structure de fastapi-psql-orm

Personnaliser les modèles

1. Ajouter de nouvelles routes

2. Modifier la configuration

3. Ajouter des variables d'environnement

Tests des modèles

Flux de développement avec les modèles

1. Choisir le bon modèle

2. Créer et configurer

3. Développement

4. Déploiement

Bonnes pratiques

1. Choisir les modèles judicieusement

2. Gestion de l'environnement

3. Stratégie de personnalisation

4. Tests

Dépannage

Problèmes de connexion à la base de données (modèles PostgreSQL)

Échecs de build Docker

Dépendances manquantes

Étapes suivantes

1. `fastapi-default`

2. `fastapi-async-crud`

3. `fastapi-custom-response`

4. `fastapi-dockerized`

5. `fastapi-psql-orm`

6. `fastapi-empty`

Utiliser `fastapi-psql-orm`

Utiliser `fastapi-dockerized`

Utiliser `fastapi-custom-response`

Structure de `fastapi-default`

Structure de `fastapi-psql-orm`