🚀 Microservice Generator (micro-generate)

micro-generate es un CLI potente y ligero para crear microservicios listos para producción con Node.js, TypeScript, GraphQL (Apollo Server), MongoDB, MySQL (Sequelize) y Redis.

Olvídate del boilerplate. Genera infraestructuras completas, features modulares, queries y mutaciones en segundos con una arquitectura escalable y las mejores prácticas integradas.

📦 Instalación y Uso

No necesitas instalarlo globalmente. Recomendamos usar npx para ejecutar siempre la última versión:

npx micro-generate <comando>

🛠️ Comandos Disponibles

1. Inicializar un Nuevo Proyecto

Crea la estructura base del microservicio, configurando TypeScript, Docker, Variables de Entorno y el Servidor.

npx micro-generate init

• Interactivo: Te preguntará el nombre del proyecto y qué tecnologias habilitar:
  • MongoDB: Soporte nativo con Mongoose.
  • Multi-DB: Posibilidad de añadir múltiples bases de datos MongoDB (ej: users, logs).
  • MySQL: Soporte completo con Sequelize.
  • Multi-DB MySQL: Posibilidad de añadir múltiples bases de datos MySQL.
  • Redis: Cliente para caching y pub/sub.
• Resultado: Un proyecto completo con src/core, src/config, src/db y todo listo para correr npm run dev.

2. Crear una Nueva Feature

Genera un módulo de dominio completo (Vertical Slice Architecture).

npx micro-generate feature

• Te pedirá: Nombre del feature (ej: users, orders).
• Tecnologías: Puedes seleccionar si la feature usa MongoDB, MySQL o Redis.
• Multi-DB: Si tienes múltiples bases de datos:
  • MongoDB: Te preguntará a cuál colección conectar (ej: users).
  • MySQL: Te preguntará por separado a cuál base de datos conectar (ej: archive).
  • Redis: Te preguntará a qué número de base de datos conectar (defecto 0).
• Genera: Carpeta en src/features/<nombre> con:
  • typeDefs.ts: Esquemas GraphQL.
  • resolvers.ts: Controladores.
  • service.ts: Lógica de negocio (con inyección del modelo correcto).
  • model.ts: Modelo Mongoose o Sequelize (según selección).
• Automático: Registra la feature en el index.ts principal.

3. Agregar una Query (Consulta)

Agrega una nueva consulta GraphQL a una feature existente sin tocar el código manualmente.

npx micro-generate query

• Flujo: Seleccionas la feature de una lista -> Escribes el nombre -> Defines el tipo de retorno.
• Magia: Inyecta automáticamente la definición en typeDefs y el esqueleto de la función en resolvers.

4. Agregar una Mutation (Mutación)

Agrega una nueva mutación para modificar datos.

npx micro-generate mutation

• Similar a query, ideal para operaciones de creación, actualización o eliminación (CRUD).

5. Agregar una Tecnología (add)

Permite conectar tecnologías de almacenamiento o base de datos a un proyecto que ya fue inicializado sin ellas, o bien añadir conexiones secundarias si la tecnología ya está presente.

npx micro-generate add <redis | mongo | mysql>

• Interactivo: Si se ejecuta sin flags, el CLI te guiará para ingresar la configuración (nombres de base de datos por defecto y secundarias).
• Instalación automática: Modifica package.json agregando las dependencias necesarias (ioredis, mongoose o sequelize y mysql2).
• Inyección de Código: Inyecta de forma segura los imports, declaraciones de conexión e inicializaciones dentro de src/index.ts y actualiza tus archivos .env y .env.example.
• Incremental: Si ejecutas add mongo o add mysql en un proyecto donde ya están configurados, el CLI detectará la presencia y te permitirá agregar únicamente bases de datos secundarias nuevas de manera transparente.

🤖 Referencia de Flags (Modo Headless)

Todos los comandos pueden ejecutarse sin prompts interactivos usando los siguientes flags.

init (Inicializar Proyecto)

| Flag | Descripción | Ejemplo | |------|-------------|---------| | -n, --name <nombre> | Nombre del proyecto | -n my-api | | --mongo / --no-mongo | Habilita/Deshabilita MongoDB | --no-mongo | | --mysql / --no-mysql | Habilita/Deshabilita MySQL | --mysql | | --redis / --no-redis | Habilita/Deshabilita Redis | --redis | | --mongo-dbs <lista> | DBs adicionales Mongo (separadas por coma)| --mongo-dbs "logs,users" | | --mysql-dbs <lista> | DBs adicionales MySQL (separadas por coma)| --mysql-dbs "archive,stats" |

add (Agregar Tecnología)

| Flag | Descripción | Ejemplo | |------|-------------|---------| | <technology> | Tecnología a agregar (redis, mongo, mysql) | mongo | | -n, --name <nombre> | Nombre de la base de datos por defecto (para Mongo/MySQL) | -n billing_db | | -s, --secondary <lista>| Bases de datos secundarias (separadas por coma) | -s "logs,archive" |

feature (Crear Feature)

| Flag | Descripción | Ejemplo | |------|-------------|---------| | -n, --name <nombre> | Nombre de la feature | -n orders | | --mongo / --no-mongo | Habilita/Deshabilita MongoDB | --mongo | | --mysql / --no-mysql | Habilita/Deshabilita MySQL | --mysql | | --redis / --no-redis | Habilita/Deshabilita Redis | --redis | | --db-connection <nombre>| Nombre de la conexión Mongo (Multi-DB) | --db-connection logs | | --mysql-connection <nombre>| Nombre de la conexión MySQL (Multi-DB) | --mysql-connection main | | --redis-db <número> | Número de base de datos Redis (0-15) | --redis-db 1 |

query y mutation

| Flag | Descripción | Ejemplo | |------|-------------|---------| | -f, --feature <nombre> | Feature objetivo | -f users | | -n, --name <nombre> | Nombre de la query/mutation | -n getUser | | -r, --return-type <tipo> | Tipo de retorno GraphQL | -r UserResponse |

Ejemplos:

# Crear feature con MySQL y Redis conectada a DB 'logs'
npx micro-generate feature --name "notifications" --mysql --redis --mysql-connection "logs"

# Agregar Query a feature existente
npx micro-generate query --feature "users" --name "getUserByEmail" --return-type "User"

# Agregar MongoDB con bases de datos secundarias
npx micro-generate add mongo --name "core_db" --secondary "analytics,reports"

📊 Arquitectura y Flujo de Trabajo

Flujo de Comandos del CLI

flowchart TD
    CLI[npx micro-generate] --> Init[init]
    CLI --> Add[add]
    CLI --> Feature[feature]
    CLI --> Query[query / mutation]

    Init -->|Crea proyecto| Base[Estructura Base: src/index.ts, src/core...]
    
    Add -->|Inyecta| Redis[Redis Connector: ioredis]
    Add -->|Inyecta| Mongo[MongoDB Connector: Mongoose]
    Add -->|Inyecta| MySQL[MySQL Connector: Sequelize]
    
    Feature -->|Genera módulo| Mod[src/features/featureName: typeDefs, resolvers, service, model]
    
    Query -->|Inyecta| QDef[Modifica typeDefs.ts & resolvers.ts]

Ciclo de Inyección de Tecnologías (add)

sequenceDiagram
    actor Developer
    participant CLI as CLI (micro-generate add)
    participant FS as Filesystem (Project Root)
    participant Index as src/index.ts

    Developer->>CLI: micro-generate add mongo -s secondary_db
    CLI->>FS: Check if src/index.ts exists
    alt MongoDB ya configurado
        CLI->>FS: Leer index.ts y .env actuales
        CLI->>FS: Agregar variable de entorno (MONGODB_URI_SECONDARY_DB)
        CLI->>Index: Inyectar nueva conexión en el objeto secondaryConnections
    else MongoDB no configurado
        CLI->>FS: Crear src/database/mongo.ts y client.ts
        CLI->>FS: Añadir dependencia mongoose a package.json
        CLI->>FS: Escribir variables de entorno en .env y .env.example
        CLI->>Index: Inyectar imports, configuración y registro del conector
    end
    CLI-->>Developer: Confirmación de éxito

🧠 IA & Agent Ready

Cada proyecto generado incluye automáticamente una Skill de Antigravity en .agent/skills/micro-generate. Esto permite que agentes de IA (como Antigravity o Cline) puedan leer las instrucciones y manipular el proyecto por ti usando los comandos del CLI.

🔥 Características Principales

• ⚡ Stack Moderno: Node.js 20+, TypeScript 5, Apollo Server 4.
• 🧠 GraphQL Modular: Arquitectura basada en features autotencidos.
• 🛡️ Type-Safety: Validación de variables de entorno con Zod.
• 🗄️ Bases de Datos:
  • MongoDB (Mongoose): Conexiones primarias y secundarias automáticas.
  • MySQL (Sequelize): Integración completa ORM con soporte multi-schema/multi-db.
  • Redis (ioredis): Patrón Repository incluido con soporte para múltiples bases de datos dinámicas.
• 📝 Logging: Implementación de alto rendimiento con Pino (JSON logs).
• 🛑 Graceful Shutdown: Manejo correcto de señales SIGINT/SIGTERM para evitar conexiones colgadas.
• 🎮 Playground Control: Habilita/deshabilita el Apollo Sandbox vía variables de entorno.

📂 Estructura Generada

my-service/
├── src/
│   ├── config/          # Configuración de entorno y DBs
│   ├── core/            # Servidor central (MicroserviceServer)
│   ├── database/        # Conectores y clientes de bases de datos/cache
│   │   ├── mongo.ts     # Cliente MongoDB principal
│   │   ├── redis.ts     # Cliente y repositorio Redis
│   │   ├── mongo/       # Conectores y helpers de MongoDB
│   │   │   └── client.ts
│   │   └── mysql/       # Conectores y helpers de MySQL (Sequelize)
│   │       └── client.ts
│   ├── features/        # Tu lógica de negocio (módulos)
│   │   ├── users/       # Ejemplo de Feature
│   │   │   ├── typeDefs.ts
│   │   │   ├── resolvers.ts
│   │   │   └── service.ts
│   │   └── index.ts     # Auto-registro de features
│   ├── services/        # Servicios compartidos (ej: llamadas HTTP)
│   │   └── api.ts
│   ├── utils/           # Loggers y helpers de sanitización
│   └── index.ts         # Punto de entrada de la aplicación
├── .env                 # Variables de entorno
├── package.json
└── tsconfig.json

🤝 Contribuyendo

1. Haz un Fork.
2. Crea tu rama de feature (git checkout -b feature/amazing-feature).
3. Commit a tus cambios (git commit -m 'feat: Add amazing feature').
4. Push a la rama (git push origin feature/amazing-feature).
5. Abre un Pull Request.

Generado con ❤️ por Jesus Leiva.