Forem: DUVAL Olivier

Redis cache clé / valeur ou comment éviter l'anti-pattern Singleton dans un contexte Web réparti

DUVAL Olivier — Wed, 15 May 2024 13:21:31 +0000

Sommaire

Préambule
Pourquoi le problème est apparu ?
Solution technique

Préambule TL;DR

💥 Dernièrement, lors d'un développement, on a eu un bug bloquant, dû à une variable qui devait préciser la stratégie à adopter post-connexion de l'utilisateur.

📌 Si le connecté est de type A alors utiliser la stratégie A (consultation BDD), sinon prendre la stratégie P (consultation API) car il est de type P.

Schéma du déroulé :

1- connexion ➙ stratégie à adopter, stocker dans une variable type_strategie ➙ obtention des informations selon la stratégie

N- une fois connecté ➙ lecture de la stratégie via la variable ➙ les informations varient (un Ctrl-F5 ou un retour sur la page)

On reconnait ici une variante du pattern Strategy, où la variable (calculée à l'authentification) qui en précise le type était en...global, autrement dit, un singleton, et cela a causé des effets de bord pour tous les connectés : pour le même connecté, la page affichant des données issus de la stratégie...changeait, parfois aller chercher les informations de la stratégie A et d'autres la stratégie B voire pire, le dernier connecté changeait la stratégie pour tous les autres, "incompréhensible" ! 🥵

Que se passe-t-il Houston ?

➢ Dans un contexte Web multi-nœuds, chaque serveur Web a son espace mémoire, indépendant des autres. Le stockage d'une valeur dans une variable le sera uniquement sur le nœud / serveur Web atteint. A chaque requête Web, celle-ci peut changer de nœuds, selon la répartition de charge.

➢ Nous utilisons Gunicorn qui est un serveur Web WSGI, cela permet d'exécuter un serveur d'applications python comme Django. Gunicorn est architecturé en plusieurs workers (ou noeuds), chaque worker a son espace mémoire isolé. Dans un contexte de production, on pourrait également avoir Gunicorn réparti sur plusieurs serveurs VM / noeuds : les requêtes Web sont non seulement réparties sur les différents serveurs, mais aussi réparties au sein de Gunicorn, on ne sait pas par avance où ira la requête (sur quel noeud et sur quel worker), pour schématiser ce type d'architecture ops :

source : https://excalidraw.com/#json=CXDUttmskxjwScBjEr35x,BavDLiX5xlisHZB5viyrPQ

💣 ⚠ Il y a autant de versions différentes de VAR qu'il existe de workers / noeuds.

💣 ⚠ Corolaire : Cette variable VAR est unique et partagée (singleton) à tous les connectés et non selon leur profil propre, l'effet "le dernier qui dit qui a raison" s'appliquera.

Un utilisateur ira par exemple sur le noeud 1 puis sur le worker 2, et la prochaine fois, peut être sur le noeud 2 puis sur le worker 1, ainsi de suite : la stratégie à adopter pouvait donc changer selon le noeud / worker sur lequel la requête tombait 🎭 l'état de la variable n'est pas conservée.

Solution élégante

1️⃣ La 1ère solution venant en tête est d'utiliser les variables de session pour stocker le type de stratégie propre au connecté.

session['strategy'] = A

...sauf que cette idée était difficile à mettre en place car non triviale dans le code et cette variable de type de stratégie est utilisé côté frontoffice mais aussi côté backoffice.

2️⃣ C'est là que Redis vient à la rescousse ! Redis est déjà utilisé comme message broker / PubSub, cet article décrit son usage dans un contexte de lancement de tâches différées. Redis permet aussi de l'utiliser en base NoSql clé / valeur pour du cache par exemple, autant prendre cette possibilité. Django fournit un provider par défaut pour Redis.

Que cela soit côté Frontoffice ou Backoffice, on stocke la stratégie dans une clé Redis. La clé est ici l'identifiant unique du connecté.

Le scénario se déroule maintenant de la façon suivante :

1- connexion ➙ stratégie à adopter, stocker dans une clé(uid_connecté) Redis ➙ obtention des informations selon la stratégie
N- une fois connecté ➙ lecture de la stratégie via la clé(uid_connecté) Redis ➙ la bonne stratégie est prise en compte à chaque fois, les informations sont bonnes à chaque requête

La grande différence réside à ce que VAR est maintenant partagée par tous les noeuds / workers, sa clé d'accès est un identifiant unique du connecté

Schématiquement :

source : https://excalidraw.com/#json=tuOIxkk9k1D3Zu8qVNyvD,JPrfOfaUnFnzCQVngYOvjQ

Technique

Configuration pour le provider de cache Redis, du settings Django

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": REDIS_CACHE # par ex. redis://api-redis-db:6379
    }
}

0️⃣ un énuméré est utilisé pour le type de stratégie

class StrategyType(IntEnum):    
    BDD = 1
    API= 2

1️⃣ à la connexion, stockage :

def _set_cache_strategy(uid_connected, strategy: StrategyType):
    """
    pas de timeout 
    sinon par défaut 300 s https://docs.djangoproject.com/fr/5.0/ref/settings/#std-setting-CACHES-TIMEOUT)
    """
    cache.set(uid_connected, strategy, timeout=None)

2️⃣ pour les autres requêtes, on lit la stratégie :

def _get_cache_strategy(uid_connected):
    return cache.get(uid_connected)

Simple et efficace, plus de problème !

Celery & Redis : exécution de tâches en différé / asynchrones

DUVAL Olivier — Sun, 12 Mar 2023 10:46:22 +0000

Sommaire

Préambule
Architecture
Code
- Code tâche / API et configuration Celery
- Docker
Sources

Préambule TL;DR

Lorsque l'on développe des applications Web, il peut arriver que l'on doive exécuter des tâches qui dépassent le timeout du serveur Web : génération de gros fichiers, envoi de mails en masse, exécution d'une machine learning, traitement de fichiers importés, génération de rapports, ...tout un tas de cas d'utilisation qui arrivent régulièrement.

L'exécution de ce type de tâches est difficilement réalisable directement par le serveur d'applications Web, qui a un timeout de configuré et qui doit être réduit (quelques secondes) sous peine d'effondrement (j'exagère...un peu 🥵😁).

Nous allons voir, grâce à Django, Celery et Redis comment exécuter des tâches en différé, elles ne seront alors pas exécutées par le serveur d'application mais par un processus à part : un worker Celery.

Architecture

Dans ce contexte, les différentes briques utilisées seront :

Django pour le serveur d'applications Web avec le module Celery : il enverra une tâche à exécuter en asynchrone
Celery worker : les processus applicatifs qui exécuteront les tâches qui leur seront envoyées
Redis : servira à être un message broker. En plus d'être un serveur de cache de données et/ou NoSql, Redis implémente le pattern de messages Pub/Sub : il y a des producteurs / clients (serveur d'applications) qui envoient des messages et des consommateurs de messages qui vont les lire (celery workers) : Celery django va envoyer l'ordre d'exécuter une tâche et un des workers va lire la tâche à exécuter et le faire. Le lancement des tâches est atomique, c'est à dire que la tâche ne va être prise que par un seul worker.

On peut représenter cette communication entre applications et processus avec ces différentes briques de la façon suivante :

(source : https://excalidraw.com/#json=MpX5kp_uYfL17ugUS6a-S,CgyUY0Aqanul0DCksVDzuA)

Un peu de code !

On va s'amuser à créer une tâche qui va attendre 5 secondes avant de nous dire qu'elle démarre, cette tâche ne sera pas exécuter dans le serveur d'applications mais dans le worker celery, en différé : le serveur d'applications rend la main immédiatement, la tâche s'exécute en temps voulu

Modules

Il nous faudra a minima comme modules, pour le côté client :

django & djangorestframwork [pour une API de lancement d'une tâche]
celery
redis

Pour le côté serveurs :

un serveur d'applications Web avec une API qui lance une tâche
un worker qui réceptionnera notre tâche à exécuter
un redis pour l'échange de messages entre le client Web et le worker Celery

Docker

4 images ont été préparées pour lancer 4 conteneurs : nginx pour le reverse proxy host -> conteneur, serveur d'application django, un worker celery, le message broker redis

au lancement de ces services via docker-compose up on aura

$ docker ps
CONTAINER ID   IMAGE                    COMMAND                  CREATED          STATUS          PORTS                                            NAMES
6caf76fca92e   api-and-worker           "celery -A core.asyn…"   11 minutes ago   Up 11 minutes   8100/tcp                                         celery-worker
9cadb4c717a5   nginx                    "nginx -g 'daemon of…"   11 minutes ago   Up 11 minutes   0.0.0.0:80->80/tcp                               nginx-api-server
b83db3cf05eb   redis:7.0.8              "docker-entrypoint.s…"   11 minutes ago   Up 11 minutes   0.0.0.0:6379->6379/tcp                           redis-broker
654b6d1222de   api-and-worker           "python3 manage.py r…"   11 minutes ago   Up 11 minutes   8100/tcp                                         api-server

avec le no-trunc pour voir les paramètres des services lancés que l'on peut retrouver dans le docker-compose :

$ docker ps --no-trunc
CONTAINER ID                                                       IMAGE                    COMMAND                                       CREATED          STATUS          PORTS
                               NAMES
6caf76fca92e5b4e83663019f34f57b5780fd3a9244d07daeb431f5f0e57b255   api-and-worker           "celery -A core.async_tasks worker -l info"   11 minutes ago   Up 11 minutes   8100/tcp
                               celery-worker
9cadb4c717a535d609dbd43ee2bb65667efd1b74f873e6e5b93efd7be365ab3a   nginx                    "nginx -g 'daemon off;'"                      11 minutes ago   Up 11 minutes   0.0.0.0:80->80/tcp                               nginx-api-server
b83db3cf05eb7c9d9aaa4fb3ce120e98f2820f1040434d336ca024e0d1f0a5b6   redis:7.0.8              "docker-entrypoint.sh redis-server"           11 minutes ago   Up 11 minutes   0.0.0.0:6379->6379/tcp                           redis-broker
654b6d1222de36b56f3e3d7bc9d13376ec7e54b527c316bbac7649576a82263f   api-and-worker           "python3 manage.py runserver 0.0.0.0:8110"    11 minutes ago   Up 11 minutes   8100/tcp
                               api-server

Code

On aura :

un module configuration celery : broker de message à utiliser, paramétrage Celery (tâches à prendre en compte, serialisation, timeout, etc)
un module "tasks", commun à l'application et au worker sera nécessaire pour définir la tâche et l'appeler ensuite, une API qui déclenchera cette tâche

Déclaration de la tâche, on met une temporisation pour démontrer l'intérêt :

from time import sleep
import logging
logger = logging.getLogger('django')
from core.async_tasks.celery import app

@app.task
def execute_long_task(title: str, delay: int, wordings: list):
    logger.info(f"** On s'endort {delay} secondes avant de lancer la tâche ZZzzzZZzzzzzzzzz **")

    sleep(delay)

    logger.info(f'** On se réveille ! Démarrage de la tâche {title} avec {wordings} **')
    logger.info(f'** Terminée !')

API d'envoi et d'ordre d'exécution de la tâche:

class ExecuteTaskApi(APIView):
    permission_classes = [AllowAny]
    renderer_classes = (JSONRenderer,)

    def get(self, request, *args, **kwargs):
        execute_long_task.delay('Exécute ma longue tâche !', 5,
                                ['Vais attendre', 'le super pouvoir de Celery'])
        return Response({'data': 'je réponds immédiatement sans attendre la fin de la tâche !'})

Configuration de Celery

import os
from celery import Celery

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "backend.settings")

app = Celery("tasks")
app.config_from_object("core.async_tasks.celery_config")

# par défaut, il recherche les tâches dans le module "tasks.py" https://docs.celeryq.dev/en/stable/reference/celery.html#celery.Celery.autodiscover_tasks
app.autodiscover_tasks(['api'])

Logs de l'exécution de http://plateform/api/execute_task/ sur le navigateur ou par curl

$ curl http://plateform/api/execute_task/
{"data":"je réponds immédiatement sans attendre la fin de la tâche !"}

Le serveur d'application envoie l'ordre d'exécuter la tâche et rend immédiatement la main au navigateur, le worker réceptionne la tâche à exécuter, il y a une temporisation de 5 secondes pour démontrer l'aspect différé / asynchrone :

api-server        | INFO basehttp "GET /api/execute_task/ HTTP/1.0" 200 73
celery-worker     | [2023-03-12 11:19:00,851: INFO/MainProcess] Received task: api.tasks.execute_long_task[3f1b8339-4192-45da-9607-23246b532af7]
celery-worker     | INFO tasks ** On s'endort 5 secondes avant de lancer la tâche ZZzzzZZzzzzzzzzz **
celery-worker     | [2023-03-12 11:19:00,854: INFO/ForkPoolWorker-8] ** On s'endort 5 secondes avant de lancer la tâche ZZzzzZZzzzzzzzzz **
celery-worker     | INFO tasks ** On se réveille ! Démarrage de la tâche Exécute ma longue tâche ! avec ['Vais attendre', 'le super pouvoir de Celery'] **
celery-worker     | [2023-03-12 11:19:05,860: INFO/ForkPoolWorker-8] ** On se réveille ! Démarrage de la tâche Exécute ma longue tâche ! avec ['Vais attendre', 'le super pouvoir de Celery'] **
celery-worker     | INFO tasks ** Terminée !
celery-worker     | [2023-03-12 11:19:05,861: INFO/ForkPoolWorker-8] ** Terminée !

La tâche a duré 5 secondes, entre 11:19:00 et 11:19:05, indépendamment du serveur Web et de son timout !

On peut dès lors imaginer des tâches qui pourraient durer quelques minutes pour effectuer des traitements particuliers.

Sources

Celery permet d'autres paramétrages comme la reprise de tâche en cas d'échec ou de s'assurer qu'une tâche ne sera pas exécutée 2 fois, etc

Il existe aussi un outil de monitoring pour visualiser l'état des tâches : Flower

Ou encore, la possibilité d'avoir des tâches récurrentes et programmées, "à la crontab", grâce à Celery Beat.

Retrouvez les sources sur le Github : https://github.com/zorky/celery-redis-django-tasks

POO et encapsulation JS

DUVAL Olivier — Wed, 29 Jun 2022 13:55:14 +0000

Sommaire

TL;DR;
Exemples d'implémentations
Chrono et couleur
Sources et démos

TL;DR;

Après plus de 5 années à développer en TypeScript (pour Angular), j'avais envie de taper un peu de JavaScript vanilla, sur des concepts et fondamentaux de ce langage.

Sur les projets des dernières années, en MVC / Webforms, MVT ou AngularJs, j'ai pu m'apercevoir de pratiques que j'estime mauvaises chez certains devs pour le développement en JavaScript : une approche uniquement par l'empilement de fonctions et non objet, ce qui amène un moment donné à du spaghetti code et cela devient illisible et (très) difficile à maintenir.

L'encapsulation en programmation objet permet, sur un objet, d'exposer au client de cet objet uniquement des méthodes / fonctions dites publiques et de cacher / masquer (rendre privé) toutes les fonctions utiles à l'objet et à son comportement, autrement dit, l'implémentation réelle sera interne à l'objet : l'accès et l'état des propriétés de cet objet ne seront accessibles que par le biais de ces fonctions publiques, cela protège et simplifie le comportement de cet objet.

Il faudra instancier l'objet pour l'utiliser.

Dans les exemples ci-après, nous allons utiliser ce principe POO en Javascript avec différentes implémentations ou façons de faire et un exemple plus élaboré avec un chrono et un compte à rebours.

Pour me simplifier la tâche, et comme disent mes enfants, "flemme", j'ai utilisé Boostrap pour rendre joli le tout, et jQuery pour l'utilisation des éléments du DOM (sélecteurs), bien que j'aurais pu utiliser le querySelector.

Différentes implémentations

Imaginons un objet avec une propriété et des méthodes pour y accéder en lecture ou en écriture et pour concaténer avec une chaîne, il y a plusieurs implémentations possible en utilisant le scope et/ou closures des fonctions, en ES5. Ma préférence va pour la 3ème forme.

1ère forme

déclaration

;
var MonObjet = MonObjet || {};
(function() {
   /*== private ==*/
   var _property = '';
   var _concat = function(val) {
     _property = `${_property}${val}`;
     return _property;
   }

   /*== public ==*/
   MonObjet.get = function() {
     return _property;
   }
   MonObjet.set = function(val) {
     _property = val;

   }
   MonObjet.concatWith = function(val) {
     return _concat(val);
   }
})();

appel

(function() {
    console.log(MonObjet.get());
    MonObjet.set('Olivier');
    var concat = MonObjet.concatWith(' Duval');
    console.log(concat); // affiche Olivier Duval
})();

2ème forme

déclaration

function MonObjet2() {
    /*== private ==*/
    var _property = '';
    var _concat = function(val) {
        _property = `${_property}${val}`;
        return _property;
    };

    /*== public ==*/
    this.get = function() {
        return _property;
    }
    this.set = function(val) {
        _property = val;
    }
    this.concatWith = function(val) {
        return _concat(val);
    }
}

appel

(function() {
    var monObjet2 = new MonObjet2();
    console.log(monObjet2.get());
    monObjet2.set('Valérie')
    var concat2 = monObjet2.concatWith(' Aubin');
    console.log(concat2); // affiche Valérie Aubin
})();

3ème forme

déclaration

var MonObjet3 = function() {
    /*== private ==*/
    var _property = '';
    var _concat = function(val) {
        _property = `${_property}${val}`;
        return _property;
    };
    var _get = function() {
        return _property;
    };
    var _set = function(val) {
        _property = val;
    };

    /*== public ==*/
    return ({
        get: _get,
        set: _set,
        concatWith: _concat
    });
};

appel

(function() {
    var monObjet3 = MonObjet3();
    console.log(monObjet3.get());
    monObjet3.set('John');
    var concat3 = monObjet3.concatWith(' Do');
    console.log(concat3); // affiche John Do
})();

Chrono et compte à rebours

Un usage plus poussé consisterait à créer des objets pour gérer

un formulaire chrono / compte à rebours : saisie d'un nombre puis activation d'un chrono ou d'un compte à rebours
un formulaire couleur : l'appui sur le bouton après sélection d'une couleur modifie la couleur du bouton
une classe compteur pour gérer la logique du chrono ou du compte à rebours

Je vous laisse regarder les démos et leur code !

Sources et démos

Démo exemples d'implémentations ouvrir la console !

Démo chrono / compte à rebours et couleur.

Sources sur Github.

NestJS 101

DUVAL Olivier — Sun, 08 May 2022 12:25:40 +0000

TL;DR

Article pour introduire NestJS, framework Typescript backend pour développer des API : fortement inspiré d'Angular, on trouvera des controlers, services, guards et autres décorateurs.

NestJS kesako ?

NestJS est un framework Javascript (plus précisément TypeScript) MVC pour développer un backend au-dessus de NodeJs et Express ou Fastify (qui géront les routes de bas niveau HTTP). Il permet également de développer des API, que nous verrons dans ce billet pour une introduction à NestJs.

La philosophie se rapproche de frameworks backends de type ASPNET WebApi C# / .NET, Java Spring ou Angular côté frontend : approche par couches (controllers, services via de l'injection de dépendances, qui va apporter une couche d'abstraction), par attributs / annotations que l'on appellera décorateurs que l'on retrouve en Angular, modulaire (comme Angular). L'écriture du code s'effectue en TypeScript (mais Javascript reste possible), on retrouvera nos bonnes pratiques de développement (typage, POO, design patterns).

NestJS propose également un CLI nest qui permettra de générer du scaffolding de classes, services, controllers, etc, bon nombre de modules / plugins / mécanismes : des ORM avec par exemple TypeORM ou d'authentification avec PassportJS (et la mécanique technique de gestion de JWT) et d'autorisation : qui a le droit à accéder à telle ou telle API / fonction (Guards avec des rôles, comme sous Angular), de sécurité avec CORS et une prise en charge d'OpenAPI via Swagger pour la documentation de vos APIs.

NestJs d'un point de vue architecture reprend tout ce que l'on connaît déjà de frameworks backend ou frontend de type SPA (particulièrement Angular), en TypeScript, ce qui permet de mutualiser ses connaissances front côté back.

Sommaire

NestJS
API livres
- Initialisation
- Squelettes controller / service / entité
- Modification des squelettes
Conclusion

API Livres

Nous allons reprendre dans cette introduction, l'application de gestion de livres de la série Angular / Django REST, en ne faisant que les livres pour l'instant, sans authentification, et sans interface, en axant uniquement sur une API.

Installation de NestJS et initialisation de l'application

$ mkdir library_nest && cd library_nest

Commençons par le CLI, de façon global :

$ npm i -g @nestjs/cli

$ nest --version
8.2.5

Création du squelette de l'application que l'on appellera backend grâce au CLI, je choisis npm comme gestionnaire de packages, aller dans backend à l'issue du scaffolding

$ nest new backend
⚡  We will scaffold your app in a few seconds..

CREATE backend/.eslintrc.js (665 bytes)
CREATE backend/.prettierrc (51 bytes)
CREATE backend/nest-cli.json (118 bytes)
CREATE backend/package.json (1992 bytes)
CREATE backend/README.md (3340 bytes)
CREATE backend/tsconfig.build.json (97 bytes)
CREATE backend/tsconfig.json (546 bytes)
CREATE backend/src/app.controller.spec.ts (617 bytes)
CREATE backend/src/app.controller.ts (274 bytes)
CREATE backend/src/app.module.ts (249 bytes)
CREATE backend/src/app.service.ts (142 bytes)
CREATE backend/src/main.ts (208 bytes)
CREATE backend/test/app.e2e-spec.ts (630 bytes)
CREATE backend/test/jest-e2e.json (183 bytes)

? Which package manager would you ❤️  to use? npm
🚀  Successfully created project backend
👉  Get started with the following commands:

$ cd backend

On peut lancer le serveur

$ npm run start ou $ npm run start:dev pour la prise en compte des modifications de code et du rechargement automatique du serveur (le watcher), en mode développement, c'est plus que recommandé.

La compilation / transpilation en javascript est effectuée dans dist qu'utilisera le serveur.

On peut accéder à http://localhost:3000/ via un navigateur.

S'il se trouvait un souci avec le port (déjà pris par exemple), il est possible de le modifier dans le fichier backend/src/main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000); // modifier le port ICI
}
bootstrap();

Controller / service / entité

Dans cet article, nous ferons simple, pour démontrer l'architecture controller / service, sans accès à une base de données.

Le déroulement des appels peut être schématisé de la manière suivante :

(source : https://excalidraw.com/#json=RLHChssGR5kaOEKRfNmdI,yIh11YsH_-LOCn11-MJjzA)

Créons avec le CLI quelques squelettes, dans un module book.

Nous aurons dans ce 1er article, un module book dans lequel se trouvera un controller bookControler et un service bookService et une classe entité book. Dans cet article, on n'accédera pas à une base de données, les livres seront juste une liste en dur dans le code.

$ nest g module book # il crée src/book/book.module.ts et met à jour le module principal src/app.module.ts qui le référence
$ nest generate --flat controller book/controller/book # controller en mode flat pour générer les fichiers dans un emplacement choisi, ici book/controller/book, il met aussi à jour le module book.module.ts
$ nest generate --flat service book/service/book # idem mais pour le service, le module book.module.ts est mis à jour
$ nest g --flat class book/book.entity # la classe entité

On a la structure suivante de src :

src
└───book
    ├───controller
    └───service

$ ls -R src | awk '
/:$/&&f{s=$0;f=0}
/:$/&&!f{sub(/:$/,"");s=$0;f=1;next}
NF&&f{ print s"/"$0 }'

src/app.controller.spec.ts
src/app.controller.ts
src/app.module.ts
src/app.service.ts
src/book/
src/main.ts
src/book/book.entity.spec.ts
src/book/book.entity.ts
src/book/book.module.ts
src/book/controller/
src/book/service/
src/book/controller/book.controller.spec.ts
src/book/controller/book.controller.ts
src/book/service/book.service.spec.ts
src/book/service/book.service.ts

Modifications des fichiers pour le rendre utilisable

L'entité book devient :

export class BookEntity {
  id: number;
  title: string;
}

Le service renvoie une liste en dur de livres ou un livre en particulier par son ID, il sera injecté dans le controller, le mot clé @Injectable est nécessaire, on initialise quelques livres en dur dans le service :

import { Injectable } from '@nestjs/common';
import { BookEntity } from '../book.entity';

@Injectable()
export class BookService {
  books: BookEntity[] = [
    <BookEntity>{ id: 1, title: 'NestJS 101' },
    <BookEntity>{ id: 2, title: 'Angular' },
  ];
  async getAll(): Promise<BookEntity[]> {
    return this.books;
  }
  async getById(id): Promise<BookEntity> {
    return this.books.find((_book: BookEntity) => _book.id === Number(id.id));
  }
}

et le controller qui l'utilise, le constructeur, comme en Angular, permet d'injecter le service. Les décorateurs @Controller() et @get() permettent de définir notre API : sur /api/books et la méthode GET via @Get() sur la fonction GetAll() qui renvoie tous les livres ou /api/books/2 GetById() sur un ID particulier.

import { Controller } from '@nestjs/common';
import { BookService } from '../service/book.service';

@Controller('api/books')
export class BookController {
  constructor(private bookService: BookService) {}
  @Get()
  async getAll(): Promise<BookEntity[]> {
    return await this.bookService.getAll();
  }
  @Get(':id')
  async getById(@Param() id): Promise<BookEntity> {
    return await this.bookService.getById(id);
  }
}

Le serveur recharge le tout

[13:31:58] File change detected. Starting incremental compilation...

[13:31:59] Found 0 errors. Watching for file changes.

[Nest] 3952  - 08/05/2022, 14:12:11     LOG [NestFactory] Starting Nest application...
[Nest] 3952  - 08/05/2022, 14:12:11     LOG [InstanceLoader] AppModule dependencies initialized +95ms
[Nest] 3952  - 08/05/2022, 14:12:11     LOG [InstanceLoader] BookModule dependencies initialized +2ms
[Nest] 3952  - 08/05/2022, 14:12:11     LOG [RoutesResolver] BookController {/api/books}: +121ms
[Nest] 3952  - 08/05/2022, 14:12:11     LOG [RouterExplorer] Mapped {/api/books, GET} route +7ms
[Nest] 3952  - 08/05/2022, 14:12:11     LOG [RouterExplorer] Mapped {/api/books/:id, GET} route +2ms
[Nest] 3952  - 08/05/2022, 14:12:11     LOG [NestApplication] Nest application successfully started +4ms

et l'API renvoie bien tous les livres au format JSON

ou un des livres

Conclusion

Cette introduction permet de comprendre l'architecture de base de NestJS, dans des prochains articles, nous nous attaquerons à l'accès à une base de données avec la librairie TypeORM, l'authentification et bien plus !

Retrouvez les sources sur https://github.com/zorky/library_nestjs/tree/nestjs-101 , installer les packages dans backend : $ npm install et exécuter ! $ npm run start:dev

Docker Swarm & Portainer UI

DUVAL Olivier — Sat, 02 Oct 2021 13:43:27 +0000

Docker Swarm & Portainer UI où l'orchestration à moindre frais.

Sommaire

Introduction
Docker swarm
- Commandes pour gérer un cluster Swarm
Portainer
- Introduction à Portainer
- Fonctionnalités utiles
Conclusion

Introduction

De nos jours, il est courant et fortement recommandé de mettre en place de la "conteneurisation", souvent au travers de la technologie Docker qui a accéléré la tendance depuis 10 ans :

Dans une équipe de développements applicatifs, sur l'environnement de développement :

avoir des images prêtes à l'emploi : par exemple une image du serveur d'applications, que toute l'équipe utilise, sur la même base de modules et versions, annuaire LDAP, base de données, etc
facilité de mise en place d'images, facilement déployables sur chaque station de travail : une image est légère et son exécution sera rapide, pour tester ou effectuer des POC, cela s'avère plus accessible
une gestion des dépendances (versions des packages, modules, ...) nettement améliorée et contrôlée

Dans un environnements de tests ou de production

Ces images pourront être packagées pour une utilisation sur une plateforme de tests et / ou la plateforme de prod, de façon rapide et efficace : déploiements facilités et mise en production efficiente.

Sur un environnement de production, il y aura régulièrement plusieurs instances d'applications sur plusieurs VM / serveurs, afin d'absorber la charge des accès utilisateurs (répartition de charge), il va donc falloir déployer toutes ces images applicatives sous forme de conteneurs légers vers ces différentes instances de machines, et ensuite, s'assurer d'orienter tel flux (https, accès base, etc) vers tels conteneurs : cette façon de faire se nomme de l'orchestration de conteneurs, qui va également gérer le cycle de vie des conteneurs : scaling, création, déploiement / rechargement pour aller vers du Zero downtime deployment, load-balancing, la communication entre les containers etc

Docker propose un orchestrateur natif à leur technologie, dans le moteur de conteneurs : Docker Swarm, où l'on va retrouver nos habitudes :

avec le docker CLI
le docker-compose Yaml, du déclaratif, qui servira aussi à la gestion des conteneurs dans Swarm (stack)

Docker swarm & Portainer

Vocabulaire

Worker = un nœud du cluster Swarm, une VM ou une machine physique

Manager = un nœud spécial du cluster Swarm qui aura pour charge d'orchestrer les services / containers du cluster (flux, déploiements, load balancing et haute disponibilité des services exposés), tel un chef d'orchestre ! Un manager peut aussi jouer le rôle de worker.

Stack = un "fichier" docker-compose dans lequel ait décrit les services avec les règles associées : d'images sources à utiliser, de déploiement, de ressources (volumes, networks, ...voire CPU & co)

Service = un élément d'une stack à déployer selon des règles

Task = un container déployé sur un / des noeuds

Registry docker

Dans un écosystème où l'orchestration demande des images pour les transformer en conteneurs ("instances" d'une image), il est nécessaire d'avoir un registry docker qui permettra de stocker ces images à déployer :

le Docker Hub en est un

ou avoir une machine registry dédiée à cela :

via une solution légère de type registry développé par Docker et disponible sur le Hub
via une solution avec une interface Web de type harbor / github

Docker swarm

Docker swarm est inclus dans le moteur docker, c'est un orchestrateur de containers, qui permettra de gérer sur un ensemble de machines / VM, les containers sur chacune de ces instances (flux, déploiement, cycle de vie, répartitions et disponibilité), et, avouons-le, la mise en place reste accessible et rapide, une fois les concepts appréhendés.

Un cluster Swarm a plusieurs nœuds avec au moins 2 nœuds, selon 2 types :

de type manager : aura la mission de diriger les flux entrants vers les nœuds (load balancer) et la gestion de l'orchestration des conteneurs : réplication dans le cluster, déploiement / rechargement des services, load-balancing. Il est conseillé d'avoir un nombre de manager impairs et au moins 3, selon l'algorithme Raft. Un manager peut aussi jouer le rôle de worker
de type worker, on pourra avoir plusieurs nœuds de ce type, afin de répartir la charge, un noeud à différents état : Active, Drain et Pause. Le mode Drain permettra de dire au manager de ne plus déployer vers les nœuds worker les services et donc d'arrêter les flux vers celui-ci. Le Pause, que j'utilise rarement, permet de suspendre tous les processus dans les containers contenus sur le nœud, en revanche, les flux continuent à être dirigés vers ce dernier.

Schématiquement, un cluster composé de managers et de workers se représentera ainsi :

Source : https://docs.docker.com/engine/swarm/how-swarm-mode-works/nodes/

Le cluster swarm se gère avec la commande docker (CLI), tout comme on le ferait habituellement avec des images / containers /... en local d'une machine, c'est le gros avantage, on ne perd pas ses habitudes :)

Quelques commande avec le docker CLI

Les commandes ont le plus souvent une aide, il suffit d'utiliser l'option --help pour avoir la liste des arguments possible.

Le docker CLI permet de gérer un cluster swarm, quelques commandes que j'utilise régulièrement, hormis l'initialisation :

Swarm

initialisation d'un cluster swarm

$ docker swarm init --advertise-addr IP_MANAGER:2377

informations sur le cluster

$ docker info

obtenir un TOKEN worker / node à partir du manager

$ docker swarm join-token worker
docker swarm join --token SWMTKN-1-id1-id2 IP_MANAGER:2377

faire rejoindre une machine sur le cluster en tant que worker

A partir de la commande donnée précédemment, il suffit de la recopier à partir d'une machine cluster

$ docker swarm join --token SWMTKN-1-id1-id2 IP_MANAGER:2377

worker / noeud : faire quitter un noeud du cluster, à partir d'un noeud :

* docker swarm leave

Noeud(s)

liste des noeuds

$ docker node ls

liste des containers / tâches des noeuds ou d'un noeud

$ docker node ps
$ docker node ps <NODE_NAME>

modifier l'état d'un noeud

$ docker node <ID_NODE> --availability "drain"
$ docker node <ID_NODE> --availability "active"

Stack(s)

liste des stacks du cluster contenant, pour chacun, des services

$ docker stack ls 
NAME                SERVICES            ORCHESTRATOR
api-XYZ             7                   Swarm
ws                  1                   Swarm
fluend              3                   Swarm
ABC                 7                   Swarm
loki-grafana        3                   Swarm
portainer           2                   Swarm
prometheus          8                   Swarm

liste des containers / tâches d'une stack

$  docker stack ps <STACK_NAME>

liste des services d'une stack (un service correspond à une section du docker compose)

$ docker stack services fluend

Service(s)

liste des services d'un noeud

$ docker service ls

informations d'un service

$ docker service inspect --pretty <SERVICE_NAME>

liste des containers d'un service avec répartition sur les noeuds

$ docker service ps <SERVICE_NAME>
$ # ou enlever le troncage du log de démarrage et la résolution DNS
$ docker service ps <SERVICE_NAME> --no-resolve --no-trunc

rechargement d'un service

# forcer le redéploiement d'un service
$ docker service update --force <SERVICE_NAME>

réplication d'un service

# réplication à 2 d'un service
$ docker service scale <SERVICE_NAME>=2

logs d'un service

$ docker service logs <SERVICE_NAME> -f

liste des configurations du cluster

$ docker config ls

Config(s)

lire une config

$ docker config inspect <CONFIG_NAME> --pretty

Portainer

Introduction

Portainer est une application qui propose une interface Web qui vous aidera à gérer votre cluster, à la place de la ligne de commande qui peut s'avérer rébarbative ou tout simplement pour simplifier la connaissance de toutes les options possible du CLI docker pour gérer le cluster ou tout simplement pour avoir une meilleure vue du cluster, sous forme de tableau de bord.

Comme vous avez pu le voir sur le docker CLI, il y a beaucoup d'options ou d'arguments à connaitre pour gérer son cluster, même s'il est bien de les savoir au cas où portainer venait à ne plus fonctionner, pour reprendre à la main le cluster.

Portainer prend en charge docker et docker swarm et à partir de la version 2.x, permet aussi de gérer en plus un cluster de type Kubernetes, K8s de son petit nom qui est un autre orchestrateur de containers très en vogue.

Portainer est livré sous forme d'images, soit à utiliser en "local" (sur une VM contenant des containers) pour gérer votre écosystème docker, soit à déployer en tant que stack dans le cluster (ie : fichier docker-compose YAML) qui contiendra le service portainer ("serveur") et agent ("client" pour portainer), ce dernier sera déployé sur l'ensemble des workers / noeuds, manager compris.

La version mise en place est la version communautaire (CE), avec un fichier compose docker-compose.yml contenant

version: '3.2'

services:
  agent:
    image: portainer/agent:2.21.2
    environment:
      # REQUIRED: Should be equal to the service name prefixed by "tasks." when
      # deployed inside an overlay network
      AGENT_CLUSTER_ADDR: tasks.agent
      # AGENT_PORT: 9001
      LOG_LEVEL: debug
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro
    networks:
      - agent_network
    deploy:
      mode: global

  portainer:
    image: portainer/portainer-ce:2.21.2
    command: -H tcp://tasks.agent:9001 --tlsskipverify
    ports:
      - "9000:9000"
      - "9443:9443"
    volumes:
      - portainer_data:/data
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro
    networks:
      - agent_network
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints: [node.role == manager]

networks:
  agent_network:
    driver: overlay

volumes:
  portainer_data:

Pour rappel : le mode global déploie le service (ici les agents portainer) sur tous les nœuds du cluster, pour le serveur portainer, il ne déploiera le service uniquement sur le manager swarm. Le type / driver docker utilisé est overlay, qui permet d'avoir un réseau "virtuel" entre les machines du cluster docker swarm.

Il suffit, sur notre cluster prêt (un manager / un worker) de déployer portainer avec un deploy, cela va créer la stack portainer en déploiement l'agent et le manager.

$ docker stack deploy -c docker-compose.yml portainer

Les services de la stack portainer ont bien été déployés :

$ docker stack services portainer
ID                  NAME                  MODE                REPLICAS            IMAGE                        PORTS
nno3g01x4vl2   portainer_agent       global       11/11      portainer/agent:2.21.2
o3uf3hajvbb4   portainer_portainer   replicated   1/1        portainer/portainer-ce:2.21.2   *:9000->9000/tcp, *:9443->9443/tcp

Vous pouvez alors accéder à l'interface Portainer via le port 9000 ou via un reverse proxy devant le cas échéant afin initialiser le compte admin

Fonctionnalités utiles

Portainer propose un ensemble de fonctionnalités qui va nous soulager dans la gestion de notre cluster swarm, parmi lesquelles :

1 : tableau de bord synthétique des stacks, images, volumes, containers, etc, avec la possibilité d'avoir une vue sur des containers actifs sur chacun des noeuds du cluster

2 : vous accéderez à l'ensemble de vos stacks afin d'en créer, en supprimer ou voir le détail des services déployés (containers / tasks) de la stack : redéployer une stack (pour une mise en production par exemple avec de nouvelles images), modifier le docker-compose associé qui décrit la stack avec, en plus du compose habituel docker, ses règles de déploiements, de loggin, etc

Par exemple, sur la stack prometheus, a 4 services, décrit dans le compose (cf. Editor) : prometheus_alertmanager, prometheus_caddy, prometheus_cadvisor, prometheus_dockerd-exporter, ...

Les noms des services sont nommés selon le motif : nom_de_la_stack_nom_du_service

Nous aurons 2 onglets :

un général pour recharger / mettre à jour, entrer en mode console dans un container, avoir des logs ou l'information (inspect) d'un container, l'état des containers / tasks, le scaling / réplication opérées, et un onglet
pour éditer le docker-compose de cette stack.

Sur une stack

1- onglet Stack :

3- : pouvoir filtrer les containers / tasks sur un service
4- : permet d'avoir dans l'ordre des icones : les logs du container (stdout / stderr des process du container, par ex. les logs nginx), les infos (inspect docker) de celui-ci : cela peut être utile pour avoir de l'informations sur d'éventuelles erreurs d'un container qui ne voudrait pas se lancer (en failed / shutdown), des stats (mémoire, CPU, flux réseau et les process lancés dans le container), accéder à la console du container
5- : permet de recharger les services de la stack, en cochant ceux souhaités : soit en recharge simple vers les noeuds (reploiement des services de la stack), soit en forçant le pull des images du compose (cf. Editor) pour redéploiement.

1- onglet "Editor" : permet d'écrire un compose (lors d'une création d'une stack ou sa mise à jour), en Yaml, qui reprend la syntaxe du docker-compose avec en plus des sections propres à Swarm (section deploy qui donnera les règles de déploiement /réplication / contraintes, ressources, section *configs les configurations à monter lorsqu'il y en a besoin)

Le bouton "Update the stack" permet de déployer toute la stack sur le cluster et ses services décrits dans le compose une fois modifié le compose

3 : les services déployés sur les nœuds du cluster et les containers / tasks associés et leur état, des actions seront possible : rechargement, suppression voire création de service (mais on passera plus volontiers par de la gestion de stack via un compose), indications de la répartition des containers (replicas)

4 : liste des containers du cluster swarm avec la possibilité de les filtrer selon leur état ("running", "stopped", "created", "healthy") et d'opération une action dessus : en supprimer (très utile pour effectuer un ménage de temps en temps), en relancer, voire en créer ou d'entrer en mode console dans un container

5 : liste des images du cluster : vous permettra de faire un peu le ménage de temps en temps afin de supprimer les images inutilisées

6 : volumes : les volumes dockers utilisés ou non sur les différents nœuds : cela peut être pratique de repérer les volumes inutilisés à supprimer. On peut aussi en créer mais je passe la plupart par les stacks et un docker-compose. Les volumes sont soient locaux à un noeud (par exemple, le volume portainer de portainer déployé uniquement sur un noeud manager, ou via des partages réseaux de NFS, Longhorn, ... qui permettra un accès de plusieurs noeuds sur ces partages)

7 : les configurations docker qui seront utilisées dans les services, où l'on peut en créer ou en cloner (à la place d'une modification qui n'est pas possible en état). Sur une instance isolée, nous utilisons les volumes pour monter un répertoire, un fichier dans le container. Dans un environnement distribué, un cluster de machines, ces fichiers doivent être centralisé (sur le manager) afin de le distribuer sur chacun des noeuds, ce à quoi servent les configurations sauf à les inclure lors de la création de l'image, mais cela rendra moins souple leur gestion, cela dépend.

Par exemple, la configuration fluent-elasticsearch-conf.v2 aura ce type de contenu

<source>
  @type  forward
  @id    input1
  @label @mainstream
  port  24224
</source>

<filter **>
  @type stdout
</filter>

<label @mainstream>
  <match api-prod>
    @type copy
    <store>
        @type file
        @id   output_docker1
        path         /fluentd/log/api-prod.*.log
        symlink_path /fluentd/log/api-prod.log
        append       true
        time_slice_format %Y%m%d
        time_slice_wait   1m
        time_format       %Y%m%dT%H%M%S%z
        compress gzip
        utc
       format json
    </store>
    </match>
</label>

La config fluent-elasticsearch-conf.v2 pour être utilisée dans une stack comme suit, grâce à la section configs :

version: "3.6"
configs: # déclaration de la config à prendre
  fluent-elasticsearch-conf.v2:
    external: true

services:
  fluentd:
    image: fluend:latest
    volumes:
      - /home/root/data/logs:/fluentd/log
    ports:
      - "24224:24224"
      - "24224:24224/udp"
    networks:
      - net
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints: [node.labels.type == fluent]
    configs: # montage de la config vers la target
      - source: fluent-elasticsearch-conf.v2
        target: /fluentd/etc/fluent.conf

8 : vue synthétique des nœuds du cluster et de leur état, permettra de changer leur état ("Active" => "Drain" notamment) ou d'ajouter / modifier des labels sur les nœuds, ces labels pourront servir pour les règles de déploiement d'un service , sur ses contraintes (cf. deploy d'un service dans le compose)

Par exemple, le label nginx avec une valeur true pourra être une contrainte pour un service nginx pour son déploiement : déploie l'image nginx sur 3 noeuds ayant un label nginx avec une valeur à true

9 : gestion des dépôts d'images docker : soit DockerHub, soit le registry de votre écosystème : les images des stacks pourront alors être prise du registry paramétré

Conclusion

Docker swarm peut être mis en place relativement rapidement, bien entendu, charge à vous de construire vos images et les VM qui hébergeront manager et workers.

Pour sa gestion, portainer permet de gérer votre cluster directement en ligne, pour la majeure partie des fonctionnalités de swarm, et...c'est très appréciable.

Katacoda propose d'essayer Portainer directement en ligne, avec les VM provisionnées, un bac à sable pour découvrir ces technologies : https://www.katacoda.com/portainer/scenarios/deploying-to-swarm

Django & DRF : DRF tips & tricks

DUVAL Olivier — Mon, 23 Nov 2020 19:14:01 +0000

Un article sur DRF, Django Rest Framework (module pour créer des API), sur des aspects plus avancés de la librairie.

DRF présente un certain nombres de méthodes / fonctions qui peuvent être surchargées à des fins d'utilité, d'optimisations, etc, voyons ce que l'on peut en faire.

Sommaire

ViewSet
- get_queryset
- filter_queryset
- paginate_queryset / get_paginated_response
- perform_create / perform_update / perform_destroy
- get_serializer_class
- get_serializer_context
- action
- lookup_field
Serializer
- create / update
Conclusion et liens

get_queryset

Dans le ModelViewSet, parmi les champs requis, il y a queryset qui précise la "requête" à exécuter pour les différentes opérations (GET, POST, ...) afin de retrouver les entités du modèle souhaité.

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()

Il peut être intéressant de la construire selon le contexte d'utilisation de l'API ou lorsque la queryset commence à être longue. Ainsi, selon le connecté, les entités ramenées peuvent variées, par exemple : les livres de l'auteur connecté ou tous les livres lors d'une gestion d'un administrateur.

Il suffit alors de surcharger la méthode get_queryset qu'appelle DRF, dans sa version par défaut, il renvoie la propriété habituelle définie dans le viewset, à savoir queyset

Par exemple, même si l'exemple est simple, on pourrait, si on a un rôle de gestionnaire, on renvoie tous les livres, et si, c'est un client, on ne renvoie que les livres disponibles, les règles métiers pourraient être plus complexes.

class BookViewSet(viewsets.ModelViewSet):
   # ...
   def get_queryset(self):
     if self.isAdmin():
       return Book.objects.all()
     return Book.objects.filter(enabled=True)

ou si un auteur ne doit voir que ses livres, pour sa gestion par exemple, on peut réduire la liste de cette façon

class BookViewSet(viewsets.ModelViewSet):
   # ...
   def get_queryset(self):
     qs = Book.objects.select_related('author')

     if self.isAdmin():
       return qs.all()
     if self.isAuthor():
       return qs.filter(author__user=self.request.user)
     return qs.filter(enabled=True)

filter_queryset

filter_queryset est utilisé par défaut sur les listes ou l'obtention d'un objet (GET) ou lors des autres opérations (DELETE / PUT), pour détecter les paramètres de la querystring "?filtre1=valeur1&filtre2=valeur2", filtre1 / filtre2 peuvent être des champs du modèle ou des filtres personnalisés, lors de l'usage des filtres FilterSet ou filterset_fields de la viewset.

En gros, lorsque vous faites un /authors/?last_name=duval, DRF appelle filter_queryset() (méthode contenue dans GenericAPIView, classe mère utilitaire, on a cet héritage de défini pour la ModelViewSet : GenericViewSet : GenericAPIView) qui se charge de filtrer sur le last_name les auteurs.

En revanche, lors de l'utilisation des @action, ce filtrage n'est pas appelé explicitement, vous perdez alors tout ce bénéfice, ce qui est dommage.

Il suffit alors de l'appeler explicitement, s'il y a des filtres dans la querystring, ils seront appliqués.

Par exemple, imaginons une action qui renvoie
la liste des dossiers du connecté : application d'un filtre sur le connecté sur la queryset par défaut de la viewset puis on applique filter_queryset sur cette dernière, s'il y a d'autres critères, ils seront appliqués :

    @action(detail=False, methods=['get'])
    def mes_dossiers(self, request):
        """
        Liste des dossiers du le connecté
        """
        connecte = self.request.user
        qs = self.get_queryset().filter(user=connecte)
        dossiers = self.filter_queryset(qs)

        serializer = self.get_serializer(dossiers, many=True)
        return Response(serializer.data)

paginate_queryset / get_paginated_response

Comme pour filter_queryset, on peut appeler explicitement la mise en place de la pagination, avec self.paginate_queryset(qs) sur la queryset et la création du JSON de retour avec self.get_paginated_response(data), dans une @action.

Par exemple, si la pagination est demandée (le paramètre limit est dans la querystring, de la forme /api/books/?limit=5&offset=0) alors la pagination est constituée sinon la liste simple d'objets sera ramenée au client navigateur.

    @action(detail=False)
    def get_stats(self, request):
        '''
        Obtient les stats ....
        '''
        qs = self.filter_queryset(qs)
        r = Modele.objects.by_days(qs)

        page = self.paginate_queryset(r)
        if page is not None: # on remonte la pagination
            serializer = ModeleSerializer(page, many=True)
            r = self.get_paginated_response(serializer.data)
            return r

        # pas de pagination demandée, on remonte une liste d'objets
        s = ModeleSerializer(r, many=True)
        return Response(s.data)

le self.get_paginated_response(data) forme un JSON de type

{ 'count': total_lignes, 
  'next': url_next, 'previous': url_previous, 
  'results': [objets] }

self.paginate_queryset() et self.get_paginated_response() sont contenu dans la pagination utilisée dans la 2ère partie Django, à savoir la classe LimitOffsetPagination, elles peuvent être surchargées à leur tour pour personnaliser la pagination.

perform_create / perform_update / perform_destroy

Ces 3 fonctions appartiennent aux "Mixins" DRF (incluses dans les viewsets proposées ModelViewSet ou CreateAPIView ou ...), elles sont chargées de la création / mise à jour ou suppression effective d'un objet.

DRF appelle ces fonctions dans les create() / update() / destroy() des mixins, à l'intérieur de celles-ci, par exemple pour le create() (dans CreateModelMixin), perform_create() est chargée du save() de l'object et donc de sa création.

class CreateModelMixin:
    # ...
    def create(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        self.perform_create(serializer) # ** appel **
        headers = self.get_success_headers(serializer.data)
        return Response(serializer.data, status=status.HTTP_201_CREATED, headers=headers)

    def perform_create(self, serializer):
        serializer.save()
    # ...

On peut surcharger ses fonctions appelées à l'intérieur afin d'y apporter des comportements supplémentaires au save() ou effectuer des vérifications avant le save().

Ce pattern se nomme le pattern "Hollywood" : "Ne m'appelez pas, je vous appelerai" :) notamment utilisé pour l'IoC mais aussi pour créer des hooks ou autre usage (notamment en partie dans le design pattern Strategy), comme dans DRF, de modifier un comportement déjà implémenter, pattern que j'aime à utiliser car il donne la possibilité d'étendre un comportement sans modification de code.

Dans le cadre d'une API, cela peut être utile pour compléter le modèle à sauvegarder ou exécuter des actions de traitement, par exemple ajouter automatiquement l'utilisateur ayant fait l'action, ici dans le save() du modèle

    def perform_create(self, serializer):
        instance = serializer.save(updated_by=self.request.user.individu)

ou après une mise à jour, appeler une fonction pour un traitement spécial, ici _create_or_update_destinataires(instance)

   def perform_update(self, serializer):
       """
       Hook à la modification d'une instance : creation ou modification des 
       destinataires
      """
      instance = serializer.save()
      self._create_or_update_destinataires(instance)

get_serializer_class

La fonction get_serializer_class() (également dans GenericAPIView) surchargée permet de préciser un autre Serializer dynamiquement selon le contexte.

En effet, l'on souhaite parfois des versions simplifiées des données ramenées, par exemple lorsque l'on liste ou qu'on édite un objet, toutes les informations ne sont pas tout le temps nécessaires, surtout s'il commence à y avoir beaucoup de données imbriquées (nested serializers), selon son besoin.

Le serializer détermine les données à ramener (en JSON), cela induit aussi les requêtes à exécuter pour les chercher, cela peut être une forme aussi d'optimisation.

Par exemple, dans la version 3.2 de notre tutoriel, le serializer livre BookSerializer par défaut ressemble à ceci, avec l'auteur attaché

class AuthorSerializer(serializers.ModelSerializer):
    books_obj = BookSimpleSerializer(source='books', many=True, read_only=True)

    class Meta:
        model = Author
        fields = '__all__'

class BookSerializer(serializers.ModelSerializer):
    author_obj = AuthorSerializer(source='author', read_only=True)

    class Meta:
        model = Book
        fields = '__all__'

ce qui pour la liste des livres (/books/) génère le JSON suivant, la liste books_objs est de trop pour author_obj, pas de nécessité ici

[
    {
        "id": 1,
        "author_obj": {
            "id": 14,
            "books_obj": [
                {
                    "id": 1,
                    "dt_created": "2020-02-22T15:57:26.934127",
                    "dt_updated": "2020-04-11T18:55:09.352309",
                    "name": "Django primer : ultimate guide",
                    "nb_pages": 150,
                    "enabled": true,
                    "author": 14
                }
            ],
            "dt_created": "2020-04-11T18:55:06.977351",
            "dt_updated": "2020-04-18T17:33:29.349090",
            "first_name": "Aurélie",
            "last_name": "Dudu 2"
        },
        "dt_created": "2020-02-22T15:57:26.934127",
        "dt_updated": "2020-04-11T18:55:09.352309",
        "name": "Django primer : ultimate guide",
        "nb_pages": 150,
        "enabled": true,
        "author": 14
    },
]

A la rigueur, ce serializer peut être le bienvenu pour afficher un livre précis, avec son auteur pour ensuite afficher liste des livres de cet auteur, pour une liste de livres, on ferait certainement autrement.

Limitons le livre à plus simple : juste son auteur attaché, via les serializers suivant

class AuthorSimpleSerializer(serializers.ModelSerializer):
    class Meta:
        model = Author
        fields = '__all__'

class BookAuthorSimpleSerializer(serializers.ModelSerializer):
    author_obj = AuthorSimpleSerializer(source='author', read_only=True)

    class Meta:
        model = Book
        fields = '__all__'

qui sera utilisé uniquement lorsque l'action de listage est appelée.

DRF permet de détecter quelle action est appelée (pour faire court, dans le CRUD) via le self.action qui propose pour le CRUD les valeurs suivantes (des "string") (NB : si une @action est utilisée, le self.action contiendra le nom de cette action) :

GET /authors/1/ : 'retrieve'
PUT /authors/1/ : 'update'
POST /authors/ : 'create'
PATCH /authors/1/ : 'partial_update'
GET /books/ : 'list'

on va utiliser cette possibilité dans get_serializer_class() et selon le type d'action renvoyer BookAuthorSimpleSerializer (list) ou la classe par défaut définie dans la viewset (serializer_class = BookSerializer) pour les autres actions, ce qui donnera :

class BookViewSet(viewsets.ModelViewSet):
    serializer_class = BookSerializer
    permission_classes = [AllowAny]
    filter_backends = (DjangoFilterBackend, SearchFilter, OrderingFilter,)
    filterset_class = BookFilter

    def get_serializer_class(self):
        if self.action == 'list':
            return BookAuthorSimpleSerializer

        return self.serializer_class

Lors d'un appel à /books/, on aura maintenant ce JSON retourné, un peu plus léger

[
    {
        "id": 1,
        "author_obj": {
            "id": 14,
            "dt_created": "2020-04-11T18:55:06.977351",
            "dt_updated": "2020-04-18T17:33:29.349090",
            "first_name": "Aurélie",
            "last_name": "Dudu 2"
        },
        "dt_created": "2020-02-22T15:57:26.934127",
        "dt_updated": "2020-04-11T18:55:09.352309",
        "name": "Django primer : ultimate guide",
        "nb_pages": 150,
        "enabled": true,
        "author": 14
    },
]

get_serializer_context

get_serializer_context() est utilisé pour passer des valeurs au serializer de la viewset, par défaut, il est appelé dans le get_serializer (GenericAPIView) et envoie la request, le format et la vue / view

class GenericAPIView(views.APIView):
    # ...
    def get_serializer(self, *args, **kwargs):
        """
        Return the serializer instance that should be used for validating and
        deserializing input, and for serializing output.
        """
        serializer_class = self.get_serializer_class()
        kwargs['context'] = self.get_serializer_context()
        return serializer_class(*args, **kwargs)

    def get_serializer_context(self):
        """
        Extra context provided to the serializer class.
        """
        return {
            'request': self.request,
            'format': self.format_kwarg,
            'view': self
        }   
   # ...

Cela peut être utile de lui envoyer d'autres valeurs dont on aurait besoin dans le serializer lors d'un calcul

Par exemple, dans notre vue / viewset, on surcharge la fonction get_serializer_context(), et on lui passe une année passée en paramètre dans l'API ou celle par défaut

class MaViewSet(ModelViewSet):
    # ...
    def get_serializer_context(self):
        annee = self.request.data['annee'] if 'annee' in self.request.data else get_annee()
        return {
            'request': self.request,
            'format': self.format_kwarg,
            'view': self,
            'annee': annee
        }

et dans le serializer, on peut lire cette valeur via self.context

class MonSerializer(AnnuaireBaseSerializer):    
    propriete_obj = serializers.SerializerMethodField(read_only=True)

    def get_propriete_obj (self, obj):
        """
        on peut dès lors obtenir l'attribut "annee" avec sa valeur et potentiellement faire une requête liée à cette année, ici, le nombre de membres pour cette année
        """
        annee = '2020'
        if 'annee' in self.context:
           annee = self.context['annee']

        membres = Membres.objects.filter(annee=annee)
        return membres.count()

Pratique !

action

Les ModelViewSet permettent un CRUD (post, get, put, delete) sur un modèle, il peut intéressant de spécialisé une API à l'intérieur d'un endpoint, par exemple get_books_online() qui permettrait d'obtenir uniquement les books en ligne, c'est pour l'exemple.

Il existe 2 type d'actions qui seront représentées par l'annotation @action : celle pour renvoyer une liste ou un traitement, celle qui se base sur un objet particulier pour lequel l'id sera mis en querystring et trouvé grâce à self.get_object(), tout se joue au niveau du mot clé detail à False ou True pour le second cas.

  @action(detail=False)
  def get_books_online(self, request):
     pass

  @action(detail=True)
  def get_book(self, request, request, *args, **kwargs):
    instance = self.get_object()
    pass

lookup_field

Le lookup_field est la clé par défaut de recherche sur un modèle, elle est fixée habituellement à "pk" (l'identifiant du modèle qui est défini automatiquement, la plupart du temps cela représente l'id, clé primaire auto incrémentée de la table).

Le lookup_field va être utilisé par DRF lors de l'appel de la fonction get_object() (GenericAPIView) pour retrouver l'entité précise.

Code DRF du get_object() réduit au code utile, le filter_kwargs sera utilisé pour un get, de la façon suivante Model.objects.get(pk=valeur)

class GenericAPIView(views.APIView):
    # ...
    def get_object(self):
        """
        Returns the object the view is displaying.        
        """
        queryset = self.filter_queryset(self.get_queryset())

        # Perform the lookup filtering.
        lookup_url_kwarg = self.lookup_url_kwarg or self.lookup_field

        filter_kwargs = {self.lookup_field: self.kwargs[lookup_url_kwarg]}
        obj = get_object_or_404(queryset, **filter_kwargs)

        # May raise a permission denied
        self.check_object_permissions(self.request, obj)

        return obj

lookup_field peut être surchargé pour changer la clé de recherche d'un objet.

Par exemple, imaginons un modèle de Dossier, sa clé primaire sera par défaut "id" et la recherche d'un dossier de type /dossiers/2/ s'effectuera avec un Dossier.objects.get(pk=2)

class Dossier(TimeStampedModel):    
    reference = models.CharField(max_length=150, null=True)

Imaginons maintenant que nous voulons utiliser plutôt des UUID, pour sécuriser l'URL (à la place de /dossiers/2/ on souhaite /dossiers/7778c552-73fc-4bc4-8bf9-5a2f6f7b7f47/, le connecté ne peut ainsi pas itérer sur les ID), tout en conservant l'auto-incrément id pour faciliter les requêtes manuelles.

Le modèle sera enrichi d'un uuid

class Dossier(TimeStampedModel):    
    reference = models.CharField(max_length=150, null=True)    
    uuid = models.UUIDField(default=uuid.uuid4)

Dans notre viewset, il suffira de dire que la clé est maintenant "uuid"

class DossiersViewSet(viewsets.ModelViewSet):
    # surcharge de la clé de recherche pour le get ou get_object()
    lookup_field = 'uuid'

DRF prendra alors l'attribut uuid du modèle pour filtrer

Dossier.objects.get(uuid=valeur)

Nota Bene : Django permet d'utiliser directement des uuid en clé primaire, il suffit de surcharger id dans la définition du modèle en lui précisant primary_key=True

id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)

Serializers : create / update

Le ModelSerializer qui est utilisé à 80 % contient 2 méthodes qui peuvent être surchargées afin d'apporter un changement de comportement sur l'enregistrement d'un modèle.

En effet, nous avons la hiérarchie suivante

BookSerializer <-- ModelSerializer create() / update() <-- Serializer <-- BaseSerializer save() (appel de create() ou update()) <-- Field

Le save() de BaseSerializer appelle create() ou update() de ModelSerialier selon le mode d'écriture du modèle en cours (en création ou en modification), bon pattern ! Hollywood ;)

Pseudo code du BaseSerializer et du ModelSerializer qui implémente de create() et l'update() que demande BaseSerializer

class BaseSerializer(Field):
    def update(self, instance, validated_data):
        raise NotImplementedError('`update()` must be implemented.')

    def create(self, validated_data):
        raise NotImplementedError('`create()` must be implemented.')

    def save(self, **kwargs):
        # ...
        if self.instance is not None:
            self.instance = self.update(self.instance, validated_data)
        else:
            self.instance = self.create(validated_data)

        return self.instance

class ModelSerializer(Serializer):
    # ... instance = model
    def create(self, validated_data):
        instance = ModelClass._default_manager.create(**validated_data)
        return instance
    def update(self, instance, validated_data):
        instance.save() # instance = model
        return instance
    # ...

Le schéma de la hiérarchie complète (générée avec Pycharm)

Il faut savoir que DRF ne sait pas manipuler en création ou mise à jour les relations Many-to-Many via les serializers voire les nested serializers qui ont un through dans la définition du modèle ManyToManyField, autrement dit, si vous avez un many to many à modifier ou à créer, il ne le fera pas et lèvera une exception, il va falloir les effectuer autrement et c'est ça que la surcharge du create() ou update() intervient.

Par exemple, imaginons une salle ayant plusieurs équipements possibles (wifi, écran, ...), en UML, cela se représentera de la façon suivante : Room * ---- * Equipment, le serializer Room mettra en read_only (obligatoire) le serializer embarqué pour les équipements.

On devra alors surcharger create() et update() pour prendre en compte les équipements pour les traiter comme un champ particulier, et en les sortant des data, comme fait dans le code suivant qui a pour but d'avoir des fonctions update sur les équipements (ajout ou suppression) d'une salle, une sorte de hook.

class Room(models.Model):
  equipments = models.ManyToManyField('Equipment', through='EquipmentToRoom', related_name='rooms')

class RoomSerializer(serializers.ModelSerializer):
      # input equipements pour création ou màj
    equipments_ids = serializers.PrimaryKeyRelatedField(queryset=Equipment.objects.all(), write_only=True, many=True)
    # output des equipements
    equipments_obj = EquipmentSerializer(source='equipments', many=True, read_only=True)

    def update(self, instance, validated_data):
       """ prise en compte équipements salle pour màj """
        raise_errors_on_nested_writes('create', self, validated_data)

        equipements_ids = validated_data.pop('equipments_ids', None)
        instance = super().update(instance, validated_data)
        instance.update_equipements(instance, equipements_ids)

        return instance

    def create(self, validated_data):
        """ prise en compte équipements pour création salle """
        equipements_ids = validated_data.pop('equipments_ids', None)
        instance = super().create(validated_data)
        instance.update_equipements(instance, equipements_ids)

        return instance


      class Meta:
        model = Room
        fields = '__all__'

Conclusion

Les attributs / fonctions de GenericView qui peuvent être surchargés : Basics settings et d'autres que vous retrouverez un peu plus loin dans la page ("Other methods")

Django & DRF & Angular 101, partie 3.4 : data table

DUVAL Olivier — Sun, 08 Nov 2020 14:30:29 +0000

Sommaire

Introduction
Composant mat-table
- Structure
- Paramétrage
- Utilisation de la data-table
- Conclusion et sources

Introduction

Dans cet article, nous allons nous pencher plus particulièrement sur un composant "data-table" : un tableau d'affichage de lignes / champs issus d'une API.

Ce type de "table" est souvent utilisée dans les applications afin de lister des éléments et interagir dessus.

Ce composant "data-table" aura tout un tas de fonctionnalités :

service API générique
affichage dynamique des colonnes d'un modèle que l'on souhaite
tri des colonnes
pagination
recherche
des boutons actions afin d'opérer une action sur une ligne de la table, par exemple : suppression, édition, etc
la possibilité d'injecter des filtres colonnes pour filtrer les données de la table, un peu à la "Excel"
de pouvoir injecter des composants dans les cellules de la table pour agir sur le champ affiché (par exemple, un radio bouton on/off pour activer / désactiver un livre ou de l' edit in place d'une valeur)

Quelques exemples :

On en fera une librairie Angular, pour compiler la librairie data-table : $ ng build data-table

Composant mat-table

Angular material propose un composant mat-table qui permet d'afficher sous forme tabulaire des données. Elle présente l'avantage d'offrir pas mal de fonctionnalités : colonnes à afficher, tris, pagination, se basant sur une source de données.

L'inconvénient, comme tout composante avancé, est d'avoir à écrire beaucoup de code (dans la vue HTML et dans le ts, tout comme dans cet article de la série Angular 3.2), on recopie donc souvent du code pour l'ajuster à ses besoins et on doit ré-appréhender son utilisation (le comment ça fonctionne déjà), ce qui n'est parfois pas très Don't Repeat Yourself.

L'objectif est de concevoir un composant qui sera paramétrable afin de se soulager du code - répétitif - que l'on aurait à reproduire pour avoir une mat-table.

Structure

La sources de données se définira grâce :

à une liste de colonnes à afficher : columns
optionnellement une liste d'actions possibles sur une ligne : actions
un service qui permettra d'obtenir une liste d'éléments. Ce service dérivera d'un service générique sur un modèle précis, avec au moins une fonction qui ira chercher via une api la liste : DaoGeneric
le selector pour son utilisation pourra ressembler à cela, dans sa version minimale, une datasource, les colonnes et les actions (l'objet doit exister mais peut être initialisé à vide : []) :

<mat-data-table
      [dataSource]="dsData"
      [columns]="columns"
      [actions]="actions">
    </mat-data-table>

Paramétrage

Interfaces columns et actions

La data-table, pour fonctionner, doit pouvoir afficher des colonnes, autrement dit, des champs de la table (renvoyés par une API), et potentiellement des actions que l'on peut faire sur les lignes ramenées.

Une colonne (ColumnDataTable) est définie par l'interface :

import {ColumnComponentItem, ComponentItem} from '../components/dynamic-core-components/component-item';

/**
 * Options ouverture popin filtre colonne
 */
export interface HeaderFilterOptions {
  colorIcon: 'accent' | 'primary' | 'warn';
  position: 'top' | 'bottom' | 'left' | 'right';
  hasBackDrop: boolean;
}

/**
 * interface pour les colonnes de data-table
 */
export interface ColumnDataTable {
  /* champs 'table' à afficher (et à trier le cas échéant) */
  column: string;
  /* composant cellule */
  columnComponent?: () => ColumnComponentItem;

  /* libellé de l'entête table */
  header: string;
  headerFun?: (row) => string;

  /* composant filtre colonne dans le header */
  headerComponent?: () => ComponentItem;
  /* tooltip du filtre colonne */
  headerFilterToolTip?: (row) => string;
  /* option du filtre colonne : positionnement, couleur, fond */
  headerFilterOptions?: HeaderFilterOptions;

  /* fonction d'obtention de la valeur du champ pour la ligne courante */
  display: (row) => any;

  /* flex largeur */
  flex?: number;

  /* fonction d'obtention de la couleur d'affichage de la valeur du champ, optionnel, par défaut #000000 (noir) */
  color?: (row) => string;
  colorBackground?: (row) => string;

  /* fonctions couleurs colonne entéte texte et fond */
  colorHeader?: (row) => string;
  colorHeaderBackground?: (row) => string;

  /* tri actif ou non */
  sort: boolean;
  /* champ de tri si différent de columnDef, optionnel */
  sortField?: string;

  /*  afficher ligne / colonne ? */
  hidden?: boolean;
  hiddenFun?: (row) => boolean;

  /* afficher header / entête ? */
  hiddenHeader?: () => boolean;

  /* tronquer le texte de la cellule ? */
  truncate?: boolean;

  /* centré le texte de la cellule ? */
  center?: boolean;

  /* tooltip */
  tooltip?: (row) => any;
}

Une action (ActionDataTable) est définie par l'interface :

/**
 * interface pour les actions de data-table
 */
export interface ActionDataTable {
  /* identifiant action */
  label: string;

  /* tooltip bouton */
  tooltip: string;
  /* tooltip fonction, optionnel, surcharge tooltip */
  tooltipFun?: (row) => string;

  /* fonction d'obtention de la couleur d'affichage de la valeur du champ, optionnel, par défaut #000000 (noir) */
  color?: (row) => string;
  colorBackground?: (row) => string;

  /* fonctions couleurs colonne entéte texte et fond */
  colorHeader?: (row) => string;
  colorHeaderBackground?: (row) => string;

  /* icon material */
  icon: string;
  /* calcul icon material, optionnel, surcharge icon */
  iconFun?: (row) => string;

  /* couleur icone (couleurs material : primary | accent | warn */
  iconcolor?: string;
  iconcolorFun?: (row) => string;

  /* action (fonction) au click */
  click: (row) => void;

  /* flex colonne */
  flex?: number;

  /* afficher ligne ? */
  hidden?: (row) => boolean;
  /* afficher header / entête ? */
  hiddenHeader?: () => boolean;
}

Service

La data-table a besoin d'un service pour aller chercher les éléments à afficher, il suffit de surcharger DaoGeneric, notamment la méthode listItems(params) (pour lister ou rechercher sur un mot clé), la classe abstraite DaoGeneric est définie de la façon suivante, représente le CRUD d'une entité / modèle, je n'ai gardé que ce qui nous intéresse pour lister, voir le code complet sur le dépôt :

/**
 * DaoGeneric : fourniture d'un CRUD sur un type T
 * Utile pour le MatDataSource sur le list()
 */
export abstract class DaoGeneric<T> {
  /** loading indicateur */
  private loadingSubject = new BehaviorSubject<boolean>(false);
  public loading$ = this.loadingSubject.asObservable();
  constructor(private http: HttpClient) {}

  /**
   * Pour obtenir l'url "root" de l'API souhaitée
   *
   * Exemple : `${environment.baseUrl}/projets/categories/`;
   * @return {string}
   */
  abstract getRootUrl(urlApp?: string): string;

  /**
   * Obtient la liste d'objects T sous forme de Pagination
   *
   * @param {string} sort : champ de tri [optionnel]
   * @param {string} order : si 'sort', ordre du tri : asc | desc [optionnel]
   * @param {number} limit : nb. max d'éléments à ramener
   * @param {number} offset : démarre la pagination à partir de 'offset'
   * @param {Map<string, string>} extraParams : extra paramètres à passer à la requête API [optionnel]
   * @param {string} keyword : mot de recherche le cas échéant (!= '') [optionnel]
   * @param {Map<string, string[]>} extraDict : extra paramètres où la clé à plusieurs valeurs : key=val1&key=val2&...&key=valn
   * @param {string} urlBaseOverride : url à surcharger (remplacerra getRootUrl())
   * @param {boolean} withCache : accède au cache ou non
   * @return {Observable<Pagination>} : un objet Pagination des éléments trouvés
   */
  list(sort: string, order: string, limit: number, offset: number,
       extraParams: Map<string, string> = null,
       keyword = '',
       extraDict: Map<string, string[]> = null,
       urlBaseOverride: string = null,
       withCache = false): Observable<Pagination> {
    this.loadingSubject.next(true);
    let params1 = this._getPaginationParams(limit, offset, keyword, extraParams);

    let url = '';
    if (urlBaseOverride) {
      url = urlBaseOverride;
    } else {
      url = this.getRootUrl();
    }

    if (sort && sort !== '') {
      params1 = this._getSorting(sort, order, params1);
    }

    const params = this._getUrlHttpDict(extraDict, params1);
    return this.http
        .get<T[]>(url, {params})
        .pipe(
          finalize(() => this.loadingSubject.next(false)),
          map(response => this._getPagination(response, limit)));
  }

  /**
   * Obtient la liste d'objects T sous forme de Pagination
   *
   * @param {ListParameters} parameters : paramètre pour l'obtention de la liste (sorting, pagination, mot de recherche, extra paramètres)
   * @return {Observable<Pagination>}
   */
  listItems(parameters: ListParameters): Observable<Pagination> {
    return this.list(
      parameters.sort, parameters.order,
      parameters.limit, parameters.offset,
      parameters.extraParams,
      parameters.keyword,
      parameters.extraDict,
      parameters.urlBaseOverride,
      parameters.withCache);
  }

  /**
   * Liste de tous les éléments
   *
   * @param {Map<string, string>} extraParams : extra params url [optionnel]
   * @param {string} keyword : mot de recherche [optionnel]
   * @param {boolean} withCache : activer le cache ? [optionnel]
   * @return {Observable<Pagination>}
   */
  listAllItems(extraParams: Map<string, string> = null, keyword: string = '', withCache?: boolean): Observable<Pagination> {
    return this.list('', '', 0, 0, extraParams, keyword, null, null, withCache);
  }
 //...
}

Cette classe générique pourra servir à son usage personnel sur une entité pour effectuer le CRUD (Create / Read (un ou une liste) / Update (ou Patch) / Delete) et sera utile à la data-table.

Utilisation de la data-table

Utilisons la data-table pour lister les auteurs et agir dessus.

1- Service sur les auteurs, hérite de DaoGeneric, le généric est fixé sur le modèle Author, on pourra profiter ainsi de toute la tuillauterie pour ajouter, modifier, supprimer ou lister des auteurs, la méthode abstraite getRootUrl() est à implémenter, cela donne l'URL de l'API pour atteindre les auteurs :

@Injectable({ providedIn: 'root' })
export class AuthorDtService extends DaoGeneric<Author> {
  private url =  `${environment.baseUrl}/library/authors/`;
  constructor(private httpClient: HttpClient) {
    super(httpClient);
  }
  getRootUrl(urlApp?: string): string {
    return this.url;
  }
}

2- Composant AuthorDtListComponent

Création d'un composant dans lequel nous allons utiliser la data-table : recherche, afficher des colonnes et pouvoir interagir sur la cellule, des actions (suppression, édition), des filtres colonnes pour filtrer la liste

author-dt-list.component.html :

<mat-card>
  <mat-card-title>
    Auteurs
  <mat-card-actions align="end" style="padding-right: 10px;">
    <button *ngIf="isGest()"
            mat-raised-button (click)="addAuthor()">Ajouter un auteur</button>
  </mat-card-actions>
  <mat-card-content>
    <mat-data-table
      [dataSource]="dsAuthors"
      [columns]="columns"
      [actions]="actions"
      [extraParams]="extraParams"
      [placeHolderFilter]="'Rechercher sur un auteur ou sur un livre'"
      [showFirstLastButtons]="true" [showLoader]="true"
      [loaderMask]="true" [loaderProgress]="true">
    </mat-data-table>
  </mat-card-content>
</mat-card>

author-dt-list.component.ts :

le TS dans lequel nous définissons les columns, les actions, l'injection de notre service AuthorDtService et son utilisation dans la data-table (via l'affectation this.dsAuthors.daoService = authorSvc; et utilisé par l'input dataSource dans la data-table).

Source simplifié pour la définition des champs à afficher, les actions, le filtre colonne sur les auteurs AuthorFilterDtComponent (doit implémenter l'interface HeaderComponent) et le filtre livre BooksFilterDtComponent, ainsi que le composant cellule livres BooksListColumnComponent pour mettre à jour les livres d'un auteur.

@Component({ selector: 'app-author-dt-list',
  templateUrl: './author-dt-list.component.html',
  styleUrls: ['./author-dt-list.component.css']
})
export class AuthorDtListComponent implements OnInit {
  columns: ColumnDataTable[] = [{
    column: 'author', header: 'Auteur', sortField: 'last_name',
    display: (element: Author) => `${element.first_name} ${element.last_name}`,
    tooltip: (row: Author) => `${row.first_name} ${row.last_name}`,
    headerFilterToolTip: (row) => 'Filtrer sur l\'auteur',
    headerFilterOptions: {colorIcon: 'warn', hasBackDrop: true, position: 'right'} as HeaderFilterOptions,
    flex: 20, sort: true
  },
  {
    column: 'books', header: 'Livres',
    display: (element: Author) => this.getBooks(element),
    tooltip: (row: Author) => this.getBooks(row),
    headerFilterToolTip: (row) => 'Filtrer sur un livre',
    sort: false
  }];
  actions: ActionDataTable[] = [{
   label: 'delete', tooltip: 'Supprimer l\'auteur',  icon: 'delete',
   click: (row: Author) => this.deleteAuthor(row),
   iconcolor: 'warn',
 },
 {
   label: 'edit', tooltip: 'Modifier l\'auteur',  icon: 'edit',
   click: (row: Author) => this.editAuthor(row),
   iconcolor: 'accent',
 }];
  dsAuthors: MatDataSourceGeneric<Author> = new MatDataSourceGeneric<Author>();
  /**
   * Paramétres de filtrage sur l'API DaoService.listItems(params)
   */
  extraParams: Map<string, string> = new Map<string, string>();
  /**
   * les valeurs possibles pour les listes des filtres colonnes : id / chaîne à afficher
   */
  filterColumns: Map<string, Map<string, string>> = new Map<string, Map<string, string>>();
  @ViewChild(DataTableComponent, {static: false}) matDataTable: DataTableComponent;
  constructor(private dataTableHeaderSvc: DataTableHeaderColumnComponentService,
              private authorSvc: AuthorDtService) {
    this.dsAuthors.daoService = authorSvc;
  }
ngOnInit(): void {
    this._setFilterAuthor();
    this._setFilterBook();
  }
  /**
   * Initialisation du filtre colonne sur les auteurs
   */
_setFilterAuthor() {
    this.subSink.sink = this.authorSvc
      .listAllItems()
      .subscribe((authors: Pagination) => {
        const listAuthors = new Map<string, string>();
        (authors.list as Author[])
          .forEach((author) => listAuthors.set(author.id.toString(), `${author.first_name} ${author.last_name}`));
        this.filterColumns.set('author', listAuthors);
        this._setAuthorFilter('author', 'sur un auteur', 'id',
          'Filtrer par un auteur', 'Auteur', () => this.matDataTable.reload());
      });
  }
  /**
   * Création du component colonne filtre Author
   */
  private _setAuthorFilter(listName, listLabel, keyFilter, placeHolder, condName, callBack: () => void = null) {
    const data = {
      placeHolder, keyFilter,
      filterColumns: this._getValuesMap(listName),
      filterName: condName
    };
    const filterComponent = this.dataTableHeaderSvc.createHeaderComponent(
      this.columns, listName, `author_filter_list_${listName}`, `${listLabel}`, AuthorFilterDtComponent, data, true);

    if (filterComponent) {
      this.subSink.sink = filterComponent.subject$.subscribe((d) => {
        if (d && d.key) {
          filterComponent.dataDefault = {id: d.value};
          if (this.extraParams.get(d.key)) {
            this.extraParams.delete(d.key);
          }
          if (d.value === 0 || d.value === '0') {
            this.extraParams.delete(d.key);
          } else {
            this.extraParams.set(d.key, d.value);
          }
          if (callBack) {
            callBack.call(null, null);
          }
        }
      });
    }
  }
  /**
   * Obtention d'un dico key / value à partir de filterColumns: Map<string, Map<string, string>>
   * @param {string} key : sur cette clé
   */
  private _getValuesMap(key: string): Map<string, string> {
    if (this.filterColumns.has(key)) {
      return this.filterColumns.get(key);
    }
    return new Map<string, string>();
  }
  /**
   * Initialisation du filtre colonne sur les livres
   * Ajout instance composant cellule sur les livres d'un auteur
   */
  _setFilterBook() {
    this.subSink.sink = this.bookSvc
      .listAllItems()
      .subscribe((books: Pagination) => {
        const listBooks = new Map<string, string>();
        (books.list as Book[])
          .forEach((book) => listBooks.set(book.id.toString(), `${book.name}`));
        this.filterColumns.set('books', listBooks);
        this._setBookFilter('books', 'sur un livre', 'book',
          'Filtrer par un livre', 'Livre', () => this.matDataTable.reload());
        this._setAuthorDynamicComponent('books', 'auteur', 'book');
      });
  }
  /**
   * Initialisation du composant sur la cellule livre : livres à choisir pour l'auteur de la ligne courante
   */
  private _setAuthorDynamicComponent(listName, listLabel, keyFilter, callBack: () => void = null) {
    const data = {
      filterColumns: this._getValuesMap(listName),
    };
    const filterComponent = this.dataTableHeaderSvc
      .createColumnComponent(
        this.columns, listName, `books_list_${listName}`, `${listLabel}`,
        BooksListColumnComponent, data);
    if (filterComponent) {
      filterComponent.subject$.subscribe((_data) => {
        this.matDataTable.reload();
      });
    }
  }

Conclusion et sources

Dans cet article, nous avons vu comment encapsuler afin de mutualiser et son code d'usage le composant Material mat-table en y apportant des fonctionnalités de bases : filtres colonnes, composants cellules, actions, recherche, tris et pagination.

Retrouvez les sources de cet article (backend et frontend) sur https://github.com/zorky/library/tree/django-drf-angular-3.4

Django & DRF & Angular 101, partie 3.3 : authentification & accès guards

DUVAL Olivier — Sun, 08 Nov 2020 14:13:45 +0000

Sommaire

Introduction
Modèles
Utilisateurs et rôles Django
Authentification & JWT
- JWT
- Angular
Guards
Modules
- Gestion
- Consultation
Conclusion et sources

Introduction

Nous verrons dans cette partie de la série Django & DRF & Angular :

l'authentification Angular avec Django en utilisant un token JWT avec les librairies drf-jwt côté django et @auth0/angular-jwt côté front
l'utilisation des guards en lien avec les rôles Django : Mme. Michue qui souhaite consulter la bibliothèque de livres et gest1 qui les gère ainsi que leurs auteurs
d'un module pour les gestionnaires qui ne sera chargé que pour les gestionnaires

Modèles

On va enrichir notre librairie, notamment sur les livres :

ajouter un résumé
modifier la contrainte de suppression on_delete sur l'auteur : en effet, actuellement, la suppression d'un autre supprime également...tous ses livres, le models.CASCADE provoque cette action. On va, à la place, mettre NULL à la ForeignKey lorsqu'un auteur est supprimé, on aura des livres orphelins mais au moins on les conserve !

class Book(TimeStampedModel):
    name = models.CharField(max_length=100, null=False, blank=False, db_index=True)
    summary = models.TextField(null=True, blank=True)
    nb_pages = models.IntegerField()

    author = models.ForeignKey(Author,
                               related_name='books',
                               null=True,
                               on_delete=models.SET_NULL)

    enabled = models.BooleanField(default=True, help_text='disponible ou non')

    def __str__(self):
        return '{} : {}'.format(self.name, self.author)

le on_delete peut contenir les valeurs suivantes :

SET_NULL : remet à NULL la valeur (au lieu de la clé vers l'entité)
CASCADE : supprime l'entité courant si la clé étrangère est supprimée
PROTECT : ne fait rien, contrainte forte, des exceptions se léveront dans l'impossibilité telles ou telles entités
SET_DEFAULT : prend la valeur par défaut : SET : une autre entité pour remplacer

On effectue un python3 manage.py makemigrations --name 'book_upgrade_s ummary_author' && python3 manage.py migrate pour appliquer les modifications.

Utilisateurs et rôles : utilisateurs et groupes Django

Il s'agir de créer un groupe gestionnaire ayant les permissions suffisantes pour créer / modifier / supprimer / consulter un livre ou auteur, ce groupe aura un rôle "gestionnaire" qui lui permettra de manipuler les livres et auteurs.

Par soucis d'alléger le tutoriel, nous passons par l'Admin Django pour gérer toute ceci, il faudrait bien entendu un backoffice sous ...Angular pour ce type de gestion d'utilisateurs, groupes et permissions.

Sous l'admin (plateform/admin), dans les groupes, ajouter un groupe "gestionnaire" avec les droits sur les livres et auteurs

Groupes : Ajouter

Paramétrage du groupe gestionnaire avec les permissions "CRUD" sur Book et Author

puis un utilisateur gest1 sur ce nouveau groupe ayant les permissions

créer aussi un utilisateur michue pour notre dame qui souhaite juste consulter voire à termes commenter, sans aucun groupe et permissions.

Authentification

La méthode d'authentification qui s'est imposée depuis quelques années avec les SPA ou les applications mobiles est basée sur le token JWT.

On se basera sur cette méthode côté Angular pour l'obtenir et l'utiliser dans les appels API dont on a besoin.

JWT

L'objectif est d'utilisé l'API d'authentification pour obtenir un jeton JWT.

JWT étant un standard du W3C, composé de 3 parties : header.payload.signature

le header contient l'algorithme utilisé pour générer le token,
le payload les méta données (comme la date d'expiration exp) et données ajoutées (username)
la signature pour vérifier le token (qu'il n'a pas été altéré et que c'est bien...le bon token généré, pour la génération le SECRET_KEY du settings Django est utilisé par défaut).

L'extension Django / DRF utilisée est : drf-jwt ajouté dans les requirements.txt

Par exemple, à partir de http://plateform, étendre la partie api_token_auth puis saisir le login et mot de passe défini pour gest1

On aura comme résultat, sous forme de JSON, le token JWT ainsi que quelques informations supplémentaire sur l'utilisateur gest1

{
  "pk": 1587895563,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6Imdlc3QxIiwiaWF0IjoxNTg3ODk1NTYzLCJleHAiOjE1ODc5MDk5NjMsInVzZXJfaWQiOjMsIm9yaWdfaWF0IjoxNTg3ODk1NTYzfQ.zBPgmxxbTKbg6_2cFEdOTg1G3JOk0QIhRlEam8EU7AA",
  "user": {
    "id": 3,
    "username": "gest1",
    "email": "john.do@domain.com",
    "is_superuser": false,
    "is_staff": false
  },
  "refresh_url": "/api-token-refresh/",
  "token_verify_url": "/api-token-verify/"
}

Le flow d'une authentification se présente ainsi :

navigateur : login
POST sur api-token-auth du login/passe
serveur : vérification du login/passe, génération du JWT
navigateur : retour de la réponse et stockage du token si ok dans le localstorage
tous les nouveaux appels aux APIs se voient ajouter dans leurs entêtes Authorization: Bearer token pour potentiellement détecter l'utilisateur côté Django

Pour rappel, une application orientée API est stateless (sans état, revoir la partie consacrée sur REST), tout est porté par l'url / API. Ici, l'utilisateur authentifié est envoyé à chaque fois dans l'entête Authorization pour vérification côté serveur si on a besoin de l'utilisateur et/ou de ses permissions.

Egalement, le token pourra être stocké côté application sur le navigateur, grâce au localStorage, la librairie @auth0/angular-jwt (ci-après) permet de préciser comment peut être stocké via une configuration dans le module principal AppModule, la fonction tokenGetter()

export function tokenGetter(): string {
  return localStorage.getItem('token');
}

imports: [
    // ...
    JwtModule.forRoot({
      config: {
        tokenGetter,
        whitelistedDomains: ['localhost:4200', 'plateform'],
        blacklistedRoutes: [],
        skipWhenExpired: true,
      }
    }),
   // ...
]

Un schéma simple du flux (pris sur cet excellent article)

Une fois connecte @auth0/angular-jwt ajoutera automatiquement à tous les appels API l'entête authorization (via un HttpInterceptor), token qu'interprétera DRF pour déterminer si l'utilisateur a les droits grâce aux permission_classes.

En mode anonyme

En mode connecté avec le compte gest1 gestionnaire

Angular authentification

On utilisera le module @auth0/angular-jwt côté front. Cette librairie fournit un service JwtHelperService qui nous aidera dans notre tâche, ainsi que du paramètrage pour retrouver le token JWT, et l'injection automatique de l'entête Authorization: Bearer token dans les APIs (merci l'HttpInterceptor d'Angular qu'utilise la librairie pour ça)

On va créer un service AuthentService qui effectuera le login et le logout, ainsi que quelques fonctions utilitaires (le visiteur était-il connecté ? obtenir le token, l'utilisateur, etc)

Service AuthentService

L'objectif de ce service d'authentifier l'utilisateur et si le retour est bon, de stocker le token ainsi que l'utilisateur user en localstorage, @auth0/angular-jwt pourra ainsi retrouver ce token grâce à la fonction tokenGetter vu précédemment.

userActivate$ nous servira à émettre ce nouveau connecté aux composants qui écoutent dessus et en ont besoin.


@Injectable({ providedIn: 'root' })
export class AuthService {
  private user: User;
  private url = `${environment.baseUrl}/api-token-auth/`;
  private userSource = new ReplaySubject<User>(1);
  userActivate$ = this.userSource.asObservable();

  constructor(private http: HttpClient,
              private jwtService: JwtHelperService) {
  }
  /**
   * Authentification /api-token-auth/
   * @param {UserAuthent} user : l'utilisateur a connecté
   * @return any dont token
   */ 
  logon(user: UserAuthent): Observable<any> {
    const headers = new HttpHeaders({
      'Content-Type': 'application/json', Accept: 'application/json'
    });
    return this.http
      .post(this.url, { username: user.username, password: user.password }, {headers})
      .pipe(map(dataJwt => this._authenticated(dataJwt)));
  }
  /**
   Déconnexion, on supprime tout ce qui est relatif au connecté et son 
   token 
  */
  logout() {
    localStorage.removeItem('token');
    localStorage.removeItem('user');
  }
  isAuthenticated() {
    return !this.jwtService.isTokenExpired();
  }
  /**
   * Stockage du token et de quelques informations user
   * @param data
   * @private
   */
  private _authenticated(data: any): User {
    localStorage.setItem('token', data.token);
    localStorage.setItem('user', JSON.stringify(data.user));
    this.userSource.next(data.user as User);
    return data;
  }
}

Component bannière de connexion

On va avoir besoin d'un component pour la bannière de connexion, ce dernier, au clic du bouton appellera logon() du service AuthentService que l'on a créé, au retour si tout est bon, redirige vers la page d'accueil. En cas de connexion infructueuse, un message est affiché, sinon on le redirige sur la page d'accueil en tant que connecté.

login() {
    this.loading = true;
    this.authService.logon(this.model)
      .pipe(finalize(() => this.loading = false))
      .subscribe(data => {
        if (data.token) {
          this.router.navigate(['/']);
          }
      },
      error => {
        this.loading = false;
        if (error instanceof HttpErrorResponse && error.status === 400) {
          const message =  error.error.non_field_errors[0];
          this.message = {
            message, label: '',
            color: 'red', icon: 'error'
          };
        } else {
          throw error;
        }
      }
    );
  }

Guards

Les guards vont nous permettre de restreindre l'accès aux routes suivant des règles de gestion sur des rôles, à l'aide de 1 ou 2 interfaces : CanActivate (si le guard retourne true alors la route continue et charge le component) et potentiellement CanLoad (est-ce que les enfants peuvent être chargés ? typiquement pour un module à charger).

Nous allons définir un guard GestionnaireGuard pour les gestionnaires : si tu es gestionnaire alors les components de gestion (édition livres / auteurs) pourront être chargés.

Guard GestionnaireGuard : la fonction isGestionnaire() teste si le connecté a un rôle gestionnaire, elle renvoie un Observable trueou falseselon le résultat du test. J'utilise le UserGroupsService en écoutant le Subject connecte$, à chaque connexion et donc le nouveau connecté, je peux tester son groupe d'appartenance.

@Injectable({ providedIn: 'root'})
export class GestionnaireGuard implements CanLoad, CanActivate {
  constructor(private userGrpService: UserGroupsService) {
  }

  canLoad(route: Route): Observable<boolean> {
    return this.isGestionnaire();
  }
  canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<boolean>  {
    return this.isGestionnaire();
  }

  private isGestionnaire(): Observable<boolean> {
    return new Observable<boolean>(observer => {
      this.userGrpService.connecte$.subscribe(connecte => {
          observer.next(this._gestionnaire(connecte));
          observer.complete();
        }
      );
    });
  }
  private _gestionnaire(connecte: UserGroups) {
    return this.userGrpService.hasRole(connecte, roles.gestionnaire) ||
           this.userGrpService.hasRole(connecte, roles.admin);
  }
}

Une fois le guard défini, il suffit de l'utiliser sur les routes qui nous intéressent, ici, celle de la gestion

app.routing.ts, route pour la gestion

// ...
const appRoutes: Routes = [
  {
    path: '',
    children: [
      {path: '', component: BooksListComponent},
      {path: 'gestion', loadChildren: () => import('./gestion/gestion.module').then(m => {
        return m.GestionModule; }), canLoad: [GestionnaireGuard], canActivate: [GestionnaireGuard]}
    ]
  },
  {path: '**', component: NotFoundComponent},
];
// ...

et côté module gestion, gestion-routing.module.ts qui contient les routes liés au module gestion, celui-ci sera chargé uniquement si une des routes est appelée (lazy loading !)

// ...
const routes: Routes = [
  {
   path: '',
   canLoad: [GestionnaireGuard], canActivate: [GestionnaireGuard],
   children: [
    {path: 'book/edit', component: BookEditComponent},
    {path: 'author/edit', component: AuthorEditComponent}
   ]
 }
];
// ...

Les guards permettent un contrôle assez fin des accès aux "vues" via les routes du connecté et de ses permissions.

Modules

Les modules sous Angular permettent de ne charger les composants associés (et donc les fichiers) que lorsque la route qui pointe dessus est appelée, dans le jargon, on appelle cela du lazy loading (chargement différé) : économie lors du chargement de l'application pour les utilisateurs lambdas, on ne charge que les "pages" uniquement lors de l'accès à la gestion par exemple. Cela peut servir aussi à partager des composants vers d'autres modules ou applications.

Dans notre application, on aura les modules suivants :

le module principal, déjà existant, chargé lors du lancement de l'application : AppModule (app.module.ts)
un module GestionModule (gestion.module.ts) qui servira uniquement aux gestionnaires lors de leur accès à la gestion des livres et auteurs.
un module transverse CommonLibraryModule qui contiendra potentiellement des composants partagés par les 2 modules précédents

Gestion

La gestion consiste pour un gestionnaire à :

éditer les livres : ajout ou mise à jour (édition / suppression)
éditer les auteurs : ajout ou mise à jour (édition / suppression)

seuls les gestionnaires peuvent avoir accès à ce type de gestion CRUD.

dans gestion, nous aurons un module gestion.module.ts pour la déclaration des composants utilisés dans la gestion de routes gestion-routing.module.ts du module Gestion.

Enfin, sur les routes de l'application principale, il suffit de déclarer les routes vers la gestion (édition livres et auteurs) avec les guards appropriés, nous aurons dans app.routing.ts, remarquez la partie gestion : dès qu'une route sur /gestion est appelée (/gestion/author/edit et /gestion/book/edit), le module gestion.module est chargée (ie : les sources et le chargement en mémoire)

const appRoutes: Routes = [
  {
    path: '',
    children: [
      {path: '', component: BooksListComponent},
      {path: 'authent', component: LoginComponent},
      {path: 'login', component: LoginComponent},
      {path: 'books', component: BooksListComponent},
      {path: 'authors', component: AuthorsListComponent},
      {path: 'gestion', loadChildren: () => import('./gestion/gestion.module').then(m => {
        return m.GestionModule; })}
    ]
  },
  {path: '**', component: NotFoundComponent},
];

Consultation

Les composants de consultations (liste et affichage) font partis du module principal (app.module) car ils sont utilisés soit par les utilisateurs qui consultent mais aussi par les gestionnaire.

Nous aurons alors une déclaration simple pour les routes app.routing.ts, ici la route / et les routes books ou authors

const appRoutes: Routes = [
  {
    path: '',
    children: [
      {path: '', component: BooksListComponent},
      {path: 'authent', component: LoginComponent},
      {path: 'login', component: LoginComponent},
      {path: 'books', component: BooksListComponent},
      {path: 'authors', component: AuthorsListComponent},
      {path: 'gestion', loadChildren: () => import('./gestion/gestion.module').then(m => {
        return m.GestionModule; })}
    ]
  },
  {path: '**', component: NotFoundComponent},
];

Conclusion et sources

Dans cet article, nous avons vu

le principe des rôles et permissions en Django
l'usage du JWT
la restrictions d'accès à certaines routes / vues via les guards

Retrouvez les sources sur la branche https://github.com/zorky/library/tree/django-drf-angular-3.3 de cet article.

Dans un prochaine article, nous irons beaucoup plus loin sur le composant "data-table", en proposant des filtres colonnes ou cellules dynamiques, ainsi que certaines améliorations.

Django & DRF & Angular 101, partie 3.2 : formulaires & mat-table

DUVAL Olivier — Sat, 18 Apr 2020 09:19:53 +0000

4ème partie de la série sur Django, DRF et Angular, poursuivons le tutoriel sur une application librairie de livres.

Dans cette partie, nous allons tâcher de créer des formulaires pour saisir ou modifier des auteurs, et de lister auteurs avec la mat-table et avoir des actions sur la liste (recherche, tri, pagination, pour supprimer ou modifier un auteur)

Sommaire

Refactoring des services avec les generics et abstract
Routing et chargement des composants
Formulaires
- Auteur
  - Vue du composant
  - TS du composant
- Livre
"Data table"
Conclusion et sources

Refactoring des services avec les generics et abstract

Dans l'article précédent, nous avons utilisé 2 services qui font la même chose : fetchAll pour renvoyer toutes les lignes, fetch pour renvoyer une ligne sur un ID, hormis l'url de l'API et le modèle qui diffère, la logique est la même : appel d'un service qui renvoie des entités / modèles.

On a donc tendance à recopier le même code et de changer juste le modèle renvoyé. Si on a 10, 20, ...N services, ce n'est pas très bon, beaucoup de code pourrait être économisé.

Typescript intègre les generics et l'abstraction des classes qui vont nous aider à résoudre cette duplication de code, on est aidé à développer en POO, merci Typescript.

Nous allons créer un modèle de service qui intégrera fetchAll() et fetch() sous forme de generic, ainsi que les autres méthodes dont on a besoin (create(), update(), delete()) pour obtenir le CRUD complet d'un objet, ce modèle sera ensuite dérivé pour chaque service.

Ce modèle service est une classe générique abstraite qu intègre une méthode (abstract getRootUrl()) qui devra être implémentée dans les classes dérivées, méthode qui donnera l'URL de l'API aux fonctions qui s'en servent pour appeler les API (get() / post() / put() / delete())

L'implémentation donne alors

import { HttpClient } from '@angular/common/http';

/**
 * ServiceGeneric : fourniture du CRUD sur un type T
 */
export abstract class ServiceGeneric<T> {
  protected constructor(private http: HttpClient) {
  }

  /**
   * Pour obtenir l'url "root" de l'API souhaitée
   * urlApp permet de fournir une information complémentaire si besoin
   * Exemple : `${environment.baseUrl}/plateform/books/`;
   */
  abstract getRootUrl(urlApp?: string): string;

  fetchAll() {
    const url = this.getRootUrl();
    return this.http.get<T[]>(url);
  }

  fetch(id) {
    const urlId = `${this.getRootUrl()}${id}/`;
    return this.http.get<T>(urlId);
  }

  //...
}

Modifions nos services bookService et AuthorService qui deviennent plus simple, le bookService :

import { Injectable } from '@angular/core';
import { HttpClient} from '@angular/common/http';
import {environment} from '../../../environments/environment';
import {Book} from './book.model';
import {ServiceGeneric} from '../base/service-generic.service';

@Injectable({ providedIn: 'root' })
export class BookService extends ServiceGeneric<Book> {
  private url =  `${environment.baseUrl}/library/books/`;

  constructor(private httpClient: HttpClient) {
    super(httpClient);
  }

  getRootUrl(urlApp?: string): string {
    return this.url;
  }
}

Lors de l'appel au fetchAll() de la classe mère, celle-ci appellera getRootUrl() de la classe dérivée pour obtenir l'URL utilisée (qui renvoie this.url, propriété privée de la classe dérivée)

dans bookService

private url = `${environment.baseUrl}/library/books/`;

dans authorService

private url = `${environment.baseUrl}/library/authors/`;

la méthode getRootUrl() doit être implémentée sinon l'IDE ou le compilateur vous le font savoir

ERROR in src/app/services/books/book.service.ts:8:14 - error TS2515: Non-abstract class 'BookService' does not implement inherited abstract member 'getRootUrl'from class 'ServiceGeneric<Book>'.

8 export class BookService extends ServiceGeneric<Book> {
               ~~~~~~~~~~~

Complétons notre classe ServiceGeneric avec toutes les méthodes du CRUD : create (verbe HTTP POST), update (verbe HTTP PUT), delete (verbe HTTP DELETE), deleteById (méthode utile, sur l'id d'une entité), patch (verbe HTTP PATCH), le source entier :

import {HttpClient, HttpHeaders} from '@angular/common/http';
import {Observable} from 'rxjs';

/**
 * ServiceGeneric : fourniture du CRUD sur un type T
 */
export abstract class ServiceGeneric<T> {
  protected constructor(private http: HttpClient) {
  }

  /**
   * Pour obtenir l'url "root" de l'API souhaitée
   * Exemple : `${environment.baseUrl}/plateform/books/`;
   */
  abstract getRootUrl(urlApp?: string): string;
  /**
   * Obtient la liste des entités T
   */
  public fetchAll() {
    const url = this._getUrl();
    return this.http.get<T[]>(url);
  }

  /**
   * Obtient une entité T
   * @param id : l'id recherché
   */
  public fetch(id) {
    const urlId = this._getUrl(id);
    return this.http.get<T>(urlId);
  }

  /**
   * Création d'une entité de type T, en POST
   * @param object : l'objet à créer
   */
  public create(object: T) {
    const url = this._getUrl();
    return this.http.post(url, JSON.stringify(object), {headers: this._setHeadersJson()});
  }

  /**
   * Mise à jour d'une entité de type T, en PUT
   * @param object : l'objet à modifier
   * @param key permet (optionnel) de préciser la prioprité clé de l'objet à modifier, par défaut 'id'
   */
  public update(object: T, key: string = 'id') {
    const url = this._getUrl(object[key]);
    return this.http.put(url, object);
  }

  /**
   * update ou create selon l'id d'une entité (0 ou > 0)
   * @param object
   * @param key
   */
  public updateOrcreate(object, key: string = 'id'): Observable<any> {
    return (key in object && object[key]) ? this.update(object, key) : this.create(object);
  }

  /**
   * Patch d'une propriété d'une entité
   * @param object l'objet à "patcher"
   * @param key permet (optionnel) de préciser la prioprité clé de l'objet à modifier, par défaut 'id'
   */
  public patch(object: T, key: string = 'id'): Observable<T> {
    const url = this._getUrl(object[key]);
    return this.http.patch<T>(url, object);
  }

  /**
   * Suppression d'une entité
   * @param object : l'objet à supprimer
   * @param key la propriété clé de l'objet à supprimer, par défaut 'id'
   */
  public delete(object: T, key: string = 'id') {
    return this._delete(object[key]);
  }

  /**
   * Suppresion d'une entité par son id
   * @param id id de l'entité à supprimer
   */
  public deleteById(id) {
    return this._delete(id);
  }

  /****
   * PRIVATE
   ****/

  /**
   * Factorisation delete / deleteById
   * @param id
   * @private
   */
  private _delete(id) {
    const url = this._getUrl(id);
    return this.http.delete(url);
  }

  /**
   * Postionnement entête content-type en application/json
   * pour POST
   * @private
   */
  private _setHeadersJson(): HttpHeaders {
    const headers = new HttpHeaders();
    return headers.append('content-type', 'application/json');
  }
  /***
   * PROTECTED
   ****/

  /**
   * Détermine l'URL de l'API à utiliser, avec ou sans id
   * @param id
   * @protected
   */
  protected _getUrl(id = null) {
    let url = this.getRootUrl();
    if (id !== null) {
      url = `${url}${id}/`;
    }
    return url;
  }
}

On a ainsi une diminution de code en factorisant nos services grâce à une classe mère et un pattern de conception, intéressons-nous maintenant au routing puis aux formulaires d'édition pour les auteurs et les livres.

Routing et chargement des composants

Le routing Angular permet, à partir :

d'une url, de charger un component
d'une partie d'une url, de charger un module (chargement différé) et le component cible
d'un lien (a href) d'aller sur une route et donc de charger un component

Cela se représente par le code suivant (un module AppRoutingModule qui est importé dans le module principal AppModule)

import {NgModule} from '@angular/core';
import {RouterModule, Routes} from '@angular/router';
import {BooksListComponent} from './components/book/books-list/books-list.component';
import {BookEditComponent} from './components/book/book-edit/book-edit.component';
import {AuthorEditFormlyComponent} from './components/author/author-edit-formly/author-edit-formly.component';
import {BookEditFormlyComponent} from './components/book/book-edit-formly/book-edit-formly.component';
import {NotFoundComponent} from "./components/not-found/not-found.component";

const appRoutes: Routes = [
  {
    path: '',
    children: [
      {path: '', component: BooksListComponent},
      {path: 'books', component: BooksListComponent},
      {path: 'book/edit', component: BookEditComponent},
      {path: 'authors', component: AuthorsListComponent},
      {path: 'author/edit', component: AuthorEditComponent},
    ]
  },
  {path: '**', component: NotFoundComponent},
];

@NgModule({
  imports: [
    RouterModule.forRoot(appRoutes)
  ],
  exports: [
    RouterModule
  ]
})
export class AppRoutingModule {
}

Le path permet sur un chemin de l'url, de charger le composant, par exemple /book/edit, l'utilisateur sera dirigé vers le composant d'édition de livre, s'il y a des paramètres, ils seront ajoutés à l'url, par exemple http://localhost:4200/book/edit;id=1 pour éditer le livre d'id 1.

Par défaut, '' renvoie sur le composant BooksListComponent (http://localhost:4200), on pourrait avoir un composant de page d'accueil à la place.

A chaque changement d'url, on peut ainsi charger tel composant, c'est ainsi que l'utilisateur se "déplace" dans l'application.

Les composants associés aux urls sont chargés / injectés via le component Angular router-outlet contenu dans app.component.html, on conserve ainsi le layout défini : header / composant injecté dans le outlet / footer

<router-outlet></router-outlet>

Le routing permet aussi de restreindre l'accès aux composants (selon des rôles ou par exemple si l'utilisateur est connecté ou non via les guards).

Nous verrons les modules et guards dans un prochain article.

Formulaires

On se basera sur les reactives forms d'Angular dont j'ai une préférence face aux template-driven forms, même si ces derniers sont plus faciles et rapides à mettre en place. Les reactives offrent plus de latitude via les Observables notamment.

Pour cela, nous allons utiliser les reactives forms par le biais du service FormBuilder et de la classe FormGroup qui regroupement nos contrôles du formulaire.

Auteur

Le formulaire auteur ressemble à ce simple formulaire

En ajout

En modification

Nous allons faire en sorte de l'utiliser de 2 façons :

en "modale" (fenêtre qui s'ouvre par dessus la courante), j'ai une préférence pour ce mode pour éviter que l'utilisateur change de page quand ce n'est pas nécessaire.
en composant en pleine page, pour l'ajout d'un nouvel auteur, grâce à la route /author/edit, accessible grâce au menu qui redirigera vers cette route et donc chargera le composant app-author-edit

Pour les modales, j'aime bien utiliser un composant "conteneur" (app-author-container), qui embarque le composant app-author-edit, en lui passant ce qu'il faut (l'auteur à modifier), et ne sert que pour la modale à ouvrir.

Création d'un component author-edit

$ ng g c authorEdit

On modifie la vue et le TS

Vue author-edit.component.html

isUpdateMode indique si on est en ajout ou modification
les 2 champs de saisie pour le prénom et le nom : avec des , ils utilisent les contrôles de authorForm : first_name et last_name, le tout défini dans le TS
le nombre de caractères de la saisie / le nombre maximum autorisé, indiqués grâce à
2 boutons d'actions : pour abandonner / fermer, pour enregistrer, ce dernier est accessible uniquement lorsque les 2 champs sont saisis, grâce aux Validators du formulaire

<mat-card>
  <mat-card-title>{{isUpdateMode ? 'Edition d\'un' : 'Nouvel'}} auteur</mat-card-title>
  <mat-card-content>
    <mat-progress-bar [mode]="'indeterminate'" color="warn" *ngIf="loading"></mat-progress-bar>
    <div [formGroup]="authorForm" *ngIf="authorForm">
      <div fxLayout="column">
        <mat-form-field>
          <label>
            <input matInput
                   maxlength="{{maxInput}}"
                   placeholder="Prénom"
                   formControlName="first_name" required>
          </label>
          <mat-hint align="end"><code>{{authorForm.get('first_name').value?.length}}</code> / <code>{{maxInput}}</code></mat-hint>
        </mat-form-field>

        <mat-form-field>
          <label>
            <input matInput
                   maxlength="{{maxInput}}"
                   placeholder="Nom"
                   formControlName="last_name" required>
          </label>
          <mat-hint align="end"><code>{{authorForm?.get('last_name').value?.length}}</code> / <code>{{maxInput}}</code></mat-hint>
        </mat-form-field>
      </div>
    </div>
  </mat-card-content>
  <mat-card-actions align="end">
    <button  mat-button
             matTooltipPosition="above" matTooltip="Retour à la liste"
             [disabled]="disabled"
             (click)="goList()">{{getLabelCancelOrReturn()}}</button>
    <button  mat-raised-button color="primary"
             matTooltipPosition="above" matTooltip="Enregistrer le livre"
             (click)="save()" [disabled]="authorForm?.invalid || disabled">Enregister</button>
  </mat-card-actions>
</mat-card>

TS author-edit.component.ts

Le code TS du component.

2 Input : onReturn : détermine si l'on doit retourner sur la liste (route /authors), author : l'auteur à modifier en mode "modale" sinon l'auteur sera chargé par l'API AuthorService.fetch(id)
1 Output : événement sur la modification effectif de l'auteur, lors du save() de l'auteur, on notifie la sauvegarde en y incluant l'objet auteur
utilisation de l'événement ngOnChanges() pour détecteur et entreprendre des actions (initialisation des valeurs du formulaire) si l'Input author est utilisé

import {Component, EventEmitter, Input, OnChanges, OnDestroy, OnInit, Output, SimpleChanges} from '@angular/core';
import {FormBuilder, FormGroup, Validators} from '@angular/forms';
import {ActivatedRoute, Router} from '@angular/router';
import {MatSnackBar} from '@angular/material/snack-bar';
import {finalize} from 'rxjs/operators';
import {Author, AuthorService, Book} from '../../../services';
import {SubSink} from '../../../services/subsink';

@Component({
  selector: 'app-author-edit',
  templateUrl: './author-edit.component.html',
  styleUrls: ['./author-edit.component.css']
})
export class AuthorEditComponent implements OnInit, OnDestroy, OnChanges {
  @Input() author: Author;
  @Input() onReturn = 'list'; // 'list' || ''
  @Output() authorUpdated = new EventEmitter<Author>();

  authorForm: FormGroup;
  maxInput = 25;
  loading = false;
  isUpdateMode = false;
  disabled = false;
  formDirty = false;
  subSink = new SubSink();

  constructor(private router: Router, private route: ActivatedRoute,
              private fb: FormBuilder, public snackBar: MatSnackBar,
              private authorSvc: AuthorService) {
  }

  ngOnInit(): void {
    this._initAuthorIfUpdate();
  }
  ngOnChanges(changes: SimpleChanges): void {
    if (changes.author && changes.author.currentValue !== null && changes.author.isFirstChange() &&
      changes.author.currentValue !== changes.author.previousValue) {
      this._initForm(changes.author.currentValue);
    }
  }
  ngOnDestroy(): void {
    this.subSink.unsubscribe();
  }
  /**
   * Sauvegarde de l'auteur
   * A l'issue :
   * - snackbar de confirmation
   * - initialisation du formulaire avec les valeurs (notamment pour l'id qui peut changer de 0 à N si ajout)
   * - notification Output de la sauvegarde
   */
  save() {
    this.disabled = this.loading = true;
    this.authorSvc
      .updateOrcreate(this.authorForm.value)
      .pipe(finalize(() => this.disabled = this.loading = false))
      .subscribe((author: Author) => {
        this.snackBar.
        open(`"${author.first_name} ${author.last_name}" bien ${this.isUpdateMode ? 'mis à jour' : 'ajouté'}`,
          'Auteur', {duration: 2000, verticalPosition: 'top', horizontalPosition: 'end'});
        this._initForm(author);
        this.authorUpdated.emit(author);
      });
  }

  /**
   * Retour à la liste selon le onReturn
   */
  goList() {
    this.authorUpdated.emit(null);
    if (this.onReturn === 'list') {
      this.router.navigate(['/authors']);
    }
  }
  getLabelCancelOrReturn() {
    if (this.formDirty) {
      return 'Abandonner';
    }
    return 'Fermer';
  }

  /**
   * PRIVATE
   *
   **/

  /**
   * Initialisation du FormGroup avec les contrôles : id, first_name, last_name
   * - on met les valeurs dans le cas d'une modification le cas échéant
   * - on écoute le valueChanges pour détecter toutes modifications des champs => changement du libellé du bouton de gauche
   * @param {Author} author : l'auteur [optionnel]
   * @private
   */
  private _initForm(author: Author = null) {
    this.isUpdateMode = author && author.id > 0;
    this.authorForm = this.fb.group({
      id: [author ? author.id : 0],
      first_name: [author?.first_name, Validators.required],
      last_name: [author?.last_name, Validators.required]
    });
    this.subSink.sink = this.authorForm.valueChanges.subscribe(values => {
      this.formDirty = true;
    });
  }

  /**
   * Recherche d'un auteur par son id, initialisation du formulaire avec ses valeurs
   * @param {number} id : id de l'auteur recherché
   * @private
   */
  private _fetchAuthor(id: number) {
    this.loading = true;
    this.subSink.sink = this.authorSvc
      .fetch(id)
      .pipe(finalize(() => this.loading = false))
      .subscribe((author: Author) => {
        this._initForm(author);
      });
  }

  /**
   * Si le component n'est pas inclus dans une modale (ie: la route est garnie par son id : /author/edit;id=1)
   * Si l'author n'est pas injecté via l'Input
   * alors une initialise le formulaire vide
   * @private
   */
  private _initAuthorIfUpdate() {
    const id = this.route.snapshot.params['id'];
    if (id && id !== '0') {
      this._fetchAuthor(id);
    } else {
      if (!this.author) {
        this._initForm();
      }
    }
  }
}

Livre

Le formulaire d'un livre pour l'ajout ou l'édition se présente ainsi : nom du livre, son nombre de pages, son auteur parmi une liste (le + permet d'en rajouter un dans la liste en utilisant le formulaire de l'auteur, en modale), et si le livre est disponible ou non

Il est accessible par l'url http://localhost:4200/book/edit;id=0 (id détermine si c'est un ajout ou une modification).

Je vous laisse regarder les sources pour ne pas redire ce qui a été fait pour l'auteur.

Data table

Les data table sont très courantes sur une application : pouvoir lister (sous forme tabulaire) des lignes d'objets et agir dessus : trier, se déplacer page par page, avoir des actions dessus : les éditer, les supprimer, etc

Material propose le composant mat-table pour représenter ce type de data table

L'objectif est d'avoir, pour les auteurs, un tableau qui liste ces derniers avec

l'auteur et une colonne qui affiche ses livres
une recherche (nous utiliserons le search de django)
des actions à droite : suppression et modification d'un auteur
le tri sur l'auteur
une pagination pour changer de page de la liste des auteurs

Vue

La mat-table a besoin d'un certain nombre d'éléments :

d'une source de données, la dataSource peut être un tableau de T (T[]) ou une classe qui hérite de MatTableDataSource ou ..., on fera la version simple : une dataSource sur Author[] ramenés par notre service
de colonnes (champs) à afficher pour les lignes : mat-row
d'entête : mat-header-row
des valeurs et modèles entête et champs pour chacune des lignes : mat-header-cell et mat-cell. Il est à noté qu'on peut injecter des composants dans les mat-cell bien entendu, on se contentera ici d'afficher le prénom et nom de l'auteur

on aura alors la vue suivante

<mat-card>
  <mat-card-actions align="end" style="padding-right: 10px;">
    <button mat-raised-button (click)="addAuthor()">Ajouter un auteur</button>
  </mat-card-actions>
  <mat-card-content>
    <mat-progress-bar *ngIf="loading" [mode]="'indeterminate'" color="warn"></mat-progress-bar>
    <!-- recherche auteurs -->
    <mat-form-field>
      <input matInput type="text"
             placeholder="Rechercher un auteur"
             matTooltip="Rechercher un auteur sur son nom / prénom"
             [formControl]="search">
    </mat-form-field>
    <!-- liste des auteurs --->
    <mat-table #table [dataSource]="authors" matSort matSortDisableClear>
      <!-- les informations de l'auteur -->

      <ng-container matColumnDef="auteur" >
        <mat-header-cell *matHeaderCellDef mat-sort-header="last_name">Auteur</mat-header-cell>
        <mat-cell *matCellDef="let row">{{row.first_name}} {{row.last_name}}</mat-cell>
      </ng-container>

      <ng-container matColumnDef="books" >
        <mat-header-cell *matHeaderCellDef >Livres</mat-header-cell>
        <mat-cell *matCellDef="let row">{{getBooks(row)}}</mat-cell>
      </ng-container>

      <!-- actions suppression / modification -->

      <ng-container matColumnDef="action_delete" >
        <mat-header-cell *matHeaderCellDef [fxFlex]="5"></mat-header-cell>
        <mat-cell *matCellDef="let row" [fxFlex]="5">
          <button mat-icon-button (click)="deleteAuthor(row)"
                  matTooltip="Supprimer cet auteur"><mat-icon [color]="'warn'">delete</mat-icon></button>
        </mat-cell>
      </ng-container>
      <ng-container matColumnDef="action_update" >
        <mat-header-cell *matHeaderCellDef [fxFlex]="5"></mat-header-cell>
        <mat-cell *matCellDef="let row" [fxFlex]="5">
          <button mat-icon-button (click)="editAuthor(row)"
                  matTooltip="Editer cet auteur"><mat-icon>edit</mat-icon></button>
        </mat-cell>
      </ng-container>

      <mat-header-row *cdkHeaderRowDef="displayedColumns"></mat-header-row>
      <mat-row *cdkRowDef="let row; columns: displayedColumns;"></mat-row>
    </mat-table>
    <mat-paginator [length]="total" [pageSize]="PAGE_SIZE"
                   [pageSizeOptions]="[2, 5, 10, 20, 50]"
                   [showFirstLastButtons]="true"></mat-paginator>
  </mat-card-content>
</mat-card>

dans ce squelette, pour les attributs importants, on aura :

un champ de recherche, on utilisera les Observables et opérateurs RxJS et un contrôle "reactive form"
mat-table
- dataSource authors : Author[] rempli à l'issue de l'appel à fetchAll()
- displayedColumns = les champs (auteur et ses livres) + les actions : la liste des colonnes à afficher, mat-table l'utilise pour itérer sur les colonnes à afficher
- pour chaque mat-cell, nous avons accès à la la ligne courante de la dataSource, la row (de type Author), ce qui permet d'accéder aux propriétés de celle-ci, ici first_name et last_name, pour afficher la valeur de ces champs, pour "books", on appelle une fonction pour lister le titre des livres de l'auteur
- de 2 actions par auteur : le supprimer (après confirmation) et le modifier (sous forme de modale), les 2 actions ont une notification à l'écran comme quoi "c'est bon !" à l'aide de la snackBar
le composant mat-paginator pour gérer la pagination (page précédent / suivante, 1ère et dernière page), on utilisera un provider getAuthorFrenchPaginatorIntl directement dans le TS du composant pour traduire et nommer les éléments du paginator ("auteurs par page", "page suivante", etc)

providers: [{ provide: MatPaginatorIntl, useValue: getAuthorFrenchPaginatorIntl() }]

Typescript

/**
 * Liste des auteurs avec pagination, tris et recherche
 */
@Component({
  selector: 'app-authors-list',
  templateUrl: './authors-list.component.html',
  styleUrls: ['./authors-list.component.css'],
  providers: [{ provide: MatPaginatorIntl, useValue: getAuthorFrenchPaginatorIntl() }]
})
export class AuthorsListComponent implements OnDestroy, AfterViewInit {
  /** Datasource */
  authors: Author[] = [];
  /** Champs à afficher */
  columns = ['auteur', 'books'];
  /** Actions sur un auteur */
  actions = ['action_delete', 'action_update'];
  /** L'ensemble des colonnes à afficher : champs + actions */
  displayedColumns = [...this.columns, ...this.actions];
  /** Paramétres du paginator */
  total = 0;
  PAGE_SIZE = 5;
  /** progress bar on / off */
  loading = false;
  /** lien vers les composants tri et paginator */
  @ViewChild(MatSort, {static: true}) sort: MatSort;
  @ViewChild(MatPaginator, {static: true}) paginator: MatPaginator;
  /** FormControl pour la recherche */
  search = new FormControl('');
  /** Utilitaire subscribe / unsubscribe */
  subSink = new SubSink();

  constructor(private router: Router, private route: ActivatedRoute,
              private dialog: MatDialog, public snackBar: MatSnackBar,
              private authorSvc: AuthorService) { }
  ngAfterViewInit(): void {
    this._initDataTable();
  }

  /**
   * Transformation de la liste de livres de l'auteur en chaîne
   * @param {Author} author : l'auteur
   */
  getBooks(author: Author) {
    return author?.books_obj?.reduce<string>((acc, currentValue, i) => {
      return i === 0 ? currentValue.name : `${acc}, ${currentValue.name}`;
    }, '');
  }
  /**
   * ACTIONS sur un auteur
   */
  /**
   * Ajout d'un auteur via une modale
   */
  addAuthor() {
    this._openAuthorModale();
  }
  /**
   * Edition d'un auteur via une modale
   * @param {Author} author
   */
  editAuthor(author: Author) {
    this._openAuthorModale(author);
  }
  /**
   * Suppression d'un auteur, après confirmation
   * @param {Author} author
   */
  deleteAuthor(author: Author) {
    const data = new DialogData();
    data.title = 'Auteur';
    data.message = `Souhaitez-vous supprimer cet auteur "${author.first_name} ${author.last_name}" ?`;
    const dialogRef = this.dialog.open(ConfirmationDialogComponent, { data });
    dialogRef.updatePosition({top: '50px'});
    dialogRef.afterClosed().subscribe(result => {
      if (result) {
        this.authorSvc.delete(author).subscribe(() => {
          this.snackBar.open(`"${author.first_name} ${author.last_name}" bien supprimé`,
            'Auteur',
            {duration: 2000, verticalPosition: 'top', horizontalPosition: 'end'});
          this.paginator.pageIndex = 0;
          this._initDataTable();
        });
      }
    });
  }
  /**
   * Ouverture modale d'édition d'un auteur
   * @param {Author} author
   * @private
   */
  _openAuthorModale(author: Author = null) {
    const data = author;
    const dialogRef = this.dialog.open(AuthorContainerComponent, {data});
    dialogRef.updatePosition({top: '50px'});
    dialogRef.updateSize('600px');
    dialogRef.afterClosed().subscribe((result: Author) => {
      if (result) {
        this._initDataTable();
      }
    });
  }
  /**
   * Factorisation du switchMap
   * @private
   */
  _switchMap(): Observable<Pagination<Author>> {
    this._toggleLoading(true);
    const parameters: ListParameters = {
      limit: this.paginator.pageSize, offset: this.paginator.pageIndex * this.paginator.pageSize,
      sort: this.sort.active, order: this.sort.direction,
      keyword: this.search.value
    } as ListParameters;
    return this.authorSvc.fetchAll(parameters);
  }
  /**
   * Initialisation data table, écoutes sur le tri, la pagination et la recherche
   * @private
   */
  _initDataTable() {
    const search$ = this.search.valueChanges
      .pipe(debounceTime(400), distinctUntilChanged(),
            switchMap((value) => {
              this.paginator.pageIndex = 0;
              return this._switchMap();
            }));
    const sortPaginate$ = merge(this.sort.sortChange, this.paginator.page)
      .pipe(startWith({}), switchMap((values) => this._switchMap()));

    this.subSink.sink = merge(search$, sortPaginate$)
      .subscribe((data: Pagination<Author>) => {
        this._toggleLoading(false);
        if (data) {
          this.total = data.total;
          this.authors = data.list;
        }
      });
  }
  _toggleLoading(value) {
    setTimeout(() => this.loading = value);
  }
  ngOnDestroy(): void {
    this.subSink.unsubscribe();
  }
}

champ de recherche : écoute sur valueChanges, on lui applique quelques opérateurs RxJS : déclenchement au bout de 400 ms (debounceTime) et on évite de poursuivre si c'est la même chaîne de saisie (distinctUntilChanged), c'est seulement après ces 2 filtres que la recherche démarre via un switchMap (un concatMap aurait été possible)
le tri / pagination : écoute des changements de tri (sortChange) et de pagination (page), ici encore, un switchMap est utilisé à l'issue de ces changements potentiel pour lancer le fetchAll() de l'API avec le tri ou la pagination modifiées

Le résultat (une liste d'auteurs Author[]) de cet ensemble (tri, pagination ou recherche puis appel à l'API fetchAll()) se retrouve dans l'abonnement subscribe(), il ne reste plus qu'à affecter authors, la mat-table se met à jour automatiquement grâce au binding de la dataSource (un Input()).

switchMap / concatMap : Ces 2 opérateurs permettent d'attendre le résultat d'une opération puis de lancer une autre opération ensuite. Le switchMap permet dans l'absolu d'annuler l'opération lancée s'il se passe quelques chose entre-temps, contrairement au concatMap (qui est donc secure pour des opérations qui ne demandent pas à être annulée : bancaire ou création d'entités qui doivent l'être, etc). Ici pas bien grave d'annuler une recherche en cours ou un tri / pagination, on utilisera donc un switchMap
merge : on utilise l'opérateur merge pour écouter tous les observables (sortPaginate$, search$), le 1er qui répond, on actionne le fetchAll() !

Conclusion et sources

On a vu

un début de refactoring pour diminuer le code en factorisant les services via une classe abstraite et les generics (les fonctions utilitaires sont volontairement mis en protected pour pouvoir les surcharger si le sort, la pagination, etc différent avec le serveur d'applications par exemple)
quelques opérateurs RxJs : debounceTime(), distinctUntilChanged(), switchMap() / concatMap(), merge()
les routes et l'appel aux composants associés
la mat-table de Material et quelques autres composants utiles : matInput et le FormGroup ou FormControl, MatDialog, snackBar

Au prochain article, nous irons plus loin dans la factorisation de composant, toujours sur la data-table, en faire un composant pour qu'il soit utilisé pour les livres, les auteurs, etc, ainsi que les modules en Angular voire les Guards.

Retrouvez les sources sur la branche https://github.com/zorky/library/tree/django-drf-angular-3.2 de cette suite sur Angular.

Django & DRF & Angular 101, partie 3.1

DUVAL Olivier — Sat, 04 Apr 2020 12:08:52 +0000

3ème partie consacrée à une application de type SPA, après les 2 / 3 parties axées sur le serveur d'applications pour fournir les APIs : django & drf (django rest framework).

Sommaire

SPA, introduction
Préparation de l'environnement
- CORS & Django
- Angular
Angular
- Introduction
- Typescript
- Services
- Components
  - Communication entre composants / components
    - Input
    - Output
    - Service & Subject
  - Composant app-books-list
  - Composant app-author-display
  - Composant principal app-root
Conclusion et sources

SPA, introduction

Les SPA se basent sur une approche composants et une architecture dite REST à base d'APIs, vous pouvez relire une présentation sur la partie REST du précédent article.

Dans un contexte d'applications métiers (en interne d'une organisation), le gros avantage d'une SPA est son côté fluide et son apport en termes d'UX, on se croirait sur une réelle application et non plus sur un "site Web", cela a remplacé ou remplace les applications développées MPA ou en Flash ou Silverlight ou Java Web Start et autres applets Java si on remonte encore plus loin, etc.

Dans un passé plus proche, les MPA (Multi Pages Applications) avaient / ont le défaut de leur qualité :

des allers-retours avec le serveur pour charger les pages et les sources javascript / CSS, souvent dans un modèle MVC, quid des modèles chargés de façon assez peu cohérent
on veut une meilleure interaction pour l'utilisateur, une meilleure UX, pour se faire, on utilise Javascript et ...jQuery pour les appels Ajax et des effets sur le DOM (apparitions et disparitions d'éléments etc) : on fait du SPA sans vraiment en faire, du code spaghetti augmente au fur et à mesure des vues et des versions de l'application : scripts chargés tant bien que mal, lesquels chargés pour telle vue, du JS fonctionnel et non objet, des scripts de fonctions appelées les unes par rapport aux autres : l'application devient très difficile à maintenir (entropie qui s'installe avec le temps) pour les suivants (développeurs) et c'est l'expérience de beaucoup de projets qui parle

Partant de ce postulat (application), une SPA est une application qui sera embarquée dans le navigateur Web, avec un jeu de "routes" (urls) et de chargement de composants à l'intérieur de l'application, ce qui peut se schématiser par

(schéma pris sur cet article)

Les sources d'une application SPA ressemble à cela, autant dire il n'y a pas grand chose et c'est assez perturbant ;)

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Ma librairie</title>
  <base href="/library/">  
  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
  <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700" rel="stylesheet">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
  <link rel="stylesheet" href="/library/styles.a7613a87447eae269697.css"></head>
<body>

<app-libray-root></app-library-root>

<script type="text/javascript" src="/library/runtime.44f969275dacc8c108f8.js"></script>
<script type="text/javascript" src="/library/es2015-polyfills.ed18db863a6a6727d6b6.js" nomodule></script>
<script type="text/javascript" src="/library/polyfills.6daf05ca7cb3720c8e32.js"></script>
<script type="text/javascript" src="/library/scripts.2ccf57d185e6d7cc00a6.js"></script>
<script type="text/javascript" src="/library/main.080a43d15e12f96ae533.js"></script>
</body>
</html>

Une Single Page Application a une architecture à base de ces éléments :

un frontend : application (Javascript / HTML / CSS) embarquée dans le navigateur, des composants / des APIs : un cadre est posé
un backend : un serveur d'applications qui sert des APIs sur une architecture REST

A contrario d'applications classiques MPA (Multi Page Applications), qui chargent les pages au fur et à mesure de la navigation, avec des allers-retours entre le navigateur et le serveur (ces serveurs d'applications utilisent souvent le modèle MVC), les SPA, vont les charger en une fois ou de façon transparente pour les utilisateurs (javascript, les vues HTML, CSS), les données chargées au fur et à mesure grâce aux APIs et à l'Ajax, cela rend la navigation beaucoup plus fluide et améliore l'expérience utilisateur.

Parmi les frameworks et librairies existantes, je me baserai sur Angular à sa version 9. Angular que j'utilise depuis sa version 2 depuis bientôt 3 ans (la version dite "2" totalement réécrite, auparavant, j'avais également participé à 2 projets en 2+ ans avec la version "1" AngularJS qui a comme seul point commun avec sa version "2" que le modèle SPA, pour le reste, pas grand chose à voir techniquement)

Préparation de l'environnement

CORS & Django

Dans un contexte de purs appels "Ajax" (XMLHttpRequest), un mécanisme de protection est mis en place via CORS afin de contrôler et de savoir si le client qui fait l'appel (get, post, ...) a le droit ou non, surtout sur du cross-domains : un client sur domain-A.ntld effectue une requête "Ajax" sur le domain-B.ntld, il faut l'autoriser ou ...le refuser, CORS permet cela, contrôler l'origine de la requête et accepter ou refuser ce type d'appels.

En Django & DRF, nous utilisons le module django-cors-headers et l'activons dans le settings.py sur la "section" INSTALLED_APPS avec corsheaders ainsi que le MIDDLEWARE corsheaders.middleware.CorsMiddleware.

Enfin, des clés de configuration sont utilisées pour paramétrer CORS (regexp sur le(s) domaine(s) autorisé(s), les entêtes) :

CORS_ORIGIN_REGEX_WHITELIST : liste de regexp pour les domaines acceptés
CORS_ORIGIN_ALLOW_ALL = True en mode DEBUG en mode développement
CORS_ALLOW_HEADERS : liste des entêtes acceptés

Historiquement, avant CORS, lors de l'utilisation de jQuery, nous utilisions une astuce pour le cross-domain: le JSONP qui permettait de générer une balise script (avec l'URL de l'appel) à la volée et effectuer ainsi des appels cross-domains, jQuery permettant facilement la génération de scripts lors d'un appel de type JSONP.

Environnement Angular

Pour un environnement de développement Angular, nous aurons besoin :

d'un IDE : j'utilise Webstorm mais VSCode reste très bien
d'installer NodeJS (v10 ou v12) (pour npm, la compilation à la volée Typescript et du serveur Web local d'exécution). Remarques: en production, une application Angular n'a pas besoin de node, comme les sources "compilées" ne sont basées que sur JS, HTML et CSS
Créer un répertoire "frontend", créer un fichier package.json (cf. contenu ci-après) et installer Angular CLI : le client angular qui va nous aider à compiler, créer des composantes, etc. Ici, cela sert uniquement à ne pas installer Angular CLI de façon global sur votre PC (l'option -g).

$ mkdir frontend && cd frontend

Contenu du fichier package.json

{
  "name": "library",
  "version": "1.0.0",
}

Installer Angular CLI localement :

$ npm install @angular/cli --save-dev

La version d'angular cli est installé :

$ ng --version

     _                      _                 ____ _     ___
    / \   _ __   __ _ _   _| | __ _ _ __     / ___| |   |_ _|
   / △ \ | '_ \ / _` | | | | |/ _` | '__|   | |   | |    | |
  / ___ \| | | | (_| | |_| | | (_| | |      | |___| |___ | |
 /_/   \_\_| |_|\__, |\__,_|_|\__,_|_|       \____|_____|___|
                |___/


Angular CLI: 9.1.0
Node: 12.13.1
OS: win32 x64

Angular: undefined
...
Ivy Workspace: <error>

Package                      Version
------------------------------------------------------
@angular-devkit/architect    0.901.0
@angular-devkit/core         9.1.0
@angular-devkit/schematics   9.1.0
@angular/cli                 9.1.0
@schematics/angular          9.1.0
@schematics/update           0.901.0
rxjs                         6.5.4

RxJs est aussi installé, nous en parlerons un peu plus tard, cela remplace les Promises qui avaient certaines limitations, RxJs ou la programmation réactive apporte aussi quelques avantages.

Créer l'application "library", cela va créer dans le répertoire library toute la tuyauterie (sources, package.json, etc)

$ ng new library

Exécuter une 1ère fois notre nouvelle application, notre squelette s'ouvre dans le navigateur sur l'adresse http://localhost:4200/

$ cd library
$ ng serve -o

Ajoutons quelques modules qui seront utiles, toujours dans "frontend/library" material, PWA et Flex layout qui nous servira pour ajuster les éléments sur une page (un site dont je me sers souvent avec des exemples)

$ ng add @angular/material
$ ng add @angular/pwa
$ ng add @angular/flex-layout

On vérifie que tout se passe bien en lançant l'application

$ ng serve -o

On a alors l'ensemble des fichiers suivants dans frontend/library

Parmi les principaux :

angular.json : le paramétrage de l'application Angular selon l'environnement, pour les tests unitaires, mode de compilation, etc
browserslist : pour la gestion compatibilité des navigateurs, Angular peut détecter et introduire des polyfills le cas échéant
package.json : la gestion des modules NPM
tsconfig.app.json : la configuration de l'application pour la compilation Typescript
tsconfig.json : la configuration générale Typescript, utilisé par tsconfig.app.json (cela peut être utile si nous avions plusieurs applications Angular à gérer, cela donne une configuration de base pour l'ensemble)
src : les sources de notre application se trouvera dans ce répertoire, ng nous a créé un semble de fichiers, notamment app-component qui représente le composant principal à partir duquel, les autres seront chargés

Source de notre application sur http://localhost:4200

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Library</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
  <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500&amp;display=swap" rel="stylesheet">
  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
  <link rel="manifest" href="manifest.webmanifest">
  <meta name="theme-color" content="#1976d2">
</head>
<body>
  <app-root></app-root>
  <noscript>Please enable JavaScript to continue using this application.</noscript>
<script src="runtime.js" type="module"></script><script src="polyfills.js" type="module"></script><script src="styles.js" type="module"></script><script src="vendor.js" type="module"></script><script src="main.js" type="module"></script></body>
</html>

Angular

Introduction

Angular est un framework / un cadre de développement de la famille SPA qui a été présentée (on peut trouver d'autres plateformes, des librairies : React, VueJS parmi les plus connues). C'est un framework Opensource (sous licence MIT) qui a été porté par Google, une forte communauté s'investit et tourne autour d'Angular.

Angular présente un cadre qui contraint le développeur, personnellement, c'est un bien, moins permissif et moins de code à la "jQuery", ce cadre couvre :

le langage, avec Typescript
une approche composants
avec un moteur de vue et de binding
à l'aide de services que l'on injectera dans les composants ou qui seront utilisés directement
un système de routing ou "routes" qui représentent les URLs et les composants à charger
un framework qui vous permet de créer des modules pour optimiser le chargement ou cloisonner selon les utilisateurs
tout un outillage de développement : de "compilation" / création / de mise à jour de versions ou de lancement d'une application grâce à Angular CLI, et de bundle et d'optimisation grâce à webpack ou Ivy (depuis la v8)
et bien plus : PWA, schematics (du scaffolding qui va jusqu'à de la mise à jour du code), Web elements

Autour du développement Angular, beaucoup d'éléments basés sur les Observables qui amène à la programmation réactive à l'aide de RxJS.

Du côté composants "graphiques" / UX, on trouvera Material, projet également Opensource qui constitue une excellent librairie qui implémente Material design, bien plus moderne et réactive que Bootstrap que l'on peut retrouver ailleurs.

Préambule et saisie des auteurs et livres

En attendant des interfaces d'édition des livres et auteurs sous Angular, vous pouvez utiliser l'admin de django qui n'est pas très user friendly mais ça aide. En ouvrant sur le navigateur, suivant si vous avez suivi la méthode virtualenv ou docker pour exécuter le serveur d'applications (voir la mise en place sur cet article)

Notre squelette d'application maintenant créé, on va pouvoir le modifier.

L'objectif est de lister les livres avec leur auteur.

Typescript

Le développement sous Angular s'effectue avec Typescript qui est un transpileur : le compilateur prend un source et le transpile en ... Javascript.

Les puristes vous diront que c'est une perte de temps certainement, que rien ne vaut JS, etc J'ai de longues années de pratique de Javascript, en POO, et il est à constater que développer en programmation objet lorsque l'on vient de langages de type C#, Java & consorts, n'est pas chose aisée car Javascript est un langage à prototype avec une syntaxe qui peut perturber.

C'est pourquoi nombre de développeurs n'utilise pas toute la puissance de Javascript pour la POO pour l'abstraction, on parlera alors encapsulation, héritage ou composition pour les grands principes mais souvent comme un langage impératif pour composer un fichier source d'une liste de fonctions à la suite des unes des autres (et génère ainsi du code spaghetti).

Typescript répond à plusieurs points que JS n'apporte pas immédiatement :

comment puis-je continuer à programmer objet comme mes autres langages objets que je connais, avec les mêmes principes ? Typescript intègre les classes, les interfaces et bien d'autres choses, nous sommes en terrain connu
TS permet aussi de typer et de vérifier à la compilation notre source, JS étant un langage à typage dynamique, et comme tous les langages de ce type, on peut avoir des surprises, TS réduit ce risque à l'exécution, la phase de transpilation permettant de réparer au plus tôt le code et d'avoir un code plus compréhensible pour les autres. Grâce au typage et selon votre IDE, celui-ci pourra vous proposer l'autocompletion des types, gain de temps assuré !
enfin, TS, permet d'avoir des modes de compilation, c'est à dire, la possibilité de préciser pour quelle version de Javascript je souhaite transpiler : ES 5, ES 6, ES next etc sans modifier le source d'origine de mon TS ! et ça, c'est précieux, beaucoup moins de réécrire de code. TS met même en place des mécanismes, sucres syntaxiques afin de pouvoir utiliser des techniques JS futures tout en gardant une version de JS qui n'implémente pas encore ces fonctionnalité (par exemple async / await en ES 5 n'existent pas ces 2 mots clés sont liés aux Promises, ils sont apparus à partir de ES2017, mais TS permet de les utiliser tout en produisant un code pour ES 5, magique ;) )

Pour toutes ces raisons, et il doit en manquer, Typescript est de plus en plus utilisé, dans VueJS, React, etc

En TS, par exemple, le code suivant du fichier test.ts, où on utilise le optional chaining et le nullish coalescing, ainsi que async / await (sucre syntaxique), tout ceci n'existe pas en ES5.

let obj = { attribut: 'toto' };
const variable = 0;
obj = null;
const maVarOptional = obj?.attribut;
const maVarNullish = variable ?? 1;

async function delay(n: any) {
  return n;
}

const results = (async () => await delay(400));
results().then((value: string) => console.log(value));

transpilation : tsc test.ts donnera le fichier test.js

le résultat de la transpilation avec cet outil en ligne, vous pouvez faire varier le target selon la version de Javascript que vous souhaitez (ES2017 par exemple intègre le async / await), intéressant de voir ce que Typescript génère suivant les versions (en ES2020, le optional chaining et le nullish coalescing sont maintenant intégrés, merci TS de pouvoir les utiliser dans les versions moins récentes ;-))

Le code TS sera traduit en Javascript de la façon suivante (attention c'est verbeux pour l'async / await en ES5) :

"use strict";
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
    return new (P || (P = Promise))(function (resolve, reject) {
        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
        step((generator = generator.apply(thisArg, _arguments || [])).next());
    });
};
var __generator = (this && this.__generator) || function (thisArg, body) {
    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
    function verb(n) { return function (v) { return step([n, v]); }; }
    function step(op) {
        if (f) throw new TypeError("Generator is already executing.");
        while (_) try {
            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
            if (y = 0, t) op = [op[0] & 2, t.value];
            switch (op[0]) {
                case 0: case 1: t = op; break;
                case 4: _.label++; return { value: op[1], done: false };
                case 5: _.label++; y = op[1]; op = [0]; continue;
                case 7: op = _.ops.pop(); _.trys.pop(); continue;
                default:
                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
                    if (t[2]) _.ops.pop();
                    _.trys.pop(); continue;
            }
            op = body.call(thisArg, _);
        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
    }
};
var obj = { attribut: 'toto' };
var variable = 0;
obj = null;
var maVarOptional = obj === null || obj === void 0 ? void 0 : obj.attribut;
var maVarNullish = variable !== null && variable !== void 0 ? variable : 1;
function delay(n) {
    return __awaiter(this, void 0, void 0, function () {
        return __generator(this, function (_a) {
            return [2 /*return*/, n];
        });
    });
}
var results = (function () { return __awaiter(void 0, void 0, void 0, function () { return __generator(this, function (_a) {
    switch (_a.label) {
        case 0: return [4 /*yield*/, delay(400)];
        case 1: return [2 /*return*/, _a.sent()];
    }
}); }); });
results().then(function (value) { return console.log(value); });

le fichier de configuration de compilation typescript

{
        "compilerOptions": {
                "target": "ES5"
        }
}

le target peut avoir les valeurs suivantes : "ES3" (par défaut), "ES5", "ES6"/"ES2015", "ES2016", "ES2017", "ESNext".

Nota Bene : async / await sont 2 mots clés liés aux Promises et qui permettent de résoudre quand vous utilisez (les promises) ce type de code imbriqué, afin de le rendre linéaire à la lecture et donc plus lisible

getResponse(url, (response) => {
   getResponse(response.url, (secondResponse) => {
     const responseData = secondResponse.data
     getResponse(responseData.url, (thirdResponse) => {
//       ...
     })
   })
 })

const response = await getResponse(url)
const secondResponse = await getResponse(response.url)
const responseData = secondResponse.data
const thirdResponse = await getResponse(responseData.url)
// ...

Service

Angular propose la notion de services. Un service contient la logique que l'on doit développer, la majeure partie du temps, un service contiendra le code pour consommer une API : obtenir un livre, lister les listes, etc pour résumer le CRUD d'une entité mais on peut aussi les utiliser pour effectuer des traitements.

Les services sont injectés dans les components, on retrouve le principe de l'IoC (utilisé souvent en C#, Java, etc) : une instance est initialisée (si elle n'existe pas déjà) puis injectée dans le constructeur d'un component, un service est donc un singleton.

Créer sous src/app le répertoire services, on va créer 2 fichiers : un modèle et un service

Le modèle : créer avec votre IDE le fichier book.model.ts et author.model.ts pour notre modèle Book et Author (une interface avec les champs typés de ce que va nous renvoyer l'api books ou authors) avec le contenu suivant

export interface Book {
  id: number;
  name: string;
  nb_pages: number;
  enabled: boolean;

  dt_created?: string;
  dt_updated?: string;
}

export interface Author {
  id: number;
  first_name: string;
  last_name: string;

  dt_created?: string;
  dt_updated?: string;
}

Les champs ayant ? sont considérés optionnels lorsque de la création d'un objet. Ce typage nous permettra aussi d'avoir l'autocompletion dans notre IDE sur les champs lors de l'utilisation d'un objet dans la vue ou le ts.

Le service : en ligne de commande, dans src/app/services, on crée notre service qui pointera vers l'API books et un autre vers l'API authors, on utilise le ng cli

$ ng g service bookService
$ ng g service authorService

dans book.service.ts / author.service.ts, éditons le code pour qu'il ressemble à ceci :

utilisation du HttpClient qui sert à effectuer les appels (get, post, ...,), les appels sont si possible typés, pour notre liste de Book ou Author, le get utilisé renverra Book ou Author[] selon l'API utilisée, à l'aide des generics de Typescript
du modèle créé pour le modèle Book ou Author
selon le type de l'environnement, l'URL base de l'API utilisée, cela représente le serveur (en local : http://localhost:4200, en test, https://domain-test.ntld, en production : https://domain-prod.ntld, etc)

import { Injectable } from '@angular/core';
import { HttpClient} from '@angular/common/http';
import {environment} from '../../../environments/environment';
import {Book} from './book.model';

@Injectable({
  providedIn: 'root'
})
export class BookService {
  private url =  `${environment.baseUrl}/library/books/`;
  constructor(private httpClient: HttpClient) { }

  /**
   * Liste de tous les livres
   */
  public fetchAll() {
    return this.httpClient.get<Book[]>(this.url);
  }

  /**
   * Obtient un livre particulier par son id
   * @param {number} id : l'identifiant du livre
   */
  public fetch(id: number) {
    const urlId = `${this.url}${id}/`;
    return this.httpClient.get<Book>(urlId);
  }
}

import {Injectable} from "@angular/core";
import {environment} from "../../../environments/environment";
import {HttpClient} from "@angular/common/http";
import {Author} from "./author.model";

@Injectable({
  providedIn: 'root'
})
export class AuthorService {
  private url =  `${environment.baseUrl}/library/authors/`;
  constructor(private httpClient: HttpClient) { }

  /**
   * Liste de tous les auteurs
   */
  public fetchAll() {
    return this.httpClient.get<Author[]>(this.url);
  }

  /**
   * Obtient un auteur particulier par son id
   * @param {number} id : l'identifiant de l'auteur
   */
  public fetch(id: number) {
    const urlId = `${this.url}${id}/`;
    return this.httpClient.get<Author>(urlId);
  }
}

Nos 2 services sont créés, on va pouvoir les utiliser dans nos components.

Composants / components

Un component est la base d'Angular. On va créer un arbre de composants (comme les balises HTML) afin de construire notre application.

Un component va être composé de 3 fichiers :

la vue : component.html, dans la vue Angular intègre un moteur qui permet du traitement sur de la donnée ou composants : l'afficher en interpolant une "variable", itérer de dessus (*ngFor), tester (*ngIf), "two way data binding" etc
le code Typescript : component.ts
le CSS le cas échéant : component.css

Une commande Angular CLI permet de créer à la voléé ces fichiers ainsi qu'un squelette HTML et TS, il l'ajoutera également au module courant où se situe le component

$ ng g c monComponent

g : generate, c : component

Pour schématiser, on aura la structure suivante dans index.html puis l'arborescence à partir de app-root :

app-root (app.component.html)
- app-header (header.component.html)
- app-books-list (books-list.component.html)
- app-footer (footer.component.html)

Communication entre components

La communication est possible entre components / composants. Les composants sont organisés en arbre, un composant peut donc avoir des enfants, qui, eux-même des enfants, etc, et un enfant un père.

componant-pere
  |--- composant-fils1
  |--- composant-fils2-pere2
       |--- composant-fils3

Pour communiquer entre composants, nous avons plusieurs options :

du père vers un fils : par les attributs [attribut] que propose un composant avec des @Input() : le composant fils intercepte alors la valeur via son @Input sur une propriété

Par exemple, le père utilise dans sa vue le composant fils , et lui passe la valeur "ma valeur"

<composant-fils1 [proprieteValeur]="'ma valeur'"></composant-fils1>

Côté fils, il pourra utiliser la valeur passer à proprieteValeur, ici, un string

@Component({
  templateUrl: './composant-fils1.component.html',
  styleUrls: ['./composant-fils1.component.scss']
})
export class ComposantFils1Component implements OnInit {
   @Input() proprieteValeur: string= null;
}

du fils vers son père : par les événements de type EventEmitter que propose le composant fils par les @Output() : le composant père intercepte alors l'événement par une fonction associés au (output_name), et potentiellement la valeur envoyée par le EventEmitter

Par exemple, le père utilise dans sa vue le composant fils , et attend de la part du fils, un événement qui lui passera une valeur (ici, un string)

<composant-fils1 (onSelected)="funInterception($event)"></composant-fils1>

FunInterception(event) {
   console.log("reçu !");
   console.log(event);
}

Côté fils, le onSelected est un EventEmitter qu'il va utiliser pour envoyer grâce à emit de la donnée (par exemple, à la suite d'un click bouton, d'un traitement fini, etc)

@Component({
  templateUrl: './composant-fils1.component.html',
  styleUrls: ['./composant-fils1.component.scss']
})
export class ComposantFils1Component implements OnInit {
   @Output() onSelected: : EventEmitter<string> = new EventEmitter<string>();

   TraitementFini() {
       this.onSelected.emit('Traitement fini, prends le relais !');
   }
}

Les Input() et Output() peuvent s'utiliser seuls ou en les combinant (on parlera de two way binding).

par un service en le combinant avec un objet RxJS de type Subject. Dans ce cas, peu importe si père ou fils, la communication s’effectuera dès lors que le service est utilisé, soit en émission, soit en écoute, les composants sont alors totalement découplés, en revanche, attention à bien s'y retrouver s'il en existe trop :)

Exemple concret

Le service de communication

@Injectable({ providedIn: 'root' })
export class CommunicationService {
  /** le Subject déclenché via filterUsed$ **/
   private filterUsedSource = new Subject<{name: string, value: any}>();

  /** l'observable à utiliser pour la communication pour l'interception **/
  filterReceive$ = this.filterUsedSource.asObservable();

  /** fonction d'envoi d'une valeur à intercepter par d'autres via filterUsed$ **/
  filterSend(name: string, value: any) {
    this.filterUsedSource.next({name: name, value: value, used: used});
  }
}

composant 1 qui attendra de recevoir

@Component({
  templateUrl: './composant-1.component.html',
  styleUrls: ['./composant-1.component.scss']
})
export class Composant1Component implements OnInit, OnDestroy {
   sub: Subscription;
   constructor(private commSvc: CommunicationService) {
   }

   ngOnInit() {
     this.sub = this.commSvc.filterReceive$.subscribe((valeur) => {
        console.log(valeur);
        console.log('Bien reçu !');
     });

   }

   ngOnDestroy() {
      this.sub.unsubscribe();
   }
}

composant 2 qui enverra des données à qui voudra bien l'écouter !

@Component({
  templateUrl: './composant-2.component.html',
  styleUrls: ['./composant-2.component.scss']
})
export class Composant2Component implements OnInit {
   constructor(private commSvc: CommunicationService) {
   }

   ngOnInit() {
   }

   EnvoiTraitement() {
     this.commSvc.filterSend({name: 'composant 2 envoie', value: 'cette valeur'});
   }
}

Composant app-books-list

Créons notre composant pour lister les livres, le but est de charger le service bookService, par le constructeur du component, d'appeler la fonction fetchAll() au clic du bouton, fonction qui fera l'appel à l'API et nous ramènera tous les livres de la base.

Squelette du TS d'un component généré grâce à "ng g c booksList", on a alors le constructeur du component et au moins l'événement / hook (qui sera appelé au chargement du component par Angular) ngOnInit qui est l'implémentation de l'interface OnInit, d'autres événements sont disponibles sur le cycle de vie d'un component. Angular utilise les décorateurs de Typescript, ici, @Component qui a au moins 3 attributs : le selector qui sera utilisé dans les vues "mères", la vue templateUrl du component et son CSS styleUrls

import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-books-list',
  templateUrl: './books-list.component.html',
  styleUrls: ['./books-list.component.css']
})
export class BooksListComponent implements OnInit {

  constructor() { }

  ngOnInit(): void {
  }

}

et la vue HTML générée (attention, elle est complexe)

<p>booksList works!</p>

Modifions les 2 fichiers pour y inclure ce qu'il faut pour la liste de nos livres : un bouton où au clic, les livres sont chargés

La vue books-list.component.html dans laquelle on utilise les composants Material : une mat-card (carte), un bouton en mat-raised-button, un matBadge pour afficher sur le bouton le nombre de livres ramenés par l'API, un mat-progress-bar ("spinner") qui s'affichera lors de l'appel à l'API, une mat-list pour afficher la liste des livres,

<mat-card>
  <mat-card-title>Livres</mat-card-title>
  <mat-card-content>
    <mat-card-actions align="end" style="padding-right: 10px;">
      <button mat-raised-button
              matBadge="{{books ? books.length : 0}}" matBadgePosition="after"
              matBadgeColor="accent" matBadgeOverlap="true" matBadgeSize="large"
              (click)="fetchBooks($event)">
        Charger les livres
      </button>
    </mat-card-actions>
    <mat-progress-bar *ngIf="loading"
                      [mode]="'indeterminate'" color="warn"></mat-progress-bar>
    <mat-divider></mat-divider>
    <mat-list>
      <mat-list-item *ngFor="let book of books">
        <p mat-line>
          <span mat-list-icon><mat-icon>book</mat-icon></span>
          <span>{{book.name}}</span>
        </p>
        <p mat-line><app-author-display [author]="book?.author_obj"></app-author-display></p>
        <p mat-line><mat-divider class="mat-divider-dashed"></mat-divider></p>
      </mat-list-item>
    </mat-list>
  </mat-card-content>
</mat-card>

Le moteur de template Angular permet de faire des traitements :

chaque component peut avoir des événements qui permettent de communiquer du composant fils vers le père qui l'utilise, ces événements sont matérialisés notamment dans le composant fils par le décorateur @Output() sur une propriété. Par exemple, le button a un événement au clic : (click), il suffit d'y adjoindre une fonction qui sera appelée au clic du bouton, ici, la fonction fetchBooks() qui est dans le TS de app-books-list
*ngIf : test si true alors
*ngFor : itération sur une liste d'objets, ici la liste de livres
les

{{var}}

permettent d'interpoler la valeur d'un objet var contenu dans le TS

le ? : l' optional chaining, permet si l'objet en question est null de ne pas continuer la chaîne, par exemple : book?.author_obj : si book est nul, il s'arrête là sinon il ira chercher l'attribut author_obj de book, valable également en typescript depuis Angular 8 / 9, comme le nullish coalescing. C'est très utile de l'utiliser pour éviter des désagréments, et facilite une syntaxe du type "book ? book.author_obj : null", et en plus, l'optional chaining et le nulling coalescing viennent d'être adoptés pour ES 2020, what else ? Même si ES2020 ne sera pas implémenté de si tôt sur tous les navigateurs, Typescript fera en sorte d'avoir une rétro compatibilité avec des versions inférieures (ES 5, ES 6, etc)

Le source TS books-list.component.ts modifié :

import {Component, OnDestroy, OnInit} from '@angular/core';
import {SubSink} from '../../services/subsink';

import {finalize} from "rxjs/operators";
import {Book, BookService} from "../../services";

@Component({
  selector: 'app-books-list',
  templateUrl: './books-list.component.html',
  styleUrls: ['./books-list.component.css']
})
export class BooksListComponent implements OnInit, OnDestroy {
  subSink = new SubSink();
  books: Book[];
  loading = false;

  constructor(private bookSvc: BookService) { }

  ngOnInit(): void {
  }

  fetchBooks(event) {
    this.loading = true;
    this.books = [];
    this.subSink.sink = this.bookSvc
      .fetchAll().pipe(finalize(() => this.loading = false))
      .subscribe((books) => {
        this.books = books;
      });
  }

  ngOnDestroy(): void {
    this.subSink.unsubscribe();
  }
}

constructor() : le constructeur de l'objet BooksListComponent, initialisé par "typescript", c'est ici que l'on injecte notre service BookService, il sera automatiquement instancié
au click, la méthode fetchBooks() est appelée, dans celle-ci on opère les actions suivantes
- loading à True : automatiquement le composant s'active grâce au *ngIf, pour une indication à l'utilisateur que c'est en train de charger
- consommer l'API books : on s'inscrit via un subscribe() à la méthode fetchAll() de l'instance bookSvc. Cela suit le pattern Observer. En effet, dans fetchAll(), nous utilisons httpClient.get() qui renvoie un Observable sur lequel l'on peut s'abonner / souscrire via un subscribe(). Dès que les données arrivent, le get() enverra un "signal" et les transmettra au subscribe, il ne reste plus qu'à les intercepter, les stocker dans books et automatiquement, via le data binding, la boucle *ngFor pourra itérer dessus. Les erreurs ne sont pas traitées dans cet exemple, subscribe permet de le faire via une seconde fonction anonyme subscribe((data), (error))
- le pipe fait parti de RxJS et permet de combiner des opérateurs de RxJs. Dans notre cas, on utilise l'opérateur finalize() qui a pour effet qu'à la fin de l'observation, le loading soit mis à false, ce qui aura pour effet de cacher le mat-progress-bar, que l'appel ait réussi ou non, comme un finally lors d'un try en C#, il y passera forcément. Le pipe peut intégrer bon nombre d'autres opérateurs que je vous laisse découvrir
On a une interface supplémentaire : OnDestroy, la méthode implémentée ngOnDestroy() sera alors automatiquement appelée lors de la destruction du composant par Angular, comme en C# ou autre, cela permet d'effectuer le ménage pour éviter d'avoir des références d'objets, ici on se désabonne des souscriptions aux observables (très important ! pour ne pas avoir d'effets de bords indésirables). J'utilise une classe utilitaire SubSink qui facilite l'ajout et le désabonnement aux Observable() créés.

Composant app-author-display

Le component app-books-list utilise dans sa vue un autre component que l'on va créer : qui est chargé d'afficher l'auteur du livre. app-books-list lui injecte directement l'auteur (author_obj) à l'aide de [author]="book?.author_obj" qui est un @Input côté app-author-display, charge ensuite à app-author-display de l'afficher.

Ce composant affichera l'auteur à l'aide d'un mat-chip. Côté TS, on voit un décorateur @Input() sur la propriété author. Cela permet une communication du composant père vers son fils, le père pourra injecter une valeur à l'aide d'un attribut entre [] sur le composant fils, cette valeur sera alors interceptée grâce à l'Input contenu dans le fils.

<app-author-display [author]="valeur"></app-author-display>

import {Component, Input, OnInit} from '@angular/core';
import {Author} from '../../../services';

@Component({
  selector: 'app-author-display',
  templateUrl: './author-display.component.html',
  styleUrls: ['./author-display.component.css']
})
export class AuthorDisplayComponent implements OnInit {
  @Input() author: Author;

  constructor() { }

  ngOnInit(): void {
  }

}

La vue, dès réception de la propriété author, l'objet sera affiché côté vue grâce à

{{author?.first_name}} {{author?.last_name}}

on appelle cela le data binding : toute modification de author dans le TS sera mis à jour côté vue et vis-versa, et cela de façon automatique, un gain de temps non négligeable.

<mat-chip-list>
  <mat-chip color="warn">{{author?.first_name}} {{author?.last_name}}</mat-chip>
</mat-chip-list>

Composant app-root (app.component)

J'ai aussi créé 2 autres composants que vous retrouverez dans les sources : app-header qui utilise le mat-toolbar et app-footer, on peut ainsi composer un layout propre de notre application, le composant principal app-root (app.component) ressemble maintenant à cela, avec notre composant app-books-list qui liste les livres

<div fxLayout="column" fxLayoutGap="10px" fxFlexFill>
  <div>
    <app-header></app-header>
  </div>
  <div fxLayoutAlign="center center">
    <div fxFlex="70">
      <app-books-list></app-books-list>
    </div>
  </div>
  <div fxFlexOffset="auto">
    <app-footer></app-footer>
  </div>
</div>

Le composant app-root est mis dans la (seule, SPA !) page index.html que je mets ici

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Library</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
  <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500&amp;display=swap" rel="stylesheet">
  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
  <link rel="manifest" href="manifest.webmanifest">
  <meta name="theme-color" content="#1976d2">
</head>
<body>
  <app-root></app-root>
  <noscript>Please enable JavaScript to continue using this application.</noscript>
</body>
</html>

Conclusion et sources

Nous avons vu les services (singletons !), les composants / components, et quelques composants Material et opérateurs RxJS.

Dans le prochain article, nous continuerons sur notre lancée et nous ferons en sorte de pouvoir éditer les livres et auteurs avec des interfaces un peu plus user friendly que l'admin Django, un peu de refactoring en utilisant la POO qu'offre Typescript et étudier une data-table de type mat-tab pour lister les auteurs et aussi agir dessus (tri, pagination, recherche). Nous aborderons aussi le système de routing, et nous irons plus loin sur opérateurs RxJS.

Les sources complets de cet article sont disponibles sur le dépôt "library",
à la branche django-drf-angular-3.1

Django & DRF 101, initialisation de l'environnement : virtualenv & docker

DUVAL Olivier — Wed, 19 Feb 2020 17:13:01 +0000

Note Bene

Dans la suite de l'article, le serveur d'application Web django pourra fonctionner selon le type d'environnement :

http://localhost:8000 dans le cas du virtualenv
http://plateform dans le cas de containers Docker

Environnement django sur un poste de développement

avec virtualenv
avec docker

Dans cet article, je vais axer sur l'installation de Django et de modules sur un poste de développement, en local, via virtualenv et docker.

On se basera sur la version 3.0.6 de django et la 3.11.x de DRF et quelques modules utiles.

[EDIT] Le billet se basait initialement sur une version django 2.2.11, pour passer en django 3.0, des modules ont dû être modifiés car plus maintenus : django-rest-swagger => drf-yasg (le staticfiles utilisé sur django-rest-swagger n'est plus valable en django 3.0 voir les modules retirés en 3.0 ou la réponse
answer re: Django TemplateSyntaxError - 'staticfiles' is not a registered tag library

Apr 30 '19

388
If you have any of the following tags in your template:
{% load staticfiles %}
{% load static from staticfiles %}
{% load admin_static %}
Then replace it with:
{% load static %}
You have to make this change because {% load staticfiles %} and {% load admin_static %} were…
Open Full Answer
djangorestframework-jwt => drf-jwt (il y a aussi simplejwt mais drf-jwt permet l'impersonnalisation que nous verrons dans un article ultérieur)

Le répertoire de travail est projet

le requirements.txt utilisé dans les 2 méthodes

django==3.0.4
djangorestframework==3.11.0
drf-jwt==1.15.1
django-filter==2.2.0
django-cors-headers==3.2.1
coreapi==2.3.3
coreapi-cli==1.0.9
requests==2.20.0
django-extensions==2.2.9
django-debug-toolbar==2.2
drf-yasg==1.17.1

virtualenv

En utilisant virtualenv.

Dans un nouveau répertoire :

$ mkdir projet && cd projet

Le nom env, derrière virtualenv, est arbitraire, c'est le nom de l'environnement virtuel, cela pourrait être myenv, projet_truc, etc

$ virtualenv env

$ source vend/bin/activate

ou sous Windows :

$ source env/Scripts/activate

pour désactiver l'environnement virtuel : $ deactivate

Installation des packages à la main :

$ pip install django==3.0.4
$ pip install djangorestframework==3.11.0
$ pip install django-filter==2.1.0
$ ...

ou par un fichier requirements.txt qui contient les packages que l'on souhaite installer pour les utiliser par la suite

$ pip install -r requirements.txt

L'environnement est prêt, un

$ python manage.py runserver

permet de lancer le serveur sur le port 8000 (http://127.0.0.1:8000/)

docker

A mon sens, c'est le plus adapté en équipe, l'objectif étant d'élaborer des images qui peuvent être partagées au sein de différentes stations de travail, l'environnement sera uniforme pour tous :

du frontal (nginx)
du serveur d'applications (django et des modules) et "monter" les sources dedans pour l'exécuter
si on utilise un SGBD (Postgresql par exemple), un containeur postgresql

Une requête HTTP suivra le chemin suivant : navigateur --> nginx --> django

$ mkdir projet && cd projet
$ mkdir docker && cd docker

A partir du répertoire docker, on aura les fichiers suivants, à créer

$ find .
.
./build.sh
./docker-compose.yml
./Dockerfile
./nginx
./nginx/conf.d
./nginx/conf.d/plateform.conf
./requirements.txt

créer l'image : exécute la commande docker build avec comme source le fichier Dockerfile qui contient les instructions de création de l'image django.

Source du Dockerfile, basé sur une image python 3.7, le port exposé à partir du container sera le 8100

FROM python:3.7-slim-buster
RUN apt-get clean
RUN apt-get update
RUN apt-get install -y libsasl2-dev python-dev libldap2-dev libssl-dev \
    libfontconfig1 libxrender1 unzip \
    libfreetype6 libc6 zlib1g libpng-dev\
    libxtst6 libtiff5-dev libjpeg62-turbo-dev zlib1g-dev libfreetype6-dev fontconfig libxml2-dev libxslt1-dev gettext \
    libaio1 libaio-dev build-essential \
     && mkdir /code && mkdir /static 
RUN apt-get clean
ENV PYTHONIOENCODING=UTF-8
WORKDIR /code
COPY ./requirements.txt requirements.txt
RUN pip install --upgrade pip && pip install -r requirements.txt
RUN apt-get install -y python3-lxml python3-cffi libcairo2 libpango1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info libcairo2 && apt-get -y clean
ADD . /code
ENV TZ=Europe/Paris
RUN apt-get update && apt-get install -y cron
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

le fichier build.sh: crée à partir du Dockerfile une image api-plateform:latest

#!/usr/bin/env bash
docker build -f Dockerfile -t api-plateform:latest .

$ ./build.sh

L'image est créée

$ docker image ls -a |grep api-pla
api-plateform                                  latest                 bda692c67a29        27 hours ago        782MB

ajouter à votre hosts un alias plateform

127.0.0.1       localhost  plateform

démarrer les containers grâce au docker-compose.yml qui décrit les services (container) à démarrer

Le docker-compose.yml qui sert au démarrage des différents containeurs : nginx, le serveur d'applications django :

version: '3.1'
services:
  api-plateform:
    image: api-plateform:latest
    container_name: api-plateform
    command: python3 manage.py runserver 0.0.0.0:8110
    volumes:
    - ../backend:/code
    networks:
    - api-plateform

  nginx-plateform:
    image: nginx
    container_name: nginx-plateform
    restart: "no"
    depends_on:
      - api-plateform
    ports:
     - 80:80
    networks:
     - api-plateform
    volumes:
     - ./nginx/conf.d/plateform.conf:/etc/nginx/conf.d/plateform.conf
     - ../log/:/var/log/nginx/

networks:
  api-plateform:

le fichier de configuration NGINX qui permet de natter le 8100 du containeur vers le port 80 pour l'extérieur, fichier nginx/conf.d/plateform.conf

server {
    listen 80;
    server_name plateform;
    error_log /var/log/nginx/error.log;

    access_log /var/log/nginx/access.log;
    client_body_buffer_size 10m;
    client_max_body_size 10m;
    client_body_timeout 120s;

    location / {
         proxy_pass http://api-plateform:8110/;
         proxy_redirect     off;
         proxy_set_header   Host             $host;
         proxy_set_header   X-Real-IP        $remote_addr;
         proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
         proxy_set_header   X-Forwarded-Protocol "http";
    }
}

$ docker-compose up
Creating network "docker_api-plateform" with the default driver
Creating api-plateform ... done
Creating nginx-plateform ... done
Attaching to api-plateform, nginx-plateform
api-plateform      | Watching for file changes with StatReloader

Le site est accessible par http://plateform

Django & DRF 101, partie 2 : DRF & API 101

DUVAL Olivier — Tue, 18 Feb 2020 13:34:55 +0000

Dans la 1ère partie, nous avons vu une introduction à l'ORM de Django avec ses capacités.

Cette 2ème partie sera consacrée à une introduction à DRF qui nous permettra de développer une API, API qui pourra être exploitée dans une application de type Angular (ou toute autre SPA).

Les sources se trouvent sur le repository https://github.com/zorky/library : l'application et le serveur d'applications containérisé (Docker).

Sommaire

Nota Bene
Préparation de l'environnement
Initialisation Django
Modèles
Admin
DRF
- REST
  - Architecture REST
  - API
- DRF initialisation
- 1ères APIs avec DRF :
  - Serializers et viewsets
    - Serializers
    - Nested serializers / serializers imbriqués
    - Viewsets
  - Actions
- Pagination, filtres et recherche avec DRF
  - Pagination
  - Recherche et Filtres
    - Filtres personnalisés
  - Tri

Note Bene

Dans la suite de l'article, le serveur d'application Web django pourra fonctionner selon le type d'environnement :

http://localhost:8000 dans le cas du virtualenv
http://plateform dans le cas de containers Docker

Utiliser la bonne url selon votre environnement. Dans la suite de l'article si j'utilise http://plateform/, à remplacer par http://localhost:8000 si vous êtes en environnement virtualenv

Préparation de l'environnement

Voir l'article en question

On se basera sur la version 3.0.4 de django et la 3.11.x de DRF et quelques modules utiles.

Django et applications

Initialisation

Django peut fonctionner en mode "plateforme" c'est à dire que vous créez un projet dans lequel vous allez créer des applications, toutes partageront la même base de données (une convention est prise alors pour le nommage des tables de la forme application_table), les configurations, "utilisateur" (au sens user de django) sont aussi partagés, ça a le mérite de mutualiser l'ensemble : pour le développement, les déploiements et l'usage d'éléments communs (serveur d'applications, authentification, "utilisateur" django, configs, etc) sans reproduire l'environnement pour chaque application.

La commande manage.py gère ce type de création.

Création du projet commun :

$ django-admin startproject backend
$ cd backend

on aura l’arborescence et les fichiers suivants de créer dans backend

manage.py
backend/
    __init__.py
    settings.py
    urls.py
    wsgi.py

Créer notre api que l'on nommera api_library :

$ django-admin startapp api_library

on aura ces fichiers de créer dans api_library

migrations/
    __init__.py
__init__.py
admin.py
apps.py
models.py
tests.py
views.py

A la fin des manipulations, on a alors l'arborescence suivante, backend qui est le coeur de django et api_library :

./api_library
./api_library/admin.py
./api_library/apps.py
./api_library/migrations
./api_library/migrations/0001_initial.py
./api_library/models.py
./api_library/serializers.py
./api_library/tests.py
./api_library/urls.py
./api_library/views.py
./api_library/__init__.py
./backend
./backend/settings.py
./backend/urls.py
./backend/webapi.py
./backend/wsgi.py
./backend/__init__.py
./db.sqlite3
./manage.py
./__init__.py

On initialise notre plateforme :

les migrations django (par défaut, django utilise sqlite, cela sera très bien en local), cela va créer toutes les tables dont Django a besoin

$ python manage.py migrate
Operations to perform:
  Apply all migrations: admin, auth, contenttypes, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying admin.0001_initial... OK
  Applying admin.0002_logentry_remove_auto_add... OK
  Applying admin.0003_logentry_add_action_flag_choices... OK
  Applying contenttypes.0002_remove_content_type_name... OK
  Applying auth.0002_alter_permission_name_max_length... OK
  Applying auth.0003_alter_user_email_max_length... OK
  Applying auth.0004_alter_user_username_opts... OK
  Applying auth.0005_alter_user_last_login_null... OK
  Applying auth.0006_require_contenttypes_0002... OK
  Applying auth.0007_alter_validators_add_error_messages... OK
  Applying auth.0008_alter_user_username_max_length... OK
  Applying auth.0009_alter_user_last_name_max_length... OK
  Applying auth.0010_alter_group_name_max_length... OK
  Applying auth.0011_update_proxy_permissions... OK
  Applying sessions.0001_initial... OK

on crée un utilisateur pour l'admin :

$ python manage.py createsuperuser 
Username (leave blank to use 'root'): admin
Email address: admin@gmail.com
Password:
Password (again):
The password is too similar to the username.
This password is too short. It must contain at least 8 characters.
This password is too common.
Bypass password validation and create user anyway? [y/N]: y
Superuser created successfully.

Lançons le serveur

$ python manage.py runserver

par défaut il est accessible sur http://127.0.0.1:8000

Arrêtons le et créons au moins un utilisateur pour accéder à l'admin Django : l'admin de django permet d'accéder à la gestion de vos données de façon simple, je l'utilise souvent pour, en développement, saisir quelques données avant d'avoir à développer les interfaces côté frontend (en Angular ou autre), pratique

Accédons à l'URL http://127.0.0.1:8000/admin en se connectant avec le compte précédemment créé, une interface apparaît pour une gestion de groupes ou d'utilisateurs, cette interface permet aussi facilement d'utiliser l'admin pour une application pour avoir des formulaires en ligne de nos entités et les garnir sans passer par la ligne de commande comme vue dans la partie 1 sur l'ORM avec shell_plus.

Amusons-nous avec quelques modèles

L'objectif est de schématiser une librairie : livres et leur auteur, ce qui donne : Book * --- 1 Author

from django.db import models

class TimeStampedModel(models.Model):
    """
    Classe utilitaire, champs dt_created / dt_updated
    """
    dt_created = models.DateTimeField(auto_now_add=True)
    dt_updated = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True

class Author(TimeStampedModel):
    first_name = models.CharField(max_length=50, null=False, blank=False)
    last_name = models.CharField(max_length=50, null=False, blank=False)

    def __str__(self):
        return '{} {}'.format(self.first_name, self.last_name)

class Book(TimeStampedModel):
    name = models.CharField(max_length=100, null=False, blank=False, db_index=True)
    nb_pages = models.IntegerField()

    author = models.ForeignKey(Author, related_name='books', null=False, on_delete=models.CASCADE)

    enabled = models.BooleanField(default=True, help_text='disponible ou non')

    def __str__(self):
        return '{} : {}'.format(self.name, self.author)

La propriété blank sert pour les formulaires Django (dans l'admin que nous voyons plus bas par exemple), le champ est donc optionnel.
str permet de surcharger ce que l'on souhaite afficher lorsque l'on fait un

print(instance_author)

il affichera alors la concaténation de first_name et last_name sinon par défaut, django affiche la clé id

Créons les migrations et les tables

$ python manage.py makemigrations api_library
Migrations for 'api_library':
  api_library\migrations\0001_initial.py
    - Create model Author
    - Create model Book

$ python manage.py migrate
Operations to perform:
  Apply all migrations: admin, api_library, auth, contenttypes, sessions
Running migrations:
  Applying api_library.0001_initial... OK

Admin

Ajoutons la possibilité d'ajouter des auteurs et livres grâce à des formulaires en utilisant l'admin django.

Il suffit, dans le fichier api_library/admin.py de déclarer les modèles de la sorte

from django.contrib import admin

from .models import Author, Book

admin.site.register(Author)
admin.site.register(Book)

En se connectant sur http://127.0.0.1:8000/admin apparaît alors une interface pour gérer des auteurs et livres, le CRUD (ajout, modification, suppression), c'est très pratique au démarrage d'un projet ou de nouveaux modèles pour avoir de la donnée.

DRF & API

Django REST Framework est un module compatible avec Django qui permet de développer des API REST assez rapidement.

REST

Architecture REST

REST est un paradigme / une architecture d'échange (service Web) entre un client (navigateur dans la plupart des cas) et un serveur, en se basant sur HTTP, décrit par Roy Fielding dans sa thèse (chapitre 5).

REST se base sur l'antique protocole HTTP :

verbes HTTP pour la communication client vers le serveur : GET (obtenir un ou des éléments), POST (créer un élément), PUT (modifier un élément), DELETE (supprimer un élément), PATCH (modifier une partie d'un élément) (et OPTIONS que nous verrons plus tard), ces verbes HTTP sont utilisés conjointement à des URLs côté client (par exemple : GET https://domain.ntld/api/todolist)
codes HTTP pour les acquittements (ACK) entre le serveur et le client utilisateur : 2xx, 4xx, 5xx, ...

REST est sans état (ou stateless) : pour résumer, tout est porté par l'URL de l'API (demande de la ressource, pagination, identité du demandeur, etc), autrement dit, la notion de session n'existe pas, pas de stockage côté serveur (a contrario des modèles clients / serveurs habituels de type MVC ou autre), si une information est gardée, elle le sera côté client

REST a été créé pour palier à certains défauts des techniques antérieures utilisées et faciliter l'échange de données dans un monde où l'échange et l'interopérabilité entre systèmes (entre un client et un serveur) sont devenus proéminents.

Ces échanges "REST" s'effectuent la plupart du temps au format JSON qui est une notation Javascript pour décrire des objets, objets qui seront utilisés pour l'échange de données en entrée ou en sortie entre 2 parties : le client et le serveur, le lien entre ces parties étant les APIs. Comme nous le verrons ci-après, l'avantage de JSON vs. XML est que c'est un format natif Javascript qui pourra être interprété directement par le moteur JS du navigateur sans avoir besoin de librairie tierce pour le faire.

API : à quoi sert une API et quelques rappels historiques

Une architecture APIs est une architecture "backoffice", c'est à dire, toute la mécanique / logique est portée par les APIs, reste à développer des frontaux devant pour adresser ces APIs : applications Web, une application Mobile, une SPA, ou des scripts / routines, etc, une API ne s'occupe pas de la manière dont sera présentée la donnée (la vue), charge aux frontaux de l'implémenter.

Un schéma qui résume très bien (pris sur https://data-flair.training/blogs/django-rest-framework/)

API publiques

La majeure partie des plateformes (Dropbox, Amazon, Google, etc) proposent dorénavant des APIs qui permettent d'interagir avec ces dernières et l'interopérabilité entre plateformes (notamment de l'échange de données), ce qui facilite l'intégration de leurs services dans d'autres applications Web, pour y apporter plus de services à l'utilisateur.

Avant cela, afin d'intégrer de la donnée externe à une application, l'un des moyen de faire était soit d'interroger directement la base de données, ce qui est bien évidemment impossible avec Amazon par exemple et cela pose également des soucis "d'abstraction" de la donnée (ie : connaître le schéma de la base et de ses tables, quid de l'évolution de ce schéma, etc), soit d'utiliser SOAP pour échanger à une époque pas si lointaine, SOAP étant fait à la base surtout pour de l'échange entre serveurs (un serveur d'application JEE ou .NET ou ...) et reste un format inapproprié pour l'échange entre client (entendre navigateur) et serveur : par défaut le format d'échange de SOAP renvoie du XML, format non natif Javascript, contrairement à JSON, ce qui oblige l'usage de librairie pour transformer la donnée, et une "complexité" (à cause du WSDL) de SOAP pour les plateformes n'étant pas natives "SOAP / XML" (comme .NET ou J2EE) : enveloppe / entête nécessaires, souci de cache, WSDL "complexe" pour décrire les entrées / sorties du service.

API privées

Avec l’avènement de l'utilisation d'Ajax à partir des années 2000 et de cette volonté d'améliorer l'expérience utilisateur sur les interfaces Web (UX), cette UX étant portée principalement par Javascript / Ajax : toute la page n'est pas rechargée, seules des parties de la page sont mises à jour, souvent avec des effets (spinner d'attente, accordéon, autocompletion, etc), ce qui donne une impression d'être sur une application bien plus réactive.

Pour cela, on utilisait ou on utilise bien souvent la libraire jQuery qui s'est imposée comme librairie pour les appels "Ajax" (à l'époque, l'objet utilisé pour faire des appels Ajax n'était pas standardisé sur les navigateurs, IE, Chrome, Firefox, cela permettait d'avoir une couche d'abstraction pour le développeur sans se soucier du navigateur) puis pour la manipulation du DOM grâce aux sélecteurs (pouvoir rechercher un élément "HTML" dans la page pour l'afficher, le cacher, lui ajouter d'autres éléments, etc) : on développait des SPA sans vraiment en faire : les pages se rechargeaient malgré tout avec une certaine latence (car utilisation d'un serveur d'application bien souvent MVC), le code devenait très vite du code spaghetti à cause bien souvent d'une mauvaise utilisation de Javascript (via des fonctions et non de la POO) et de l'excès de jQuery : des sélecteurs partout, des fonctions javascript éparpillées dans de multiples fichiers JS inclus ou non dans les pages, ou côté MVC, avec des vues partielles et des modèles injectés comme on pouvait. L'entropie de ce type d'application était forte : maintenabilité et évolutivité réduites qui peuvent devenir complexes, sans compter les régressions et du côté utilisateur, un ressenti et une UX perfectible.

De là, sont nés des frameworks / librairies de type "SPA" pour améliorer les critiques sur les applications "anciennes générations" à base de jQuery / MVC (appelés aussi MPA : Multi Pages Applications) : Ember, KnockoutJS, VueJS ou ReactJS et bien sûr Angular.

Le principe d'une SPA est de se baser sur des services REST ou APIs pour obtenir, et/ou mettre à jour la donnée, sous forme de multiples appels "Ajax" et de l'usage du binding (attachement) automatique entre ces données et la vue pour les afficher. Les derniers frameworks ont également une approche components / composants, qui introduit un des principes de SOLID en POO : la responsabilité unique ou souhaitée : un composant répond à un besoin et un seul (par exemple, un composant d'entêtes, d'autocompletion, de table pour afficher des éléments, etc) et souvent, réutilisables.

Schéma (tiré de cet article) qui explique la différence entre les MPAs et le SPAs

Le propre d'une SPA est de charger l'application en une seule fois ou en différé et que cela soit transparent pour l'utilisateur de l'application : cela amène une fluidité de navigation et une UX bien supérieure à des applications "classiques".

Pour ces APIs, dans l'écosystème Django, il existe un module qui va nous permettre de développer ces dites APIs : Django rest framework et c'est ce nous allons voir dans les prochaines parties.

DRF initialisation

Pour l'utilisation de DRF, nous aurons besoin d'un ensemble de modules à installer et à utiliser (voir le requirements.txt de l'initialisation)

Dans backend/settings.py, la partie INSTALLED_APPS contient les modules qui seront chargés : rest_framework mais aussi rest_framework_swagger ou drf-yasg qui nous permettra de documenter nos APIs, django_filters est un module tiers très puissant qui nous servira à faire des filtres de recherche par la suite et bien entendu notre module api_library :

INSTALLED_APPS = [
    'rest_framework',
    'rest_framework_swagger',

    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django_extensions',

    'django_filters',

    'api_library',
]

APIs

Avec DRF, un triptyque permet simplement de créer une API avec : le modèle (de Django), le Serializer, la Viewset, on se basera sur le plus complet le ModelViewSet, l'URL et optionnellement le FilterSet.

Serializers et viewsets

Serializers

Un serializer servira à sérialiser ou désérialiser la donnée en JSON (entrées / sorties d'une API) : l'application envoie du JSON et réceptionne du JSON.

Une viewset servira pour traiter les requêtes HTTP pour les APIs : un viewset qui répondra à 80 % de nos besoins est le ModelViewSet, il traitera le GET, POST, PUT, DELETE "automatiquement" (le CRUD de nos modèles), nous verrons qu'il existe aussi d'autres classes plus restrictives (pour uniquement du GET ou du POST, etc).

Dans api_library, créer un fichier serializers.py pour définir nos serializers sur nos modèles Author et Book :

# api_library/serializers.py

from rest_framework import serializers

from .models import Author, Book

class AuthorSerializer(serializers.ModelSerializer):
    class Meta:
        model = Author
        fields = '__all__'

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['id', 'label']

la class Meta permet de définir le serializer (les méta-données), parmi les plus communs :

model : le modèle utilisé par DRF pour sérializer / désérializer
fields : les champs qui seront inclus dans le JSON, le mot clé 'all' permet d'inclure tous les champs du modèle automatiquement
exclude : les champs à exclure - attention, ne doit pas être utilisé en même temps que fields, il prendra donc tous les champs moins les exclude
read_only_fields : les champs qui ne sont pas à "écrire" lors de l'envoi / de la réception du JSON

Lorsque l'on interrogera les Books (via http://plateform/library/books/ ou http://plateform/library/books/1), avec la pagination on aura comme résultat du serializer BookSerializer, un Book en JSON aura la forme suivante

{
   "id": 1,
   "dt_created": "2020-02-22T15:57:26.934127",
   "dt_updated": "2020-02-22T15:57:26.934149",
   "name": "Django primer",
   "nb_pages": 150,
   "enabled": true,
   "author": 1
}

Nested Serializers

Comme nous pouvons le voir sur la partie précédente et selon le schéma

Book * ----- 1 Author

le sérializer de Book, renverra le lien Author avec sa clé : "author": 1, ou "1" est l'id d'author qui est lié à Book (un livre a un auteur).

Egalement, lorsque l'on demande un "Author", on pourrait avoir besoin de sa liste de livres directement sous forme d'objects.

Il peut être intéressant de renvoyer tout l'objet Author, pour afficher directement sur le livre toute l'information de son auteur (un nester serializer ou serializer embarqué)

On modifie le serializer BookSerializer pour ajouter l'objet Author :

class BookSerializer(serializers.ModelSerializer):
    author_obj = AuthorSerializer(source='author', read_only=True)

    class Meta:
        model = Book
        fields = '__all__'

source est à la propriété de jointure utilisé dans le modèle Book (author = models.ForeignKey(Author, related_name='books', null=False, on_delete=models.CASCADE)), elle est obligatoire dans notre cas car la propriété renvoyée dans le serializer se nomme author_obj sinon elle devient optionnelle (si on avait écrit par exemple author = AuthorSerializer(read_only=True))
read_only car cela ne servira qu'à la consultation, DRF ne peut écrire directement des nested serializer en base, une autre technique sera alors utilisée

Lors du requêtage (http://plateform/library/books/ ou http://plateform/library/books/1), on aura alors le résultat suivant, avec intégrer l'auteur (propriété author_obj)

{
    "id": 1,
    "author_obj": {
        "id": 1,
        "dt_created": "2020-02-22T15:56:55.547391",
        "dt_updated": "2020-02-22T15:56:55.547413",
        "first_name": "Olivier",
        "last_name": "DUVAL"
    },
    "dt_created": "2020-02-22T15:57:26.934127",
    "dt_updated": "2020-02-22T15:57:26.934149",
    "name": "Django primer",
    "nb_pages": 150,
    "enabled": true,
    "author": 1
}

A l'inverse, on pourrait avoir la liste des livres d'un auteur directement dans le serializer AuthorSerializer, on aura alors le code suivant :

class BookSimpleSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = '__all__'

class AuthorSerializer(serializers.ModelSerializer):
    books = BookSimpleSerializer(many=True, read_only=True)

    class Meta:
        model = Author
        fields = '__all__'

class BookSerializer(serializers.ModelSerializer):
    author_obj = AuthorSerializer(source='author', read_only=True)

    class Meta:
        model = Book
        fields = '__all__'

Dans ce cas, la création d'un autre serializer (BookSimpleSerializer) est obligatoire pour pouvoir l'utiliser dans AuthorSerializer car BookSerializer est en-dessous de AuthorSerializer, ceci pour éviter de la récursion à l'infinie (author -> books -> author -> books -> etc).

many=True permet de répondre au rendu de plusieurs livres pour un auteur (pour rappel, la déclaration dans Book est author = models.ForeignKey(Author, related_name='books', null=False, on_delete=models.CASCADE)), books de books = BookSimpleSerializer(many=True, read_only=True) représente la relation inverse déclarée dans related_name.

Lorsque l'on interroge http://plateform/library/authors/1/ , on aura le JSON suivant, l'auteur avec la liste de ses livres :

{
    "id": 1,
    "books": [
        {
            "id": 1,
            "dt_created": "2020-02-22T15:57:26.934127",
            "dt_updated": "2020-02-22T15:57:26.934149",
            "name": "Django primer",
            "nb_pages": 150,
            "enabled": true,
            "author": 1
        },
        {
            "id": 3,
            "dt_created": "2020-02-22T15:57:51.851990",
            "dt_updated": "2020-02-22T15:57:51.852012",
            "name": "Angular primer",
            "nb_pages": 325,
            "enabled": true,
            "author": 1
        }
    ],
    "dt_created": "2020-02-22T15:56:55.547391",
    "dt_updated": "2020-02-22T15:56:55.547413",
    "first_name": "Olivier",
    "last_name": "DUVAL"
}

ATTENTION : les "nested serializers" feront un appel / des appels vers l' / les entité(s) pour obtenir les données, on pensera donc à utiliser le select_related (pour les cardinalités 1) ou le prefetch_related (pour les many) dans la queryset de la viewset que nous voyons ci-après. Les "nested" engendrent aussi plus de données qui transitent via l'API.

Viewsets

Un viewset est une vue qui va servir pour l'API, le plus simple étant le ModelViewSet qui fera le CRUD : GET, POST, PUT, DELETE, en se servant d'un serializer (pour la transformation JSON des entrées et des sorties), d'une queryset (la requête par défaut),. Dans dans api_library, le fichier views.py contiendra :

# api_library/views.py

from rest_framework import viewsets
from rest_framework.permissions import AllowAny

from .models import Author, Book
from .serializers import AuthorSerializer, BookSerializer

class AuthorViewSet(viewsets.ModelViewSet):
    queryset = Author.objects.prefetch_related('books').all()
    serializer_class = AuthorSerializer
    permission_classes = [AllowAny]


class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.select_related('author').all()
    serializer_class = BookSerializer
    permission_classes = [AllowAny]

queryset : est la queryset par défaut utilisée pour retrouver les enregistrements, remarquez qu'on utilise les select_related ou prefetch_related pour optimiser le requêtage comme vu sur https://dev.to/zorky/django-drf-101-partie-1-2p2#optimisations
serializer_class : le serializer par défaut à utiliser pour la sérialisation / dé-sérialisation des données, on peut également en préciser dynamiquement, patience, nous verrons cela dans un futur article
permission_classes : les droits d'accès à l'API, ici AllowAny pour dire qu'elle est publique, on pourrait également configurer les permissions par défaut de toutes les viewset via le backend/settings, section REST_FRAMEWORK, cela s'appliquera à toutes les viewsets sans avoir besoin de permission_classes à l'intérieur. Si vous souhaitez qu'au moins les APIs aient besoin d'une authentification, il suffira d'utiliser IsAuthenticated à la place. Les permissions sont également personnalisables, c'est à dire que l'on peut imaginer des rôles applicatifs, rôles qui seront ensuite utilisés pour accéder à telle ou telle API (APIs de backoffice, de frontoffice, etc)

REST_FRAMEWORK = {
 'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.AllowAny',
    ]
...
}

Lorsqu'on regarde les sources de ModelViewSet, la class se compose en une multitude de "mixin" qui représente le CRUD et une pour la tuyauterie. On peut utiliser d'autre viewset génériques spécialisés autre que le ModelViewSet pour répondre à des besoins spécifiques d'API : CreateAPIView (POST uniquement), UpdateAPIView (PUT uniquement), ListAPIView (GET liste), RetrieveAPIView (GET d'un objet), DestroyAPIView (DELETE uniquement), ListCreateAPIView, RetrieveUpdateAPIView, RetrieveDestroyAPIView, RetrieveUpdateDestroyAPIView, voir l'ensemble des views disponibles sur le site de DRF.

class ModelViewSet(mixins.CreateModelMixin,
                   mixins.RetrieveModelMixin,
                   mixins.UpdateModelMixin,
                   mixins.DestroyModelMixin,
                   mixins.ListModelMixin,
                   GenericViewSet):
    """
    A viewset that provides default `create()`, `retrieve()`, `update()`,
    `partial_update()`, `destroy()` and `list()` actions.
    """
    pass

Dans api_library, créer un fichier urls.py, Les viewset sont attachées à une URL, précisées dans urls.py qui contiendra le code suivant

# coding=utf-8
# api_library/urls.py

from django.conf.urls import url, include
from rest_framework import routers
from . import views

router = routers.DefaultRouter()
router.register(r'authors', views.AuthorViewSet, 'authors')
router.register(r'book', views.BookViewSet, 'books')

urlpatterns = [
    url(r'', include(router.urls)),    
]

Dans backend, le fichier urls.py utilisera les urls d'api_library précédemment ajoutées, et nous allons activer Swagger pour accéder et requêter notre API directement. Egalement, en mode DEBUG (en dév), on active la debug toolbar (debug_toolbar) pour obtenir de l'information sur les API (notamment le SQL), l'api de notre librairie aura la forme : http://domain.ntld/library/ :

# backend/urls.py
from django.contrib import admin
from django.conf import settings
from django.conf.urls import url, include
from django.conf.urls.static import static
from rest_framework_jwt.views import obtain_jwt_token, refresh_jwt_token, verify_jwt_token
from rest_framework_swagger.views import get_swagger_view

schema_view = get_swagger_view(title='Api plateforme')

urlpatterns = [
    url(r'^$', schema_view),
    url(r'library/', include('api_library.urls')),
    url(r'^admin/', admin.site.urls)
]

if settings.DEBUG:
    import debug_toolbar

    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
    urlpatterns = [
        url(r'^__debug__/', include(debug_toolbar.urls))
    ] + urlpatterns

Pour résumer :

des serializers dans api_library/serializers.py
des views dans api_library/views.py
des urls avec les viewsets dans api_library/urls.py
déclaration de swagger, de la debug toolbar et inclusion des urls api_library dans backend/urls.py

Aller sur http://localhost:8000 ou http://plateform , Swagger expose les APIs authors et books que l'on peut manipuler directement, basées sur les verbes HTTP d'une architecture REST

Utilisation de /library/authors/ en GET, avec le résultat JSON

ou de /library/authors/1/ (donne moi l'auteur d'identifiant 1)

La partie Request URL (par ex. http://plateform/library/authors/) peut être ouverte dans un onglet à part du navigateur, on a accès alors à la debug toolbar et notamment la partie SQL pour voir les requêtes qui sont exécutées ou d'autres informations utiles

Si l'on veut ouvrir la request URL avec un résultat uniquement en JSON (sans Swagger), il suffit de postfixer l'url avec ?format=json (http://plateform/library/authors/?format=json)

Actions

Les viewsets ModelViewSet permettent le CRUD sur un modèle, on peut les spécialiser pour avoir des "fonctions" au sein du ModelViewSet, par exemple une url de type http://plateform/library/books/disponibles/ , /disponibles/ renverra les livres uniquement disponibles, les actions permettent de répondre spécifiquement à du fonctionnel dans le détail.

Le paramètre method permet de choisir le verbe HTTP sur lequel l'action répondra (get, post, put, delete), optionnellement, on peut également utiliser le permission_classes avec une liste de permissions, cela surchargera les permissions de la viewset.

Les actions DRF sont créés grâce au décorateur @action, il en existe 2 types

une qui va chercher l'objet d'id N, l'attribut detail est à True. Action qui nécessite de passer l'id de l'objet sur lequel on va créer l'action Cela permet d'utiliser la fonction utilitaire get_object qui se chargera de nous trouver l'objet à partir du paramètre pk qui représente l'id envoyé. L'action doit renvoyer un Response, dans l'exemple si après : trouve l'objet Entite d'id pk et le renvoie

    @action(detail=True, methods=['get'])
    def ma_fonction_specialisee(self, request, pk=None):
          mon_entite: Entite = self.get_object()
          serializer = EntiteSerializer(mon_entite)
          return Response(data={serializer.data}, status=status.HTTP_200_OK)

une "générique" où le detail est à False

    @action(detail=False)
    def ma_fonction_specialisee(self, request):
        # traitement pour renvoyer de la donnée
        return Response(data={}, status=status.HTTP_200_OK)

Dans les 2, on pourra utiliser request pour retrouver des paramètres passés à la queystring (&param1=val1&param2=val2&...&parmN=valN), de la façon suivante, exemple pour retrouver param1, s'il n'existe pas, sa valeur est fixée à None

request.query_params.get('param1', None)

On pourra également tester la méthode utilisée via request.method, à savoir si c'est 'GET', 'POST', 'PUT', 'DELETE'

Pagination, filtres et recherche

Lorsque l'on développe des API ou plus généralement on interroge des listes d'objets, il est important de penser à la pagination (le fait de ne ramener qu'un ensemble de lignes (10 par exemple) d'un ensemble global de données), et aux filtres de recherche qu'on peut donner à l'utilisateur d'une application, cela contribue à l'UX.

Pagination

La pagination doit être réalisée côté base de données, plus performante bien évidemment qu'une pagination effectuée sur un ensemble d'objets en "mémoire", voir plus loin pour les requêtes.

Pour ça, DRF propose 2 options :

soit indiquer la pagination en settings, qui sera commune à toutes les APIs,
soit dans le viewset, au cas par cas

DRF propose plusieurs type de "fournisseurs" : PageNumberPagination (l'url sera de la forme &page=N&page_size=LIMIT), LimitOffsetPagination (l'url sera de la forme &limit=10&offset=5) et CursorPagination, je préfère le LimitOffsetPagination car dans le retour JSON, nous avons toutes les indications liées à la pagination, on se déplace dans les "pages" grâce au limit et optionnellement à l'offset (par défaut 0, indique le démarrage à l'enregistrement N° offset)

Par exemple, la requête http://plateform/library/authors/?limit=1&format=json retournera : on a le nombre totale en base (count: 3), la prochaine "page" avec l'offset (http://plateform/library/authors/?format=json&limit=1&offset=1) et enfin les données dans results

{
  count: 3,
  next: "http://plateform/library/authors/?format=json&limit=1&offset=1",
  previous: null,
  results: [
  {
    id: 1,
    dt_created: "2020-02-18T11:57:51.608823",
    dt_updated: "2020-02-18T11:57:51.608823",
    first_name: "Olivier",
    last_name: "DUVAL"
  }
]
}

Dans le backend/settings.py, sur la partie REST_FRAMEWORK, ajouter :

REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
'PAGE_SIZE': 10,
...
}

ou dans le viewset désiré :

from rest_framework import viewsets
from rest_framework.pagination import LimitOffsetPagination
from rest_framework.permissions import AllowAny

from .models import Author, Book
from .serializers import AuthorSerializer, BookSerializer

class AuthorViewSet(viewsets.ModelViewSet):
    queryset = Author.objects.prefetch_related('books').all()
    serializer_class = AuthorSerializer
    permission_classes = [AllowAny]

    pagination_class = LimitOffsetPagination
    page_size = 10

Dès lors, on peut utiliser la pagination en ajoutant les paramètres limit (le nombre de lignes ramené) et offset (à partir de quel ligne) à l'url : http://plateform/library/authors/?limit=5&offset=5 : donne moi la liste des auteurs à partir du 5ème et les 5 premiers de la liste, simple et efficace.

Pour les requêtes SQL générées, ouvrons sur http://plateform/library/authors/?limit=2&offset=1 la partie SQL de la debug toolbar, 2 requêtes pour les auteurs sont générées : 1 pour le comptage en base (count) et une autre pour la liste (selon le SGBD les instructions peuvent varier, ici, avec SQLite, nous avons un OFFSET et un LIMIT)

Filtres

Recherche

Lorsque l'on a des listes, on a souvent besoin de rechercher des éléments. DRF a prévu le cas grâce au SearchFilter, ajoutons filter_backends = (SearchFilter,) au viewset et les champs de recherche souhaités (ici "first_name" OU "last_name")

# api_library/views.py

import django_filters

from rest_framework import viewsets
from rest_framework.filters import SearchFilter
from rest_framework.pagination import LimitOffsetPagination, PageNumberPagination
from rest_framework.permissions import AllowAny, IsAuthenticated

from .models import Author, Book
from .serializers import AuthorSerializer, BookSerializer

class AuthorViewSet(viewsets.ModelViewSet):
    queryset = Author.objects.prefetch_related('books').all()
    serializer_class = AuthorSerializer
    permission_classes = [AllowAny]
    filter_backends =  (SearchFilter,)

    search_fields = ['first_name', 'last_name']

La requête http://plateform/library/authors/?search=aur%C3%A9%20duv cherchera sur les 2 champs précisés dans search_fields en effectuant un LIKE et un OR en permutant toutes les possibilités :

SELECT "api_library_author"."id",
       "api_library_author"."dt_created",
       "api_library_author"."dt_updated",
       "api_library_author"."first_name",
       "api_library_author"."last_name"
  FROM "api_library_author"
 WHERE (("api_library_author"."first_name" LIKE '''%auré%''' ESCAPE '\' OR "api_library_author"."last_name" LIKE '''%auré%''' ESCAPE '\') AND ("api_library_author"."first_name" LIKE '''%duv%''' ESCAPE '\' OR "api_library_author"."last_name" LIKE '''%duv%''' ESCAPE '\'))
 LIMIT 10

Attention, c'est accent sensitive mais case insensitive (duv ou DUV renverront le même résultat).

Filtres de recherche sur des champs

Autre facilité de DRF, la possibilité d'utiliser des filtres sur des champs, par exemple, pouvoir rechercher les livres ayant 150 pages, ou le nom d'un auteur égale à "DUVAL", les filtres sont cumulables, et bien entendu, si la pagination est utilisée, elle s'intégrera à la requête.

Ajoutons à filter_backends la classe DjangoFilterBackend qui active l'usage des filtres, associé à filterset_fields qui précise les champs que l'on peut filter. Les filtres de base sont stricts, un = sera utilisé.

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.select_related('author').all()
    serializer_class = BookSerializer
    permission_classes = [AllowAny]
    filter_backends = (DjangoFilterBackend, SearchFilter,)
    filterset_fields = ('name', 'nb_pages', 'author', 'author__last_name', 'author__first_name',)

Dès lors que les filtres sont mis, on peut les voir sur swagger pour les utiliser

Dès lors on peut filtrer exactement sur les champs souhaités (précisés avec filterset_fields), lors de l'utilisation de ces champs dans l'url, un ET est appliqué entre les conditions.

Par exemple, les livres de 150 pages pour l'auteur d'identifiant 1 : http://plateform/library/books/?nb_pages=150&author=1 ou les livres de 150 pages de l'auteur de nom "DUVAL" : http://plateform/library/books/?author__last_name=DUVAL&nb_pages=150

La dernière requête, en utilisant la debug toolbar donnera

SELECT "api_library_book"."id",
       "api_library_book"."dt_created",
       "api_library_book"."dt_updated",
       "api_library_book"."name",
       "api_library_book"."nb_pages",
       "api_library_book"."author_id",
       "api_library_author"."id",
       "api_library_author"."dt_created",
       "api_library_author"."dt_updated",
       "api_library_author"."first_name",
       "api_library_author"."last_name"
  FROM "api_library_book"
 INNER JOIN "api_library_author"
    ON ("api_library_book"."author_id" = "api_library_author"."id")
 WHERE ("api_library_book"."nb_pages" = '150' AND "api_library_author"."last_name" = '''DUVAL''')

Comme on peut le remarquer, dans notre exemple, les filtres s'effectuent à partir du modèle Book, on peut alors remonter vers auteur en indiquant les champs de ce modèle grâce à __ (grâce à la clé étrangère author définie dans le modèle par author = models.ForeignKey(Author, related_name='books', null=False, on_delete=models.CASCADE)) pour filtrer sur le nom ou prénom : author__last_name ou author__first_name. Attention, cela génère une requête pour aller chercher l'entité author pour ses attributs last_name / first_name, un select_related('author') est conseillé sur la queryset de la viewset.

Filtres personnalisés

Les filtres proposés permettent déjà pas mal de recherche et filtrage. DRF et django-filters permettent aussi d'en créer, la classe FilterSet permet cela en conjonction avec filterset_class que nous allons utiliser dans les viewsets.

Pour Book, on pourrait rechercher les livres entre 2 nombre de pages ou sur une liste d'auteurs (identifiants).

Création d'un filtre personnalisé pour Book et Author, dans un nouveau fichier api_libray/filters.py

from django_filters import FilterSet, filters, BaseInFilter, NumberFilter

from .models import Book, Author

class IntegerInFilter(BaseInFilter, NumberFilter):
    pass

class AuthorFilter(FilterSet):
    last_name = filters.CharFilter(lookup_expr='iexact')
    first_name = filters.CharFilter(lookup_expr='iexact')

    class Meta:
        model = Author
        fields = ['last_name', 'first_name', ]

class BookFilter(FilterSet):
    pages =  filters.RangeFilter(field_name='nb_pages')
    author_in = IntegerInFilter(field_name='author', lookup_expr='in')
    author_isnull = django_filters.BooleanFilter(field_name='author', lookup_expr='isnull')

    class Meta:
        model = Book
        fields = ['name', 'nb_pages', 'author', 'author__last_name', 'author__first_name', ]

La partie gauche représente la clé de l'url (pages ou author_in ou author_isnull, l'url sera pages=valeur ou author_in=1,2 ou author_isnull=true).

La partie droite soit l'expression de la queryset (lookup_expr="mot_cle", sera le postfix à la requête queryset.

iexact donnera champ__iexact="valeur"), soit la classe filtre spécialisée (RangeFilter dans notre exemple), si field_name n'est pas donné, il recherchera le champ de même libellé que la partie gauche (last_name par exemple).

author_isnull donnera champ__isnull=true

La class Meta permet de préciser le modèle sur lequel le filtre s'applique ainsi que les champs, optionnellement, les lookup_expr pourraient être définies dans cette partie pour chaque champ

class AuthorFilter(FilterSet):
    last_name = filters.CharFilter()
    first_name = filters.CharFilter()

    class Meta:
        model = Author
        fields = {'last_name': ['iexact'],
                  'first_name': ['iexact']}

Pour Book, on va pouvoir rechercher les libres qui ont entre N et M pages grâce au filtre RangeFilter, l'url d'interrogation sera par exemple http://plateform/library/books/?pages_min=100&pages_max=400, on peut omettre _min ou _max, la requête sera alors >= ou <= pour comparer la valeur

Requête générée

SELECT "api_library_book"."id",
       "api_library_book"."dt_created",
       "api_library_book"."dt_updated",
       "api_library_book"."name",
       "api_library_book"."nb_pages",
       "api_library_book"."author_id",
       "api_library_author"."id",
       "api_library_author"."dt_created",
       "api_library_author"."dt_updated",
       "api_library_author"."first_name",
       "api_library_author"."last_name"
  FROM "api_library_book"
 INNER JOIN "api_library_author"
    ON ("api_library_book"."author_id" = "api_library_author"."id")
 WHERE "api_library_book"."nb_pages" BETWEEN '100' AND '400'
 LIMIT 10

Pouvoir retrouver les libres d'une liste d'auteurs, author_in = IntegerInFilter(field_name='author', lookup_expr='in'), IntergerInFilter permet de surchargées BaseInFilter et NumberFilter pour préciser que ce sont des entiers que l'on attend, la requête sera alors par exemple http://plateform/library/books/?author_in=1,2

Il est à remarquer que l'on retrouve les filtres applicables sur l'interface de Swagger, en ouvrant directement les urls, par exemple http://plateform/library/books/

On pourrait aussi définir des fonctions si les règles métiers sont un peu complexes grâce au mot clé method, on accède à la queryset courante ainsi que la valeur à prendre en compte, ajoutons la possibilité pour Author de faire ?by_search=oli%20duv

from django.db.models import Q
from django_filters import FilterSet, filters, BaseInFilter, NumberFilter

from .models import Book, Author

class AuthorFilter(FilterSet):
    last_name = filters.CharFilter(lookup_expr='iexact')
    first_name = filters.CharFilter(lookup_expr='iexact')
    by_search = filters.CharFilter(method="get_by_search")

    def get_by_search(self, queryset, name, value):
        """
        Search mot à mot
        """
        words = value.split(' ')

        filters = Q()
        for word in words:
            filters |= Q(first_name__icontains=word) | Q(last_name__icontains=word)

        qs = queryset.filter(filters)
        return qs

    class Meta:
        model = Author
        fields = ['last_name', 'first_name',]

Tri

DRF permet également d'effectuer des tris dynamiquement en les précisant dans l'url. Pour cela, nous utilisons la classe OrderingFilter que l'on va ajouter à filter_backends et associé à ordering_fields qui précise quels champs sont triables, dans l'url il suffira d'utiliser ordering en précisant le champ et l'ordre (- pour DESC, rien ou + pour ASC), par exemples :

http://plateform/library/books/?ordering=name donnera un tri sur le champ name en tri ascendant (A -> Z)

SELECT "api_library_book"."id",
       "api_library_book"."dt_created",
       "api_library_book"."dt_updated",
       "api_library_book"."name",
       "api_library_book"."nb_pages",
       "api_library_book"."author_id",
       "api_library_author"."id",
       "api_library_author"."dt_created",
       "api_library_author"."dt_updated",
       "api_library_author"."first_name",
       "api_library_author"."last_name"
  FROM "api_library_book"
 INNER JOIN "api_library_author"
    ON ("api_library_book"."author_id" = "api_library_author"."id")
 ORDER BY "api_library_book"."name" ASC
 LIMIT 10

http://plateform/library/books/?ordering=-name donnera un tri sur le champ name en tri descendant (Z -> A)

SELECT "api_library_book"."id",
       "api_library_book"."dt_created",
       "api_library_book"."dt_updated",
       "api_library_book"."name",
       "api_library_book"."nb_pages",
       "api_library_book"."author_id",
       "api_library_author"."id",
       "api_library_author"."dt_created",
       "api_library_author"."dt_updated",
       "api_library_author"."first_name",
       "api_library_author"."last_name"
  FROM "api_library_book"
 INNER JOIN "api_library_author"
    ON ("api_library_book"."author_id" = "api_library_author"."id")
 ORDER BY "api_library_book"."name" DESC
 LIMIT 10

Nos viewsets deviennent

# api_library/views.py

from django_filters.rest_framework import DjangoFilterBackend

from rest_framework import viewsets
from rest_framework.filters import SearchFilter, OrderingFilter
from rest_framework.pagination import LimitOffsetPagination
from rest_framework.permissions import AllowAny

from .models import Author, Book
from .serializers import AuthorSerializer, BookSerializer

class AuthorViewSet(viewsets.ModelViewSet):
    queryset = Author.objects.prefetch_related('books').all()
    serializer_class = AuthorSerializer
    permission_classes = [AllowAny]
    filter_backends =  (DjangoFilterBackend, SearchFilter, OrderingFilter, )

    search_fields = ['first_name', 'last_name']
    filterset_fields = ('last_name',)
    ordering_fields = ('id', 'last_name',)

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.select_related('author').all()
    serializer_class = BookSerializer
    permission_classes = [AllowAny]
    filter_backends = (DjangoFilterBackend, SearchFilter, OrderingFilter,)

    search_fields = ['name', 'author__first_name', 'author__last_name']
    filterset_fields = ('name', 'nb_pages', 'author', 'author__last_name', 'author__first_name',)
    ordering_fields = ('id', 'name',)

On va pouvoir trier Author sur l'id et le last_name, et Book sur son id et le name

Si l'on souhaite préciser un tri par défaut, il suffira d'utiliser ordering qui peut être une liste de champs, à ajouter à la viewset, par exemple : ordering = ['first_name', 'last_name'] sur AuthorViewSet, triera par défaut les auteurs sur le prénom et nom et non sur leur id qui est la clé par défaut du tri pour les modèles.

On aura alors la requête suivante de générée (remarquer le ORDER BY) :

SELECT "api_library_author"."id",
       "api_library_author"."dt_created",
       "api_library_author"."dt_updated",
       "api_library_author"."first_name",
       "api_library_author"."last_name"
  FROM "api_library_author"
 ORDER BY "api_library_author"."first_name" ASC, "api_library_author"."last_name" ASC
 LIMIT 10

on aurait pu faire un tri sur first_name ASC et last_name DESC grâce au - : ordering = ['first_name', '-last_name'], cela donnera


SELECT "api_library_author"."id",
       "api_library_author"."dt_created",
       "api_library_author"."dt_updated",
       "api_library_author"."first_name",
       "api_library_author"."last_name"
  FROM "api_library_author"
 ORDER BY "api_library_author"."first_name" ASC, "api_library_author"."last_name" DESC
 LIMIT 10

La liste des APIs disponibles pour Book et Author sera disponible sur http://plateform

Dans une prochaine partie, nous verrons à débuter une application en Angular qui utilise ces APIs.

Restez connectés !