Pourquoi séparer entité persistence et payload API
L’entité ORM porte souvent des champs internes (createdAt, relations lazy, flags techniques). Les exposer
tels quels crée des fuites de modèle et des failles de validation (champs modifiables par erreur).
Utilisez un DTO (symfony/validator) ou une structure dédiée par commande.
Exemple : contraintes métier + UUID
namespace App\\Dto;use Symfony\Component\Validator\Constraints as Assert; use Symfony\Component\Uid\Uuid;
final class CreateTransferRequest { public function __construct( #[Assert\NotBlank] #[Assert\Uuid] public string $fromAccountId,
#[Assert\\NotBlank] #[Assert\\Uuid] public string $toAccountId, #[Assert\\Positive] public string $amountCents, ) {}
}
amountCents en chaîne est volontaire : beaucoup de payloads JSON numériques perdent la précision décimale ;
pour la monnaie, entier + échelle ou décimal sérialisé en string sont des patterns éprouvés. Adaptez à
votre norme interne, mais évitez le flottant nu.
Normaliser les erreurs (422)
Retournez une structure stable : tableau de violations avec path + message + éventuellement
code machine-lisible. Les assistants et les générateurs de clients s’appuient sur cette régularité.
{
"type": "https://symfony.com/errors/validation",
"title": "Validation Failed",
"status": 422,
"violations": [
{ "path": "fromAccountId", "message": "This value is not a valid UUID.", "code": "INVALID_UUID" }
]
}Couche HTTP Symfony
MapRequestPayload (Symfony 6.3+) ou un ArgumentValueResolver personnalisé permet de
déclencher la validation avant le contrôleur et de centraliser le mapping erreur → réponse. L’important est que
tous les endpoints passent par le même pipeline — sinon la doc ment et les clients cassent au hasard.
FAQ
Valider en JavaScript côté front suffit ?
Non : c’est une aide UX. La validation serveur reste la source de vérité (sécurité, intégrité, évolutions multi-clients).
Faut-il utiliser OpenAPI partout ?
Pas obligatoire, mais un contrat formalisé (même léger) améliore SEO technique, onboarding et génération de tests contractuels.