UUID donne l’impression d’être une solution prête à coller partout: générer, stocker, exposer. Les problèmes apparaissent autour du format. Une colonne texte trop permissive, un index non mesuré, une validation approximative, un endpoint qui confond identifiant et autorisation ou un import qui régénère les valeurs peuvent transformer un outil utile en dette durable.
Une colonne texte arbitraire accepte trop
Sans type UUID ou contrainte, la base peut accepter des chaînes mal formées, des espaces, des variantes de casse ou des valeurs qui ne sont pas des UUID. Les index deviennent plus volumineux et les comparaisons moins contrôlées.
Si un type natif existe, utilisez-le. Sinon, imposez une forme canonique et une validation stricte au boundary d’entrée.
Les index aléatoires ont un coût possible
Un UUID v4 comme clé primaire insère des valeurs dans différentes pages d’un index. Sur de petits volumes, ce coût est négligeable. Sur de forts volumes d’écriture, il peut dégrader la localité et augmenter la fragmentation.
UUID ordonné par temps, clé interne séquentielle ou stratégie d’index différente peuvent être préférables. La décision doit être mesurée, pas héritée d’une discussion générale.
La validation doit suivre une politique
Une regex qui vérifie seulement des groupes hexadécimaux peut accepter des valeurs hors version ou refuser des versions légitimes. Une bibliothèque UUID comprend mieux la structure. La politique métier doit ensuite dire quelles versions sont acceptées.
Ne corrigez pas silencieusement un input avec texte supplémentaire ou séparateurs inattendus. Rejeter tôt garde le contrat propre.
UUID n’est pas une autorisation
Un identifiant difficile à deviner peut fuiter dans les logs, les URLs ou les captures d’écran. Si connaître l’UUID suffit à lire la ressource, le système repose sur l’obscurité. Chaque requête doit vérifier les permissions du principal.
Les liens secrets doivent utiliser des tokens spécifiques, révocables et expirables, pas l’identifiant principal de la ressource.
Les retries peuvent créer des doublons métier
Si un client génère un nouvel UUID à chaque tentative, la base aura plusieurs lignes uniques pour la même action. L’unicité technique ne garantit pas l’idempotence métier. Le client doit réutiliser l’ID logique ou fournir une operation key.
Les endpoints de création doivent être pensés avec les retries, les timeouts et les imports. UUID aide, mais ne définit pas tout le workflow.
IDs publics et internes doivent rester distincts
Un système peut utiliser une clé entière interne et un UUID public. Ce modèle est valide, mais les noms, types et serializers doivent être clairs. Exposer la clé interne par erreur ou utiliser l’UUID dans un join critique peut créer sécurité ou performance mauvaises.
Les DTOs devraient indiquer explicitement public_id, uuid ou internal_id. Les ambiguïtés de nom deviennent vite des bugs.
Les opérations bulk ont besoin de limites
Une liste de mille UUID valides peut être trop coûteuse. Limitez le nombre d’IDs, validez chacun, vérifiez les permissions et prévoyez un plan de requête efficace. La syntaxe correcte ne garantit pas une charge acceptable.
Les réponses doivent éviter de révéler l’existence de ressources interdites. Parfois, “not found” et “forbidden” se ressemblent volontairement pour l’extérieur.
La sérialisation doit préserver la valeur
JSON transporte UUID comme chaîne. Les queues, exports et caches doivent conserver la forme exacte attendue. Convertir en nombre, tronquer, modifier la casse ou enlever des tirets sans règle casse les références.
Les logs devraient permettre recherche exacte tout en ajoutant contexte humain. Un UUID seul n’aide pas un opérateur à comprendre la ressource.
Les schémas doivent aligner clés primaires et étrangères
Un UUID stocké en binaire à un endroit et en texte ailleurs complique les joins et les constraints. Les revues de schéma doivent vérifier type, collation, index et ordre de bytes. Une incohérence discrète peut transformer une migration simple en chantier risqué.
Les exports doivent aussi préciser la représentation. Un partenaire ne devrait pas deviner si la valeur est canonical text, hex compact ou autre forme.
Les imports doivent être idempotents
Lorsqu’un import échoue au milieu, le second passage doit produire les mêmes identifiants pour les mêmes objets. Un mapping persistant ou une version basée sur nom peut aider. Sans idempotence, les relations externes deviennent difficiles à reconstruire.
Les exports partenaires devraient conserver le même UUID entre versions. Changer la référence publique oblige chaque consommateur à reconstruire son mapping, ce qui est souvent plus risqué que la migration interne elle-même.
Surveillez les erreurs rares
Un duplicate-key failure ou un UUID mal formé devrait être rare. Une hausse signale un générateur cassé, un client mal mis à jour ou une corruption d’import. Les métriques par endpoint et par producteur rendent ces problèmes visibles.
Les alertes ne doivent pas attendre une collision. Une augmentation de valeurs mal formées ou de versions inattendues suffit souvent à détecter une intégration cassée.
Les réponses API doivent distinguer une syntaxe incorrecte d’un ID valide mais absent. Cette cohérence aide les clients tout en évitant de révéler des ressources auxquelles ils n’ont pas accès.
UUID fonctionne bien lorsqu’il est traité comme identifiant opaque avec stockage compact, validation claire, contraintes, autorisation explicite et outils de support adaptés.