apolo-81 Express API — Node.js + Express 5
Stack: Node.js + Express 5 + Zod + better-sqlite3 / Prisma + TypeScript (opcional)
Usado en: GHL WA Broadcaster, WA Group Poster y backends de proyectos propios.
1. Estructura de proyecto
src/
├── index.js # Entry point — inicializa app y arranca servidor
├── routes/ # Routers por dominio
│ ├── groups.js
│ ├── posts.js
│ └── auth.js
├── middleware/ # Middleware reutilizable
│ ├── auth.js # Verificación de token/tenant
│ ├── validate.js # Validación Zod
│ └── errorHandler.js
├── services/ # Lógica de negocio (sin Express)
│ └── tenantManager.js
└── lib/
└── db.js # Instancia de DB
2. Setup base
// src/index.js
import express from 'express'
import cors from 'cors'
import { groupsRouter } from './routes/groups.js'
import { errorHandler } from './middleware/errorHandler.js'
const app = express()
// Middleware global
app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(',') || '*' }))
app.use(express.json({ limit: '10mb' }))
app.use(express.urlencoded({ extended: true }))
// Health check
app.get('/health', (req, res) => res.json({ ok: true, ts: Date.now() }))
// Rutas
app.use('/api/groups', groupsRouter)
// Error handler — siempre al final
app.use(errorHandler)
const PORT = process.env.PORT || 3000
app.listen(PORT, () => console.log(`Server running on port ${PORT}`))
3. Router modular
// src/routes/groups.js
import { Router } from 'express'
import { z } from 'zod'
import { validate } from '../middleware/validate.js'
import { tenantMiddleware } from '../middleware/auth.js'
export const groupsRouter = Router()
// Aplicar tenant middleware a todas las rutas del router
groupsRouter.use(tenantMiddleware)
const createGroupSchema = z.object({
name: z.string().min(1).max(100),
jid: z.string(),
active: z.boolean().default(true),
})
// GET /api/groups
groupsRouter.get('/', async (req, res, next) => {
try {
const groups = await req.db.all(
'SELECT * FROM groups WHERE location_id = ? ORDER BY created_at DESC',
[req.locationId]
)
res.json(groups)
} catch (err) {
next(err)
}
})
// POST /api/groups
groupsRouter.post('/', validate(createGroupSchema), async (req, res, next) => {
try {
const { name, jid, active } = req.body
const result = await req.db.run(
'INSERT INTO groups (name, jid, active, location_id) VALUES (?, ?, ?, ?)',
[name, jid, active ? 1 : 0, req.locationId]
)
res.status(201).json({ id: result.lastID, name, jid, active })
} catch (err) {
next(err)
}
})
// DELETE /api/groups/:id
groupsRouter.delete('/:id', async (req, res, next) => {
try {
const { id } = req.params
const group = await req.db.get(
'SELECT * FROM groups WHERE id = ? AND location_id = ?',
[id, req.locationId]
)
if (!group) return res.status(404).json({ error: 'Group not found' })
await req.db.run('DELETE FROM groups WHERE id = ?', [id])
res.status(204).send()
} catch (err) {
next(err)
}
})
4. Middleware de validación con Zod
// src/middleware/validate.js
export function validate(schema) {
return (req, res, next) => {
const result = schema.safeParse(req.body)
if (!result.success) {
return res.status(400).json({
error: 'Validation failed',
issues: result.error.flatten().fieldErrors,
})
}
req.body = result.data // datos parseados y tipados
next()
}
}
// Para validar query params
export function validateQuery(schema) {
return (req, res, next) => {
const result = schema.safeParse(req.query)
if (!result.success) {
return res.status(400).json({ error: 'Invalid query params', issues: result.error.flatten() })
}
req.query = result.data
next()
}
}
5. Error handler global
// src/middleware/errorHandler.js
export function errorHandler(err, req, res, next) {
console.error(`[${new Date().toISOString()}] ${req.method} ${req.path}`, err)
// Errores conocidos con status
if (err.status) {
return res.status(err.status).json({ error: err.message })
}
// SQLite unique constraint
if (err.code === 'SQLITE_CONSTRAINT_UNIQUE') {
return res.status(409).json({ error: 'Duplicate entry' })
}
// Prisma unique constraint
if (err.code === 'P2002') {
return res.status(409).json({ error: 'Duplicate entry' })
}
// Default 500
res.status(500).json({
error: process.env.NODE_ENV === 'production' ? 'Internal server error' : err.message,
})
}
// Helper para crear errores con status
export function createError(status, message) {
const err = new Error(message)
err.status = status
return err
}
6. Multi-tenant middleware (patrón GHL/SaaS)
// src/middleware/auth.js
export function tenantMiddleware(req, res, next) {
const locationId = req.headers['x-location-id'] || req.query.location_id
if (!locationId) {
return res.status(401).json({ error: 'Missing location_id' })
}
req.locationId = locationId
next()
}
// JWT Bearer token
export function jwtMiddleware(req, res, next) {
const auth = req.headers.authorization
if (!auth?.startsWith('Bearer ')) {
return res.status(401).json({ error: 'Missing token' })
}
try {
const token = auth.slice(7)
const payload = jwt.verify(token, process.env.JWT_SECRET)
req.user = payload
next()
} catch {
res.status(401).json({ error: 'Invalid token' })
}
}
7. Async wrapper (evitar try/catch repetitivo)
// Wrapper para rutas async — Express 5 maneja errores async nativamente
// En Express 4: usar este wrapper
export const asyncHandler = (fn) => (req, res, next) =>
Promise.resolve(fn(req, res, next)).catch(next)
// Uso:
router.get('/', asyncHandler(async (req, res) => {
const data = await someAsyncOperation()
res.json(data)
}))
Express 5 (recomendado): las rutas async lanzan errores automáticamente — no necesitas el wrapper.
8. Rate limiting
import rateLimit from 'express-rate-limit'
export const apiLimiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutos
max: 100,
standardHeaders: true,
legacyHeaders: false,
message: { error: 'Too many requests, try again later' },
})
// Anti-spam para endpoints sensibles
export const strictLimiter = rateLimit({
windowMs: 60 * 1000, // 1 minuto
max: 5,
message: { error: 'Rate limit exceeded' },
})
// En index.js
app.use('/api/', apiLimiter)
app.use('/api/auth/', strictLimiter)
9. Variables de entorno
PORT=3000
NODE_ENV=production
DATABASE_URL=./data/db.sqlite
JWT_SECRET=your-secret-min-32-chars
ALLOWED_ORIGINS=https://yourapp.com,https://app.gohighlevel.com
10. Package.json base
{
"type": "module",
"scripts": {
"dev": "node --watch src/index.js",
"start": "node src/index.js"
},
"dependencies": {
"express": "^5.0.0",
"zod": "^3.23.0",
"cors": "^2.8.5",
"express-rate-limit": "^7.4.0",
"jsonwebtoken": "^9.0.2",
"better-sqlite3": "^11.0.0"
}
}
11. Patrones de respuesta consistentes
// Siempre mismo formato de respuesta
// Success
res.json({ data: result, meta: { total, page } })
// o simplemente
res.json(result)
// Error
res.status(400).json({ error: 'Mensaje descriptivo', field: 'campo' })
// Created
res.status(201).json({ id: newRecord.id, ...newRecord })
// No content
res.status(204).send()