Diagramme d'architecture microservices : un exemple et sept règles pour qu'il reste lisible

Demandez à une équipe de dessiner ses microservices et vous obtiendrez souvent la même image : trente boîtes, chacune reliée à toutes les autres, des flèches sans étiquette. C'est exact, et cela ne répond à aucune question que l'on se pose. Les ingénieurs l'appellent le diagramme « étoile de la mort ».

Un diagramme d'architecture microservices utile est une suite de décisions sur ce qu'il faut montrer. Ce guide s'appuie sur un exemple, une boutique en ligne avec cinq services, et présente les sept règles qui le rendent lisible. Ces règles valent aussi bien pour cinq services que pour cinquante.

Les questions auxquelles le diagramme doit répondre

Avant de dessiner, notez les questions. Un bon diagramme de microservices répond à cinq d'entre elles d'un seul coup d'œil :

1. Par où entrent les requêtes ? Les clients, la passerelle API, les backends for frontends (BFF).
2. Quel service possède quelles données ? Chaque base de données devrait avoir exactement un propriétaire.
3. Qui appelle qui de façon synchrone ? Ces appels partagent latence et pannes.
4. Que se passe-t-il de façon asynchrone ? Les événements et les files d'attente découplent les services dans le temps.
5. Qu'est-ce qui échappe à notre contrôle ? Les prestataires de paiement, les services d'e-mail, les API de partenaires.

Si une boîte ou une flèche n'aide à répondre à aucune de ces questions, sa place est probablement sur un autre diagramme.

L'exemple : une boutique en ligne avec cinq services

La boutique a des clients web et mobile, une passerelle API et cinq services :

• Catalog sert les produits depuis sa propre base PostgreSQL.
• Cart conserve les paniers dans Redis.
• Orders crée les commandes dans sa propre base PostgreSQL et publie OrderPlaced sur le topic orders dans Kafka.
• Payments consomme OrderPlaced, débite la carte via Stripe, enregistre le résultat et publie PaymentSucceeded ou PaymentFailed sur le topic payments.
• Notifications consomme le topic payments et envoie par e-mail, via un prestataire d'e-mailing, un reçu ou un avis signalant l'échec du paiement.

Orders consomme aussi le topic payments pour marquer une commande comme payée. Personne n'appelle Payments directement ; le tunnel de commande est une chaîne d'événements. C'est exactement ce choix de conception que le diagramme doit rendre visible :

Lisez-le de gauche à droite : la passerelle est le seul point d'entrée, les flèches pleines sont des appels synchrones, les flèches en tirets des événements qui passent par des topics nommés, et chaque base de données est rattachée à un seul et unique service.

Sept règles pour un diagramme de microservices lisible

1. Partir des points d'entrée

Dessinez d'abord, à gauche, les clients et la passerelle API. Ils fixent le sens de lecture et montrent quels services sont réellement exposés. Un service qu'aucun chemin ne relie à la passerelle est interne, et cela mérite d'être visible.

2. Rattacher chaque base à son propriétaire

Placez chaque stockage de données à côté du seul service qui le possède et ne reliez que ce service. Si deux services partagent aujourd'hui une base de données, dessinez-le aussi. C'est un signal d'alerte bien connu, et un diagramme qui le masque rend la prochaine migration plus difficile à planifier.

3. Séparer les appels synchrones des événements

Utilisez deux styles de trait et indiquez-les dans une légende : plein pour la requête et la réponse (REST, gRPC), en tirets pour les messages qui passent par un broker. Dessinez les topics ou les files d'attente comme des nœuds. Une boîte « bus d'événements » unique, à laquelle tous les services sont reliés, cache qui produit et qui consomme quoi.

4. Étiqueter chaque lien avec ce qui y circule

GET /products, POST /orders, OrderPlaced, PaymentFailed. Une étiquette transforme une flèche en contrat, et c'est ce que l'on cherche dans le diagramme pendant un incident.

5. Regrouper par domaine, pas par technologie

Si vous avez besoin de cadres, regroupez les services par domaine métier ou par équipe responsable : parcours d'achat, tunnel de commande, communication client. Des cadres comme « services Node.js » ou « services Java » répondent à une question que personne ne pose.

6. Garder l'infrastructure dans sa propre vue

Les Pods, les sidecars, les service meshes et les tableaux de bord comptent, mais pas dans la vue logique. Dessinez le déploiement sur un diagramme séparé, par exemple un diagramme d'architecture Kubernetes, et reliez les deux.

7. Montrer un flux critique

Choisissez le flux qui fait vivre l'entreprise, ici le tunnel de commande, et rendez-le facile à suivre : numérotez les étapes sur les liens ou mettez son chemin en évidence. Un flux par diagramme ; un deuxième flux a droit à sa propre copie de la vue.

Quand le système est trop grand pour un seul diagramme

Au-delà d'une vingtaine de boîtes, découpez. Un schéma qui tient la route :

• Un diagramme de paysage, avec les domaines comme cadres et seulement les connexions les plus importantes entre eux.
• Un diagramme par domaine, avec ses services, ses stockages de données et ses topics, dessiné selon les règles ci-dessus.
• Des diagrammes de flux pour les quelques parcours qui comptent, comme la commande ou l'inscription.

Cela se transpose naturellement au modèle C4 : le paysage est proche d'une vue de contexte système, et chaque diagramme de domaine est une vue de conteneurs dans laquelle les services et leurs bases de données sont les conteneurs.

Erreurs courantes

• Des flèches sans étiquette. Les lecteurs devinent, et chacun devine autre chose.
• La passerelle reliée aux bases de données. Si elle lit vraiment une base, c'est une décision de conception à discuter, pas un raccourci à dessiner.
• Mélanger les vues. Avec des Pods, des services AWS et des capacités métier sur un même canevas, plus personne ne peut lire quoi que ce soit.
• Cacher le broker. Kafka n'est pas un tuyau ; les topics ont des noms, des propriétaires et des consommateurs.
• Un instantané qui ne change jamais. Un diagramme qui date de la dernière refonte d'architecture est un document historique. Datez-le, ou gardez-le vivant.

Le construire dans Archboard

Archboard propose des packs de nœuds pour chaque partie de ce diagramme, si bien que services, stockages et topics sont des nœuds typés avec des ports plutôt que des boîtes interchangeables :

1. Connectez-vous avec Google ou GitHub et créez un diagramme.
2. Ajoutez une Boîte du pack Base pour les clients et une Passerelle API du pack Cloud.
3. Ajoutez les services sous forme de nœuds Conteneur du pack Modèle C4, avec le langage ou le framework dans le champ Technologie.
4. Ajoutez Postgres et Redis du pack Données à côté de leurs propriétaires, puis des nœuds Sujet pour orders et payments.
5. Ajoutez des nœuds Système externe du pack Modèle C4 pour Stripe et le prestataire d'e-mailing.
6. Connectez les ports. Laissez les appels synchrones en trait plein, passez les événements en tirets, puis étiquetez chaque lien.
7. Partagez le lien en direct avec l'équipe, ou intégrez le diagramme à votre documentation avec Pro.

L'exemple ci-dessus compte 15 nœuds de diagramme, ce qui tient dans le plan Free. Pour des exemples proches, ouvrez /examples/kubernetes-microservices pour le côté déploiement et /examples/api-gateway-infographic pour une infographie du pattern de passerelle API.

FAQ

Combien de services un diagramme doit-il montrer ? Autant que vous pouvez en lire sans zoomer, en général jusqu'à une vingtaine de boîtes. Au-delà, découpez par domaine et gardez une vue de paysage au-dessus.

Faut-il utiliser le modèle C4 pour des microservices ? Cela fonctionne bien. Les services et leurs bases de données deviennent des conteneurs dans une vue de conteneurs. Certaines équipes modélisent chaque service détenu de manière indépendante comme un système logiciel à part entière ; choisissez une convention et mettez-la par écrit.

Comment représenter Kubernetes, le service mesh et le monitoring ? Sur un diagramme de déploiement séparé. La vue logique répond à la question « qui parle à qui » ; la vue de déploiement, à la question « où ça tourne ».

Les événements doivent-ils pointer du consommateur vers le topic, puisque les consommateurs fonctionnent en pull ? Dessinez le sens dans lequel circulent les données, du producteur au topic puis au consommateur, et précisez que les consommateurs fonctionnent en pull si cela compte pour la discussion.

Comment garder le diagramme à jour ? Donnez un propriétaire au diagramme, mettez-le à jour dans la même pull request que le changement, et faites un lien vers le diagramme en direct depuis votre documentation au lieu de coller des captures d'écran.

Commencez gratuitement — un siège, sans carte bancaire.