Diagramme en tant que code : Diagrammes de séquence UML avec PlantUML et VPasCode

Un UML diagramme de séquencemontre comment les participants interagissent au fil du temps. Il est utile pour documenter un cas d’utilisation, flux d’API, processus métier ou scénario système. Le temps s’écoule généralement de haut en bas ; la disposition horizontale indique qui participe, et non une mesure précise du temps écoulé.

PlantUMLvous permet de décrire le diagramme sous forme de texte. l’éditeur VPasCode de Visual Paradigmassocie un éditeur de code à un aperçu en direct et à une assistance par IA pour générer, modifier et corriger le code de diagramme. Une bonne méthode de travail consiste à utiliser l’IA pour obtenir une première ébauche, puis à inspecter et affiner vous-même le code PlantUML.

1. La structure de base

Un diagramme de séquence PlantUMLcommence par @startuml et se termine par @enduml. Les participants sont généralement listés avant les messages afin que vous puissiez contrôler leurs noms et leur ordre.

@startuml
acteur Client
participant Navigateur
participant "API de commande" as API
database "Base de données de commande" as DB

Client -> Navigateur : Passer une commande
Navigateur -> API : POST /orders
API -> DB : Enregistrer la commande
DB --> API : ID de commande
API --> Navigateur : 201 Created
Navigateur -> Client : Afficher la confirmation
@enduml

L’étiquette affichée du participant peut être entre guillemets, avec comme fournissant un alias plus court à utiliser dans les messages. Les mots-clés de participant courants incluent acteur, participant, limite, contrôle, entité, base de données, et collections. Utilisez le mot-clé qui communique le mieux le rôle du participant ; il n’impose pas une architecture particulière.

2. Lecture des messages et du temps

Chaque message est écrit sous la forme d’un émetteur, d’une flèche, d’un récepteur et d’une étiquette. L’ordre des lignes de messages détermine leur ordre vertical dans le diagramme.

• -> est une flèche de message pleine, couramment utilisée pour une requête ou un appel.

• --> est une flèche en pointillés, souvent utilisée pour une réponse ou un retour.

• ->> et -->> utilisent des pointes de flèche ouvertes dans les styles courants de PlantUML.

• : texte ajoute l’étiquette du message.

Choisissez une convention cohérente pour les appels et les réponses. Les diagrammes UML communiquent une interaction ; ils ne garantissent pas automatiquement que l’implémentation suit le protocole représenté.

3. Activations et durées de vie des participants

Les activations peuvent montrer quand un participant effectue un travail. Utilisez activate et désactiver, ou le raccourci ++ et -- sur les flèches de message.

@startuml
actor User
participant "Login API" as API
database Users

User -> API: Soumettre les identifiants
activer API
API -> Users: Trouver le compte
activer Users
Users --> API: Enregistrement du compte
désactiver Users
API --> User: Résultat de connexion
désactiver API
@enduml

Les activations sont les plus utiles lorsqu’elles clarifient les appels imbriqués ou la responsabilité. Évitez de les ajouter mécaniquement à chaque message si cela rend le diagramme plus difficile à lire.

4. Conditions, alternatives et répétition

Utilisez des fragments combinés pour afficher le flux de contrôle. Le mot-clé fragment commence le bloc, sinon sépare les alternatives le cas échéant, et fin la ferme. Les conditions de garde vont entre crochets.

Cheminements alternatifs : alt et sinon

@startuml
acteur Utilisateur
participant "API de connexion" comme API
base de données Utilisateurs

Utilisateur -> API : Soumettre nom d'utilisateur et mot de passe
API -> Utilisateurs : Vérifier les identifiants
Utilisateurs --> API : Résultat de la correspondance

alt [identifiants valides]
  API --> Utilisateur : Retourner un jeton de session
sinon [identifiants invalides]
  API --> Utilisateur : Retourner une erreur d'authentification
end
@enduml

alt est approprié lorsque les cheminements sont mutuellement exclusifs. Utilisez des libellés qui rendent les conditions claires.

Comportement optionnel : opt

@startuml
acteur Client
participant Paiement
participant "Service d'envoi d'e-mails" comme Email

Client -> Paiement : Finaliser l'achat
Paiement --> Client : Confirmation de commande

opt [le client a accepté de recevoir des e-mails]
  Paiement -> Email : Envoyer le reçu
  Email --> Paiement : Accepté
end
@enduml

Répétition : boucle

@startuml
participant "Job par lots" as Job
participant "API de paiement" as API

boucle [pour chaque paiement en attente]
  Job -> API : Soumettre le paiement
  API --> Job : Résultat du paiement
fin
@enduml

Placez l’action répétée à l’intérieur du fragment et indiquez clairement la condition ou la portée de la boucle.

5. Interactions parallèles et groupées

Utilisez par lorsque les interactions se produisent simultanément ou que leur ordre n’est pas significatif. Utilisez group pour étiqueter un ensemble de messages sans impliquer une structure de flux de contrôle particulière.

@startuml
participant "Service de commande" as Orders
participant "Service d'inventaire" as Inventory
participant "Service de notification" as Notify

Orders -> Orders: Commande acceptée

par Réserver le stock
  Orders -> Inventory: Réserver les articles
  Inventory --> Orders: Résultat de la réservation
else Notifier le client
  Orders -> Notify: Envoyer une mise à jour de la commande
  Notify --> Orders: Accepté
end
@enduml

Utiliser par uniquement lorsque la concurrence a du sens. Si une action doit se terminer avant qu’une autre ne commence, affichez les messages séquentiellement à la place.

6. Notes, références et regroupement visuel

Les notes peuvent clarifier les hypothèses, les contraintes ou les décisions. Un ref fragment peut orienter les lecteurs vers un autre diagramme ou une interaction documentée séparément.

@startuml
acteur Client
participant "Interface de paiement" as UI
participant "Service de paiement" as Pay
participant "Vérification de fraude" as Fraud

Client -> UI: Payer la commande
UI -> Pay: Autoriser le paiement
Pay -> Fraud: Évaluer la transaction

note à droite de Fraud
  Les règles de risque sont maintenues
  en dehors de cette interaction.
end note

Fraud --> Pay: Résultat de risque
Pay --> UI: Résultat d'autorisation
UI --> Client: Afficher le résultat
@enduml

Les notes doivent ajouter du contexte plutôt que de répéter les libellés des messages. Si le diagramme devient encombré, divisez-le en scénarios ciblés et utilisez des références ou des liens vers la documentation pour les relier.

7. Création et affinage de diagrammes dans VPasCode

VPasCode prend en charge l’édition PlantUML avec rendu en direct, ainsi que la génération de diagrammes assistée par IA, la modification de code et la correction de syntaxe. Son interface exacte et la disponibilité de ses fonctionnalités peuvent évoluer, mais le flux de travail général est le suivant :

1. Ouvrez VPasCode et choisissez ou saisissez PlantUML.

2. Décrivez l’interaction, ou collez un brouillon PlantUML dans l’éditeur.

3. Vérifiez l’aperçu rendu pendant que vous affinerez la source.

4. Demandez à l’IA d’apporter une modification spécifique, comme « ajouter un chemin pour des identifiants invalides en utilisant “alt.”

5. Vérifiez le code et le diagramme résultants pour la syntaxe et la cohérence du système.

6. Exportez ou partagez le diagramme terminé en utilisant les options disponibles dans l’éditeur.

Une invite utile fournit à l’IA le type de diagramme, les acteurs, les limites du système, le chemin de succès principal, les chemins alternatifs importants et le niveau de détail. Par exemple :

Créez un diagramme de séquence PlantUML pour un client se connectant à une application web. Incluez le navigateur, l’API de connexion, le fournisseur d’identité et la base de données utilisateur. Montrez le chemin de connexion réussi et une alternative pour mot de passe invalide. Utilisez des libellés concis et n’inventez pas de services au-delà de ceux-ci.

Traitez le code généré comme un brouillon. Vérifiez que les participants, les flèches, les conditions et les chemins d’erreur reflètent le système réel, et non pas simplement un flux plausible.

8. Un exemple plus complet : paiement avec échec de paiement

Cet exemple combine des alias de participants, des activations et un chemin alternatif.

@startuml
title Validation et autorisation de paiement

acteur Client
frontière "Interface de paiement" as UI
contrôle "Service de commande" as Orders
participant "Passerelle de paiement" as Pay
database "Base de données des commandes" as DB

Client -> UI: Soumettre le paiement
UI -> Orders: Créer une commande en attente
activer Orders

Orders -> DB: Enregistrer la commande en attente
DB --> Orders: ID de commande

Orders -> Pay: Autoriser le paiement
activer Pay

alt [paiement approuvé]
  Pay --> Orders: Code d'autorisation
  désactiver Pay

  Orders -> DB: Marquer la commande comme confirmée
  DB --> Orders: Mis à jour
  Orders --> UI: Commande confirmée
  UI --> Client: Afficher la confirmation
sinon [paiement refusé]
  Pay --> Orders: Raison du refus
  désactiver Pay

  Orders -> DB: Marquer la commande comme échouée
  DB --> Orders: Mis à jour
  Orders --> UI: Paiement refusé
  UI --> Client: Afficher l'option de réessayer
fin

désactiver Orders
@enduml

Vérifiez que l’ordre du diagramme correspond au comportement réel. Par exemple, si le système ne persiste la commande qu’après une autorisation réussie, déplacez les messages de base de données pour correspondre à cette conception.

9. Lignes directrices pratiques de modélisation

• Gardez un diagramme centré.Montrez un seul scénario ou un ensemble de chemins étroitement liés. Séparez les détails profonds qui distraient de l’interaction principale.

• Nommez les participants par responsabilité.Préférez des libellés tels que “Service de commande” ou “Passerelle de paiement” à des libellés vagues tels que “Système.

• “Montrez des frontières significatives.Distinguez l’utilisateur, le client, les services internes, les bases de données et les systèmes externes lorsque cela aide les lecteurs à comprendre les responsabilités.

• Utilisez des libellés de messages clairs. Incluez une opération, un événement ou un résultat important ; évitez les étiquettes qui se contentent de dire « processus ».

• Modélisez les chemins d’échec qui ont de l’importance. Incluez les délais d’attente pertinents, les rejets, les nouvelles tentatives ou les échecs de validation lorsqu’ils affectent le scénario.

• Utilisez les fragments avec précision. alt signifie des chemins alternatifs, opt signifie un comportement optionnel, loop signifie une répétition, et par signifie un comportement parallèle.

• Évitez le bruit d’implémentation. Ne diagrammez pas chaque getter, méthode interne ou détail de bas niveau, sauf si le public en a besoin.

• Gardez la source maintenable. Utilisez des alias pour les noms longs, une dénomination cohérente, et des commentaires ou notes courts pour les hypothèses importantes.

10. Erreurs courantes et liste de vérification

Si le diagramme ne s’affiche pas, vérifiez que @startuml et @enduml sont présents, les blocs de fragment ont des correspondances findéclarations, les alias sont utilisés de manière cohérente, et tous les points de terminaison des messages font référence à des participants définis. Vérifiez également la présence de syntaxe d’un autre langage de diagramme collée accidentellement dans la source PlantUML.

Avant de partager, vérifiez deux points :

• Syntaxe :S’affiche-t-il correctement ? Les fragments sont-ils fermés ? Les participants et les alias sont-ils cohérents ?

• Sens :Les participants et les directions des messages sont-ils corrects ? Les chemins d’erreur importants sont-ils inclus ? Les systèmes externes et les dépôts de données sont-ils représentés avec précision ?

Le flux de travail diagramme en tant que code le plus robuste combine une source lisible, une rétroaction visuelle rapide et une revue par les experts du domaine. PlantUML offre un contrôle explicite sur la notation des interactions, tandis que VPasCode peut accélérer la rédaction et l’itération ; l’autorité finale sur l’exactitude du diagramme reste toujours le comportement du système qu’il est censé décrire.

Cette publication est également disponible en Deutsch, English, Español, فارسی, Bahasa Indonesia, 日本語, Polski, Portuguese, Ру́сский, Việt Nam, 简体中文 : liste des langues séparées par une virgule, 繁體中文 : dernière langue.