Erreur métier

Back

Tout contrôle menant à une erreur métier (i.e qui n'est pas lié à des données invalide ou une ressource non-trouvée) :

• nécessite une exception spécifique au module/API (ex: TypologieException/VisaException)
• est identifiée par un code métier (ex: typologie-1001) associée à un message spécifique

public enum TypologieProblem implements IProblemDetails {
    NAME_ALREADY_EXISTS(HttpStatus.BAD_REQUEST, "typologie-1001", "typologie-1001.title", "typologie-1001.detail");
    //...
}

• On passe de préférence un contexte à l'exception, il permet de préciser le problème rencontré (ex : le status d'une ressource)

throw new RoleException(RoleProblem.ROLE_ALREADY_EXISTS_BY_TYPE_AND_CONTEXT,
	// map with context
	Map.of(ROLE_TYPE_CONTEXT, role.getType().getLabel(),
		ROLE_CONTEXT_CONTEXT, role.getContexte().getLabel());
}

• Faire une énum orientée métier/controller. Ex : NomenclaturePaysProblem qui correspond aux erreurs métier renvoyées par le NomenclaturePaysController
• spécialiser les codes erreurs ex :
  • nomenclature-pays-1001.title
  • nomenclature-pays-1001.detail
  • nomenclature-simple-1001.title
  • etc
• la partie numérique 1001 est ré-initialisable par énum

Attention

Pensez à documenter openAPI avec les erreurs métiers

Attribut 'context'

L'objet context est construit manuellement lors de la création de l'erreur métier par le dev, il permet de passer les valeurs nécessaires à construire un message d'erreur par l'appelant, mais aussi de rajouter plus de contexte pour comprendre d'où provient l'erreur.

Format : on utilise le format kebab-case pour les clés dans la propriété "context" d'un retour d'erreur. On la préfixe avec l'entité en rapport avec l'erreur (ex: role-name)

{
  "title": "Erreur lors de l'ajout d'un viseur.",
  "code": "typologie-1001",
  "detail": "Impossible de créer un viseur avec le rôle Administrateur fonctionnel",
  "instance": "/typologies/1/viseurs",
  "context": {
    "role-name": "Administrateur fonctionnel", <-- utile pour construire le message
    "role-peut-viser-convention": "false" <-- utile pour comprendre le problème
  },
  "error-id": "237e5686-a676-4af3-99d2-a57df90e9f9b"
}

Voir la FQR CR de l'atelier