Bon exemple d'un diagramme de séquence pour les appels de service Web?

Question

On m'a demandé de créer un diagramme de séquence pour documenter les appels de service Web effectués par mon application.

Je ne comprends pas vraiment les diagrammes de séquence. Ils sont difficiles à lire - beaucoup de lignes, pas beaucoup de texte. Par exemple, si je veux montrer que mon application appelle un service spécifique, passer un ensemble de données et récupérer un ensemble de données différent, il n'y a pas assez de place sur la ligne et la ligne pour afficher toutes ces données et de souligner que c'est un GET ou un POST, et sans cette information, le diagramme est minimaliste au point de ne pas être très utile. Je trouve beaucoup plus facile de documenter des choses comme ça dans un fichier texte ou sur un wiki. Mais je vois à quel point les diagrammes de séquence sont populaires, donc je pense que je ne les "reçois" pas.

J'ai donc trois questions en ce moment:

(1) Quelqu'un peut-il me montrer quelques exemples particulièrement bons/utiles d'un diagramme de séquence pour les appels de service Web, donc je peux voir comment cela se fait-ce pas? (2) Lorsqu'un flux a différents chemins logiques qui entraînent différents appels de service Web, devrais-je les représenter par if/then/else dans un seul diagramme de séquence, ou créer un diagramme de séquence différent pour chaque possibilité? (3) Je comprends que les diagrammes de séquence sont basés sur UML, mais en quoi UML est-il un "langage"? Il n'y a pas de représentation textuelle, non? Cela ressemble plus à une manière de schématiser quelque chose, comme un organigramme.

Answer 1

Le but du diagramme de séquence dans votre cas est de communiquer certaines informations à vos collègues (ou à vous-même). Il n'y a vraiment pas de «meilleure» façon de procéder, tout comme il n'y a pas de meilleure façon d'écrire cette réponse - j'ai déjà reformulé cette réponse, et si je devais relire ma réponse dans un an , Je le reformulerais probablement pour être plus clair.

La même chose vaut pour les diagrammes ici; Si vous ne comprenez pas le diagramme vous-même (en supposant que vous compreniez le but des diagrammes de séquence), alors les autres ne le comprendront pas non plus.

Peut-être que dans votre cas quelque chose comme cela pourrait suffire

Mise au point sur la communication d'abord, le souci d'être « conforme » aux spécifications UML plus tard. Considérez-vous la langue des signes comme une langue, même si elle utilise des gestes de la main plutôt que du texte?

De même UML a un «vocabulaire» d'éléments visuels qui représentent différents concepts --- les diagrammes de séquence avec leurs lignes de vie et les messages expriment une séquence de communication entre les acteurs (classes). En outre, vous pouvez ajouter des notes à votre diagramme pour clarifier votre intention.

(2) Vous pouvez faire les deux. Encore une fois, le facteur décisif est la clarté de la communication - si un seul diagramme est trop encombré, alors cassez-le et faites-en un autre, ou une douzaine de plus (comme vous diviser les méthodes et les classes). Une règle de base est de garder le même niveau d'abstraction dans tout le diagramme - plonger soudain dans des détails de mise en œuvre peut l'encombrer très rapidement.

(1) La meilleure façon de commencer est d'apprendre d'abord le "vocabulaire" des diagrammes, par ex.uml-diagrams.org, puis dessinez quelque chose et voyez si vous le comprenez ou si les autres le comprennent; N'ayez pas peur de jeter un diagramme si vous pensez pouvoir le «reformuler».

il y a à peine assez de place sur la ligne de sortie et la ligne de retour pour afficher toutes ces données

sonne comme un problème d'outillage; Il suffit de mettre les lignes plus loin, ou utiliser des choses comme PlantUML qui fait cela pour vous. (Ou utiliser un outil UML réelle.)

le diagramme est au point minimalistes de ne pas être très utile

Ensuite, enrichir, ajouter une annotation de texte, le diviser. Utilisez-le comme partie de la documentation pour illustrer seulement certains points; vous n'avez pas besoin d'utiliser le diagramme comme seul artefact de documentation.