UUID parece una solución que se puede añadir sin pensar: generar, guardar y exponer. En la práctica, los errores aparecen alrededor del identificador. El tipo de columna, el índice, la forma textual, la validación, la autorización y los imports determinan si UUID reduce coordinación o introduce deuda. Un ID grande no sustituye disciplina de datos.
Guardar UUID como texto arbitrario pierde garantías
Una columna de texto amplia acepta valores mal formados, mayúsculas mezcladas, strings con espacios y datos que ni siquiera son UUID. También ocupa más espacio en índices. Si la base ofrece tipo UUID o representación binaria fija, suele ser mejor.
Cuando se usa texto por compatibilidad, define longitud, forma canónica y validación. No permitas que varias representaciones del mismo valor se propaguen por la base.
Los índices deben medirse
UUID aleatorio como primary key puede fragmentar índices ordenados. En sistemas pequeños no se nota; en escrituras intensivas puede afectar I/O y cache. UUID ordenado por tiempo, clave interna secuencial o índices ajustados pueden ser mejores según patrones de consulta.
No decidas solo por opiniones. Mide inserción, joins, tamaño de índices y planes de query con datos parecidos a producción.
Validación no debe ser un regex casual
Un patrón que solo revisa grupos hexadecimales puede aceptar variantes incorrectas o rechazar versiones legítimas. Usa bibliotecas que entiendan UUID y aplica una política de versiones. Entrada válida sintácticamente no siempre es aceptable para tu dominio.
No “corrijas” automáticamente valores con texto extra o separadores raros. Rechazar temprano obliga al productor a arreglar el contrato y evita convertir un input dudoso en otro recurso.
UUID no autoriza
Un ID difícil de adivinar no reemplaza permisos. Los UUID aparecen en enlaces compartidos, logs y herramientas de soporte. Cualquier endpoint que entregue un recurso debe comprobar que el usuario o servicio puede acceder a él.
Si se desea acceso por posesión de enlace, diseña tokens específicos con expiración y revocación. El identificador principal del recurso debería seguir siendo identidad, no credencial.
Los retries pueden crear duplicados lógicos
Un cliente offline que genera un UUID para crear un registro debe reutilizar el mismo ID al reintentar. Si crea uno nuevo en cada attempt, la base tendrá múltiples registros únicos para la misma acción. La unicidad técnica no impide duplicidad de negocio.
Los endpoints idempotentes deben aceptar operation IDs o claves naturales según el caso. UUID ayuda, pero el flujo de retry también debe estar diseñado.
No mezcles IDs internos y públicos accidentalmente
Algunas aplicaciones usan enteros internos por eficiencia y UUID públicos para APIs. Ese modelo puede funcionar, pero requiere nombres claros, tipos distintos y cuidado en rutas. Exponer el entero por error rompe la separación; usar el UUID donde se esperaba integer puede dañar rendimiento.
Los DTOs y serializers deben dejar claro qué identificador atraviesa cada frontera. La confusión de IDs es una fuente común de bugs de autorización.
Bulk operations necesitan límites
Una lista de mil UUID válidos puede ser demasiado costosa para un endpoint. Limita cantidad, valida cada valor, verifica permisos por recurso y usa queries planificadas. No asumas que la sintaxis correcta implica carga aceptable.
Las respuestas deben evitar revelar qué IDs existen cuando el usuario no tiene permiso. A veces “not found” y “forbidden” se unifican externamente para reducir filtración.
Los errores de API deben ser consistentes
Un UUID mal formado es un error de cliente y debería rechazarse antes de consultar la base. Un recurso inexistente y uno prohibido pueden necesitar respuestas externas similares para no revelar existencia. Internamente, logs con request ID pueden conservar la causa exacta.
También conviene medir valores rechazados por endpoint. Un aumento repentino suele señalar un cliente roto, un cambio de serialización o un intento automatizado de exploración.
La serialización debe preservar bytes y forma
JSON transporta UUID como string. Colas, exports y caches deben conservar casing, guiones y orden binario cuando aplique. Recortar, traducir o convertir el identificador en número destruye referencias.
Los contratos públicos deben nombrar el campo con precisión. id, public_id y internal_id no deberían alternarse casualmente. Un nombre claro evita que clientes mezclen referencias o guarden un identificador que no será estable.
Las bases replicadas necesitan la misma política
Si una región genera UUID con una biblioteca distinta o una versión diferente, la consistencia operativa se pierde. Documenta generator, version y forma canónica como estándar compartido. En distributed systems, la independencia de generación no significa independencia de reglas.
Las revisiones de esquema deberían comprobar que primary keys, foreign keys y columnas públicas usan tipos compatibles. Un UUID guardado como binario en un lugar y texto en otro puede complicar joins, constraints y herramientas de exportación.
Observa errores raros
Duplicate-key failures y malformed UUID deberían ser eventos excepcionales. Si aumentan, pueden indicar generador roto, cliente defectuoso o corrupción en un import. Métricas por boundary ayudan a detectar el problema antes de que se extienda.
UUID funciona mejor cuando se trata como valor opaco con storage compacto, validación clara, constraints, permisos explícitos y herramientas de soporte. El formato resuelve generación; el sistema aún debe resolver integridad.