Insertar un documento no consiste únicamente en ejecutar . Una inserción transforma una entrada no confiable en un documento BSON, valida su estructura, asigna identidad, intenta persistirlo con una garantía de escritura y devuelve un resultado que la aplicación debe interpretar.
insertOne
Texto
input
↓
validación y autorización
↓
mapping a BSON
↓
insertOne / insertMany / bulkWrite
↓
validation + unique indexes
↓
write concern
↓
resultado o error
La operación devuelve un resultado con acknowledgment e insertedId cuando corresponde. Que la inserción haya sido acknowledged no significa que todos los nodos del replica set ya la hayan persistido; la garantía depende del write concern.
El tenant se obtiene de la sesión, no del request body.
Los productos se consultan y se crean snapshots.
El total se calcula en una capa confiable.
Los valores se convierten a tipos BSON.
MongoDB aplica validators e índices.
El resultado se transforma a una respuesta pública.
El ejemplo no incluye por sí solo una reserva atómica de stock; eso pertenece al diseño de concurrencia y puede requerir updates condicionales o una transacción.
Si no se envía _id, el driver suele generarlo antes de enviar el documento. Generarlo explícitamente permite conocerlo con anticipación y utilizarlo en logs, eventos u operaciones relacionadas.
Un _id duplicado produce duplicate key error. No debes capturar ese error como si fuera indisponibilidad general.
El write concern define qué acknowledgment espera el cliente.
Conceptualmente:
Texto
w: 1
→ el primary reconoce
w: 'majority'
→ espera confirmación de mayoría de miembros con voto según reglas del replica set
Puede combinarse con timeout y journaling según configuración. Mayor durabilidad suele añadir latencia. No configures un concern débil o fuerte sin relacionarlo con el riesgo del caso de uso.
Permite continuar operaciones independientes después de errores. Puede mejorar throughput, pero el resultado puede ser parcial y el orden de ejecución no debe utilizarse como contrato.
insertMany no convierte el lote en una sola transacción.
Una request puede repetirse por timeout, retry del cliente o recuperación de red. Si crear dos órdenes sería incorrecto, utiliza una clave de idempotencia:
JavaScript
{
businessId,idempotencyKey:'checkout-abc-123',// order fields}
La aplicación puede recuperar el resultado existente cuando recibe el mismo key. La estrategia debe definir cuánto tiempo se conserva y qué payload representa.
Los drivers pueden reintentar ciertas escrituras ante fallos transitorios cuando la topología y operación son compatibles. No añadas retries manuales ciegos sin conocer los del driver.
Existe una diferencia entre:
operación definitivamente fallida;
operación aplicada pero respuesta perdida;
resultado de commit desconocido.
La idempotencia y los índices ayudan a resolver ambigüedad.
Una inserción cruza varias fronteras: input, mapping, validación, índices, durabilidad y respuesta. insertOne es atómico para un documento; insertMany puede producir éxito parcial. La seguridad y consistencia dependen del diseño que rodea la llamada.
Comprueba lo aprendido
¿Por qué insertMany no equivale a una transacción?
¿Qué protege un índice unique que una consulta previa no protege?
¿Cómo manejarías una respuesta perdida después de crear una orden?
¿Qué diferencia existe entre validación de input y schema validation?
¿Cuándo elegirías ordered frente a unordered?
¿Qué significa realmente que una escritura sea acknowledged?