Backend Modular
Completa el comportamiento solicitado con el cambio legible más pequeño. Aplica estas convenciones a nuevos backends y al código afectado en proyectos existentes. No conviertas una corrección enfocada en una migración de todo el proyecto.
Carga las referencias relevantes
| Tarea | Leer |
|---|---|
| Nuevo módulo, refactor estructural, DTOs, inyección de dependencias | Arquitectura |
| Contratos de error, fallos de validación, filtros globales, i18n | Errores e i18n |
| Consultas, índices, transacciones, Redis, comportamiento de caché/almacenamiento | Datos y Redis |
| Paquetes de usuario, autenticación, sesiones, OAuth, dispositivos, huellas digitales, hashing de contraseñas/IP | Identidad |
| Guards de cabecera y JWT, middleware, decoradores de ruta y parámetros | Límite de solicitud |
| Bootstrap, configuración, límites de tasa, logs, salud, verificación | Operaciones |
| Colas, trabajadores, programaciones, idempotencia de webhook, límites de recursos | Trabajo en segundo plano |
| Dockerfile, Compose local, scripts Bash de inicio/parada, comandos de API/trabajador | Docker |
| Verificaciones de CI, contenedores, migraciones, lanzamientos, reversión | CI/CD |
Para un nuevo backend, revisión de cimientos o solicitud de arreglar componentes base faltantes, lee Arquitectura, Operaciones, Errores e i18n, Límite de solicitud, Docker y Datos y Redis antes de editar. Lee otras referencias según las necesite la tarea. Adapta los ejemplos a las versiones instaladas y al dominio real. Usa Markdown portátil y herramientas de proyecto estándar. Sigue el modelo de permisos del agente anfitrión.
Establece el alcance antes de editar
Lee las instrucciones del repositorio, el manifiesto del paquete, el bootstrap, los módulos afectados y sus llamadores, los esquemas relevantes, el uso de Redis y las pruebas. Usa definiciones de configuración y nombres de variables de ejemplo para el descubrimiento.
Nuevo backend. Aplica las reglas de cimientos y arquitectura directamente. Implementa la base conectada y usa las referencias relevantes para los flujos de producto solicitados. Pregunta por decisiones de producto faltantes que afecten el comportamiento o la propiedad de los datos. La habilidad ya establece las elecciones de ingeniería base.
Backend existente. Comienza con una evaluación de arquitectura de solo lectura. Presenta la arquitectura actual, el objetivo propuesto y qué componentes mantener, cambiar, agregar o aplazar. "Revisa este backend según modular-backend" cubre todo el backend. Cuando una solicitud especifique el estándar sin seleccionar cambios específicos, pregunta en una pregunta concisa qué propuestas aplicar y espera la decisión. Si el usuario ya solicitó explícitamente un cambio específico, primero analiza y comparte la arquitectura relevante, procede con ese cambio y pregunta antes de asumir más cambios arquitectónicos. Una solicitud de solo análisis termina con la evaluación. Después de que el usuario seleccione el alcance, impleméntalo y ejecuta las comprobaciones de aceptación aplicables.
Para una solicitud que nombre una característica, endpoint o error, limita la evaluación a esa ruta y sus llamadores afectados. Usa el módulo existente más cercano que siga estas reglas como modelo para nombres, ubicación de archivos, DTOs, errores y estilo de transacción.
Nuevo backend, revisión de cimientos o remediación de base
- AppBuilder y Helmet son obligatorios para HTTP. Mantén
src/main.tsdelgado y coloca la construcción de HTTP ensrc/builder/app.builder.ts. Usa unFastifyAdapterexplícito de Nest ofastifydirecto para HTTP Node.js sin Nest. Registra@fastify/helmetcompatible antes de la inicialización o escucha. Vincula el builder real en pruebas de integración HTTP. Los trabajadores sin HTTP usan su propio punto de entrada. - Localiza los errores HTTP en un filtro global o manejador de Fastify. Usa definiciones de error de módulo con
code,statusymessageKey, un registro tipificado y una excepción compartida. Devuelve{ status, code, message }para nuevos contratos HTTP.statuscoincide con el estado HTTP,codepermanece estable entre idiomas ymessageproviene de i18n. Para APIs existentes, conserva los campos publicados hasta que se acuerde una migración compatible. - La infraestructura de Redis y una ruta de datos real de Redis son obligatorias. Agrega configuración de conexión validada, archivos centralizados de claves Redis y TTL, un proveedor Redis compartido y una sonda de readiness. Asigna a Redis al menos una familia de datos útil para la cual sea la fuente de verdad. Implementa sus lecturas y escrituras reales a través de un repositorio de dominio. Una conexión, sonda de salud o caché de respuesta SQL por sí sola no satisface esta regla. Usa un flujo de producto existente adecuado, como configuración de cliente publicada, clasificación/estado en vivo o limitación compartida. Cuando el producto tenga configuración de cliente o política de versión, almacena y sirve su documento publicado desde Redis. Identifica una decisión de producto faltante si no se puede elegir ninguna familia de datos legítima del alcance.
- Genera claves de Redis a partir de plantillas compartidas. Mantén las plantillas
[placeholder]enredis-keys.config.ts, los TTL enredis-ttl.config.tsygenerateRedisKey/generateRedisKeysensrc/utils/redis-key.util.ts. Haz que el proveedor compartido aplique el namespace configurado una vez. Usa esta ruta en lectores, escritores y trabajos reales. Conserva el formato de clave existente durante las revisiones a menos que el usuario seleccione una migración planificada. Consulta ejemplos de claves Redis. - Las lecturas propiedad de Redis y preparadas permanecen en Redis. Establece el comportamiento de población, actualización, falta de clave, caducidad, interrupción y recuperación por familia de clave. Usa ausencia tipificada para una entidad genuinamente faltante y no disponible tipificado para una interrupción o una proyección requerida que no está lista. Una solicitud nunca consulta SQL como respaldo para estos roles. Usa una excepción explícita de caché-aside solo para una caché desechable acordada. Conserva un contrato de lectura existente en revisiones no relacionadas.
- Conecta la limitación de tasa compartida para HTTP. Registra el guard o hook de cumplimiento y configura un presupuesto predeterminado para rutas externas. Agrega presupuestos más estrictos respaldados por Redis para autenticación, recuperación y acciones costosas que existan. Usa contadores separados de IP y cuenta normalizada para el inicio de sesión con contraseña. Incrementa y expira atómicamente, responde con 429 y
Retry-After, y devuelve 503 tipificado cuando el cumplimiento requerido no esté disponible. Usa una política explícita para exenciones de rutas del sistema. - Pagina cada colección en crecimiento expuesta por HTTP. Usa un DTO de consulta validado, límite acotado y un cursor de keyset estable que contenga cada valor de ordenación más un desempate único. Consulta
limit + 1con el alcance y filtros del llamador en el repositorio. Devuelve{ items, nextCursor }para nuevas listas. Calcula totales exactos y usa desplazamiento de número de página solo cuando el contrato de la API lo necesite. - Conecta los guards y decoradores que usa la API. Usa un guard de cabecera tipificado para un contrato móvil/dispositivo, un guard JWT para rutas JWT protegidas y guards de rol, invitado o proveedor específico donde la política los necesite. Registra los guards y consume su contexto validado usando decoradores de parámetros. Usa hooks de solicitud de Fastify o middleware existente para preocupaciones de transporte transversales.
- Entrega un flujo de trabajo Docker ejecutable. Proporciona o reutiliza un Dockerfile, Compose para dependencias locales y comandos Bash de inicio/parada con alcance de proyecto. Espera la preparación y usa volúmenes duraderos para datos autoritativos. Conserva un flujo de trabajo equivalente establecido en las revisiones. Ejecuta programaciones de trabajos y consumidores solo cuando la carga de trabajo lo justifique.
- Implementa solo los módulos/características requeridos. Los flujos de trabajo de autenticación/usuario/dispositivo son orientación reutilizable, no permiso para agregar funciones de cuenta a un servicio que no las necesita.
- Usa primero los módulos integrados de Node.js y los módulos oficiales de NestJS. La base aprobada incluye
@fastify/helmetcompatible, un único cliente Redis ynestjs-i18npara errores HTTP de Nest si no hay una integración de i18n adecuada instalada. Un nuevo flujo de autenticación por contraseña puede usarargon2compatible para Argon2id; usanode:cryptopara resúmenes de tokens y huellas digitales con clave. Mantén el cliente Redis existente funcional o usaredispor defecto para un nuevo proyecto. Usafastifydirectamente donde se importe. Otros nuevos paquetes de terceros, pares opcionales y plugins de Fastify requieren aprobación explícita. Consulta Operaciones. - Entrega bootstrap conectado, configuración validada, proveedores, migraciones requeridas, configuración local y las APIs solicitadas. No te detengas en archivos de andamio desconectados.
Backend existente / revisión
- Encuentra todos los llamadores antes de cambiar una función compartida o mover archivos: servicios, controladores, trabajos, guards, exportaciones, mocks, fixtures y consumidores de respuesta.
- Conserva cambios no relacionados, contratos públicos, comportamiento de token/almacenamiento, validación, filtros de propiedad y nombres establecidos. Restringe la limpieza a la ruta de la tarea.
- Cuando la tarea configure, reemplace o repare la base HTTP, trae Fastify, AppBuilder y Helmet juntos al alcance. Conserva el adaptador y el bootstrap durante cambios de características no relacionados. Al migrar a Fastify, verifica los códigos de estado, middleware, cookies, cargas y cuerpos de webhook firmados donde sea relevante.
- Extrae consultas a repositorios concretos al cambiar el servicio relevante. Conserva el contexto de transacción, bloqueos, manejo de errores, forma de retorno, ámbito de soft-delete y tenant.
- Al cambiar una lista o limitador, conserva el cursor público existente y el contrato de respuesta y ajusta la validación dentro del alcance. Rastrea los metadatos de límite de tasa hasta un guard o hook en ejecución. Mantén el ámbito de actor y tenant en la consulta de datos. Planifica explícitamente los cambios incompatibles de cursor o clave de limitador.
- Para una configuración o refactor de infraestructura, aplica la misma política de paquetes. Conserva las integraciones existentes a menos que la tarea las cambie. Resuelve las dependencias requeridas para la infraestructura solicitada antes de agregar paquetes.
- No elimines silenciosamente el respaldo, cambies el almacenamiento de sesión, modifiques los tiempos de vida de los tokens o invalides todas las sesiones como limpieza. Planifica la compatibilidad y las migraciones de datos/claves para las transiciones solicitadas.
- Produce las migraciones necesarias; no elimines datos en vivo ni ejecutes migraciones de producción incidentalmente.
Reglas de arquitectura
- Usa el diseño completo para cada característica bajo
src/modules/. Cada módulo de característica incluyedto/, un controlador, un servicio, un repositorio y<feature>.module.ts. Mantén un solo controlador, servicio o repositorio en la raíz del módulo. Cuando una capa tenga múltiples archivos, agrúpala encontrollers/,services/orepositories/. Usaerrors/para errores específicos del módulo cuando sea necesario. Coloca los proveedores de soporte bajo infraestructura o trabajos bajo workers cuando no tengan API de característica o acceso a datos. En una revisión con alcance, conserva las rutas existentes a menos que un cambio en el diseño del módulo sea parte de la tarea. - El controlador maneja HTTP; el servicio decide; el repositorio accede a los datos. Sin lógica de negocio, consultas ORM o comandos Redis en los controladores. Los servicios poseen reglas y orquestación. Los repositorios poseen consultas y operaciones Redis, incluyendo escrituras condicionales que imponen invariantes atómicas.
- Componer de manera práctica. Las acciones de negocio entre módulos llaman al servicio propietario. El uso directo de un repositorio exportado está permitido para trabajo solo de datos o transacciones compartidas. No crees métodos de servicio de paso directo por apariencia.
- Mantén la propiedad de la transacción cerca del trabajo. El servicio puede abarcar varios repositorios con un cliente de transacción pasado; el repositorio puede poseer una operación atómica autónoma. Cada participante usa ese cliente. Sin Unidad de Trabajo genérica o marco de transacciones.
- Escribe código pequeño y legible. Reutiliza ayudantes, APIs estándar y dependencias instaladas. Evita opciones especulativas, envoltorios, clases base, repositorios genéricos y abstracciones de un solo uso. Elimina validación redundante y captura-y-relanza; conserva la validación de límites, autorización, concurrencia y protección contra pérdida de datos.
- Reduce el trabajo real. Minimiza consultas, viajes redondos, campos, filas y asignaciones intermedias. Las consultas paralelas por elemento siguen siendo N+1. Equilibra tiempo y espacio para la carga de trabajo; no prometas ambos mínimos absolutos ni debilites el hashing de contraseñas por velocidad.
- Justifica los índices. Vincula cada índice a una consulta real o restricción de integridad. Inspecciona los índices primarios/únicos/compuestos antes de agregar más. No agregues duplicados especulativos ni elimines índices basándote solo en la apariencia del esquema.
- Asigna a Redis un rol. Distingue datos primarios, modelos de lectura preparados y cachés desechables. Define propiedad, población/actualización, TTL, fallo (miss), interrupción (outage) y recuperación. Sin respaldo automático a DB. Los fallos de caché y las fallas de conexión son separados; elige la política de la referencia de datos.
- Comparte solo código compartido. Los ayudantes comunes pertenecen a utils/common, la infraestructura a libs, las configuraciones compartidas a config. Mantén los ayudantes solo de módulo locales. Centraliza las claves Redis y los TTL.
- Posee y tipifica los errores. Define errores de dominio bajo el directorio
errors/del módulo. Lanza elErrorCoderegistrado a través deAppExceptiony traduce sumessageKeyen el límite HTTP. Mantén las consultas internas, trazas de pila, secretos y detalles del proveedor fuera de las respuestas.
Completa y verifica
Actualiza los llamadores necesarios, DTOs, definiciones de error, proveedores/exportaciones, configuración, esquemas/migraciones y pruebas. Implementa fallos importantes así como éxitos.
Para trabajo de cimientos, sigue las comprobaciones de aceptación. Traza el punto de entrada de producción a través del builder y una característica real a través de su repositorio Redis. Verifica Helmet, el contrato de error HTTP localizado, la inicialización y cierre de Redis, y fallo versus interrupción. Verifica 429 y 503 en rutas limitadas reales, y prueba la paginación estable en cada nuevo contrato de lista. Informa cualquier elemento de base que falte o no esté verificado.
La nueva lógica no trivial necesita una pequeña prueba de comportamiento o verificación basada en aserciones. Verifica los invariantes afectados: propiedad, recuento de consultas, reversión, caducidad/reutilización/concurrencia de tokens, fallo versus interrupción de Redis o actualizaciones atómicas. Los movimientos triviales no necesitan una prueba.
Habilidades relacionadas
tecnología-específica– Habilidades que proporcionan documentación de referencia para pilas concretas como PostgreSQL, RabbitMQ, Prisma, etc.componente-específico– Habilidades que proporcionan documentación de componentes desplegables como sistemas de archivos, pruebas, etc.