| name | express-microservices-architecture |
| description | Complete guide for building scalable microservices with Express.js including middleware patterns, routing strategies, error handling, production architecture, and deployment best practices |
| tags | ["express","microservices","nodejs","middleware","routing","scalability","architecture","production"] |
| tier | tier-1 |
Express.js Microservices Architecture
A comprehensive skill for building production-ready microservices with Express.js. Master middleware patterns, routing strategies, error handling, scalability techniques, and deployment architectures for Node.js microservices at scale.
When to Use This Skill
Use this skill when:
- Building RESTful APIs and microservices with Node.js
- Designing scalable distributed systems with Express.js
- Implementing middleware-based architecture patterns
- Creating API gateways and service mesh architectures
- Developing production-ready Node.js applications
- Migrating monoliths to microservices architecture
- Building event-driven microservices
- Implementing authentication, authorization, and security layers
- Optimizing Express.js applications for high performance
- Setting up monitoring, logging, and observability
- Deploying Express.js apps with Docker and Kubernetes
- Implementing circuit breakers and resilience patterns
Core Concepts
Express.js Fundamentals
Express.js is a minimal and flexible Node.js web application framework that provides robust features for web and mobile applications. It's the de facto standard for building Node.js APIs and microservices.
Key Characteristics:
- Minimal: Unopinionated framework with essential web app features
- Middleware-based: Request/response pipeline architecture
- Routing: Powerful routing mechanism with parameter support
- Template Engines: Support for various view engines
- Performance: Built on top of Node.js for high performance
- Extensible: Rich ecosystem of middleware and plugins
Middleware Architecture
Middleware functions are the backbone of Express.js applications. They have access to the request object (req), response object (res), and the next middleware function (next).
Middleware Flow:
Request → Middleware 1 → Middleware 2 → ... → Route Handler → Response
↓ ↓ ↓
Error Handler Error Handler Error Handler
Middleware Types:
- Application-level middleware: Bound to
app instance
- Router-level middleware: Bound to
express.Router() instance
- Error-handling middleware: Has 4 parameters (err, req, res, next)
- Built-in middleware: Express built-in functions (static, json, urlencoded)
- Third-party middleware: External packages (cors, helmet, morgan)
Routing Strategies
Express routing enables you to map HTTP methods and URLs to handler functions.
Routing Components:
- Route paths: String patterns, regex, or path parameters
- Route parameters: Named URL segments (:userId)
- Route handlers: Single or multiple callback functions
- Response methods: res.send(), res.json(), res.status(), etc.
- Router instances: Modular, mountable route handlers
Error Handling
Error handling in Express requires special middleware with 4 parameters: (err, req, res, next).
Error Handling Flow:
- Synchronous errors are caught automatically
- Asynchronous errors must be passed to
next(err)
- Error middleware processes errors centrally
- Proper status codes and error formats returned
Microservices Principles
Characteristics of Microservices:
- Single Responsibility: Each service does one thing well
- Independence: Services can be deployed independently
- Decentralized: Each service owns its data
- Resilience: Failure in one service doesn't crash entire system
- Scalability: Scale services independently based on demand
- Technology Diversity: Different services can use different tech stacks
Microservices Patterns
Pattern 1: API Gateway Pattern
The API Gateway acts as a single entry point for all client requests, routing them to appropriate microservices.
Benefits:
- Single entry point for clients
- Request routing and composition
- Authentication and authorization
- Rate limiting and throttling
- Request/response transformation
- Protocol translation
Implementation Structure:
Client → API Gateway → Microservice 1 (Users)
→ Microservice 2 (Orders)
→ Microservice 3 (Products)
→ Microservice 4 (Notifications)
Pattern 2: Service Discovery
Services register themselves and discover other services dynamically.
Approaches:
- Client-side discovery: Client queries service registry
- Server-side discovery: Load balancer queries registry
- DNS-based discovery: Using DNS for service location
Popular Tools:
- Consul
- Eureka
- etcd
- Kubernetes built-in discovery
Pattern 3: Circuit Breaker
Prevents cascading failures by stopping requests to failing services.
States:
- Closed: Normal operation, requests pass through
- Open: Service failing, requests fail immediately
- Half-Open: Testing if service recovered
Pattern 4: Event-Driven Architecture
Services communicate through events instead of direct calls.
Components:
- Event producers: Services that emit events
- Event consumers: Services that listen to events
- Message broker: RabbitMQ, Kafka, Redis
- Event store: Persist events for replay
Pattern 5: Database per Service
Each microservice owns its database, ensuring loose coupling.
Benefits:
- Service independence
- Technology diversity
- Easier scaling
- Clear boundaries
Challenges:
- Distributed transactions
- Data consistency
- Joins across services
Pattern 6: Saga Pattern
Manages distributed transactions across multiple services.
Types:
- Choreography: Services coordinate through events
- Orchestration: Central coordinator manages transaction
Pattern 7: CQRS (Command Query Responsibility Segregation)
Separate read and write operations into different models.
Benefits:
- Optimized read/write models
- Scalability
- Performance
- Flexibility
Middleware Architecture Patterns
Custom Middleware Development
Middleware functions execute in the order they're defined.
Basic Middleware Structure:
const express = require('express');
const app = express();
const requestLogger = (req, res, next) => {
console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
next();
};
app.use(requestLogger);
From Context7 - Saving Data in Request Object:
const express = require('express');
const app = express();
const port = 3000;
const addUserInfo = (req, res, next) => {
req.user = {
id: 123,
username: 'testuser'
};
next();
};
const addTimestamp = (req, res, next) => {
req.requestTime = Date.now();
next();
};
app.use(addUserInfo);
app.use(addTimestamp);
app.get('/', (req, res) => {
const userId = req.user.id;
const username = req.user.username;
const timestamp = req.requestTime;
res.send(`User ID: ${userId}, Username: ${username}, Request Time: ${new Date(timestamp).toISOString()}`);
});
app.listen(port, () => {
console.log(`Request data sharing example listening at http://localhost:${port}`);
});
Error-Handling Middleware
Error middleware has 4 parameters and should be defined after all other middleware.
From Context7 - Error Handling Middleware:
const express = require('express');
const app = express();
const port = 3000;
app.use((req, res, next) => {
console.log('Request received');
next();
});
app.get('/throw-error', (req, res, next) => {
const error = new Error('This is a simulated error');
error.status = 400;
next(error);
});
app.use((err, req, res, next) => {
console.error('Error caught:', err.message);
res.status(err.status || 500).send(`An error occurred: ${err.message}`);
});
app.listen(port, () => {
console.log(`Error middleware example listening at http://localhost:${port}`);
});
From Context7 - Global Error Handler:
app.use(express.bodyParser())
app.use(express.cookieParser())
app.use(express.session())
app.use(app.router)
app.use(function(err, req, res, next){
res.send(500, { error: 'Sorry something bad happened!' });
})
Route-Specific Middleware
Apply middleware to specific routes for targeted functionality.
From Context7 - Route Middleware:
const express = require('express');
const app = express();
const port = 3000;
const requestLogger = (req, res, next) => {
console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
next();
};
app.get('/protected', requestLogger, (req, res) => {
res.send('This route is protected by middleware!');
});
const adminMiddleware = (req, res, next) => {
console.log('Admin access check...');
next();
};
app.get('/admin/dashboard', adminMiddleware, (req, res) => {
res.send('Welcome to the admin dashboard!');
});
app.use(requestLogger);
app.get('/', (req, res) => {
res.send('Hello, world!');
});
app.listen(port, () => {
console.log(`Route middleware example listening at http://localhost:${port}`);
});
Authentication Middleware
const jwt = require('jsonwebtoken');
const authenticateToken = (req, res, next) => {
const authHeader = req.headers['authorization'];
const token = authHeader && authHeader.split(' ')[1];
if (!token) {
return res.status(401).json({ error: 'Access token required' });
}
jwt.verify(token, process.env.JWT_SECRET, (err, user) => {
if (err) {
return res.status(403).json({ error: 'Invalid or expired token' });
}
req.user = user;
next();
});
};
const authorize = (...roles) => {
return (req, res, next) => {
if (!req.user) {
return res.status(401).json({ error: 'Unauthorized' });
}
if (!roles.includes(req.user.role)) {
return res.status(403).json({ error: 'Insufficient permissions' });
}
next();
};
};
app.get('/admin/users', authenticateToken, authorize('admin'), (req, res) => {
res.json({ users: [] });
});
Request Validation Middleware
const { body, param, query, validationResult } = require('express-validator');
const validate = (validations) => {
return async (req, res, next) => {
await Promise.all(validations.map(validation => validation.run(req)));
const errors = validationResult(req);
if (errors.isEmpty()) {
return next();
}
res.status(400).json({
error: 'Validation failed',
details: errors.array()
});
};
};
app.post('/users', validate([
body('email').isEmail().normalizeEmail(),
body('password').isLength({ min: 8 }),
body('name').trim().notEmpty()
]), (req, res) => {
res.json({ success: true });
});
Rate Limiting Middleware
const rateLimit = require('express-rate-limit');
const RedisStore = require('rate-limit-redis');
const Redis = require('ioredis');
const limiter = rateLimit({
windowMs: 15 * 60 * 1000,
max: 100,
message: 'Too many requests, please try again later',
standardHeaders: true,
legacyHeaders: false,
});
const redisClient = new Redis({
host: process.env.REDIS_HOST,
port: process.env.REDIS_PORT,
});
const distributedLimiter = rateLimit({
store: new RedisStore({
client: redisClient,
prefix: 'rl:',
}),
windowMs: 15 * 60 * 1000,
max: 100,
});
app.use('/api/', distributedLimiter);
app.post('/api/login', rateLimit({
windowMs: 15 * 60 * 1000,
max: 5,
}), loginHandler);
Logging Middleware
const morgan = require('morgan');
const winston = require('winston');
const { format } = winston;
const logger = winston.createLogger({
level: 'info',
format: format.combine(
format.timestamp(),
format.errors({ stack: true }),
format.json()
),
defaultMeta: { service: 'user-service' },
transports: [
new winston.transports.File({ filename: 'error.log', level: 'error' }),
new winston.transports.File({ filename: 'combined.log' }),
],
});
if (process.env.NODE_ENV !== 'production') {
logger.add(new winston.transports.Console({
format: format.combine(
format.colorize(),
format.simple()
)
}));
}
app.use(morgan('combined', {
stream: {
write: (message) => logger.info(message.trim())
}
}));
const requestLogger = (req, res, next) => {
const start = Date.now();
res.on('finish', () => {
const duration = Date.now() - start;
logger.info({
method: req.method,
path: req.path,
status: res.statusCode,
duration: `${duration}ms`,
ip: req.ip,
userAgent: req.get('user-agent')
});
});
next();
};
app.use(requestLogger);
CORS Middleware
const cors = require('cors');
app.use(cors());
const corsOptions = {
origin: function (origin, callback) {
const allowedOrigins = [
'https://example.com',
'https://app.example.com',
process.env.FRONTEND_URL
];
if (!origin || allowedOrigins.includes(origin)) {
callback(null, true);
} else {
callback(new Error('Not allowed by CORS'));
}
},
credentials: true,
optionsSuccessStatus: 200,
methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
allowedHeaders: ['Content-Type', 'Authorization'],
exposedHeaders: ['X-Total-Count', 'X-Page-Number'],
maxAge: 86400,
};
app.use(cors(corsOptions));
app.options('/api/admin/*', cors(adminCorsOptions));
app.use('/api/admin/', cors(adminCorsOptions));
Security Middleware
const helmet = require('helmet');
const mongoSanitize = require('express-mongo-sanitize');
const xss = require('xss-clean');
const hpp = require('hpp');
app.use(helmet());
app.use((req, res, next) => {
res.setHeader('X-Content-Type-Options', 'nosniff');
res.setHeader('X-Frame-Options', 'DENY');
res.setHeader('X-XSS-Protection', '1; mode=block');
next();
});
app.use(mongoSanitize());
app.use(xss());
app.use(hpp({
whitelist: ['sort', 'fields', 'page', 'limit']
}));
app.use(helmet.contentSecurityPolicy({
directives: {
defaultSrc: ["'self'"],
styleSrc: ["'self'", "'unsafe-inline'"],
scriptSrc: ["'self'"],
imgSrc: ["'self'", 'data:', 'https:'],
},
}));
Routing Strategies
Basic Routing
From Context7 - Express Routing:
app.get('/', home);
app.use('/public', require('st')(process.cwd()));
app.get('/users', users.list);
app.post('/users', users.create);
Route Method Chaining
From Context7 - Route Chaining:
app.route('/users')
.get(function(req, res, next) {
res.json({ users: [] });
})
.post(function(req, res, next) {
res.status(201).json({ user: {} });
});
Router Modules
const express = require('express');
const router = express.Router();
router.use((req, res, next) => {
console.log('Time: ', Date.now());
next();
});
router.get('/', (req, res) => {
res.json({ users: [] });
});
router.get('/:id', (req, res) => {
res.json({ user: { id: req.params.id } });
});
router.post('/', (req, res) => {
res.status(201).json({ user: req.body });
});
router.put('/:id', (req, res) => {
res.json({ user: { id: req.params.id, ...req.body } });
});
router.delete('/:id', (req, res) => {
res.status(204).send();
});
module.exports = router;
const usersRouter = require('./routes/users');
app.use('/api/users', usersRouter);
Route Parameters
app.get('/users/:userId/posts/:postId', (req, res) => {
const { userId, postId } = req.params;
res.json({ userId, postId });
});
app.param('userId', (req, res, next, userId) => {
User.findById(userId)
.then(user => {
if (!user) {
return res.status(404).json({ error: 'User not found' });
}
req.user = user;
next();
})
.catch(next);
});
app.param('postId', [
validatePostId,
fetchPost,
checkPermissions
]);
Query Parameters
app.get('/api/users', (req, res) => {
const {
role,
active,
page = 1,
limit = 10,
sort = '-createdAt'
} = req.query;
const query = {};
if (role) query.role = role;
if (active !== undefined) query.active = active === 'true';
const skip = (page - 1) * limit;
User.find(query)
.sort(sort)
.limit(parseInt(limit))
.skip(skip)
.then(users => res.json({ users, page, limit }))
.catch(next);
});
API Versioning
const v1Router = express.Router();
v1Router.get('/users', (req, res) => {
res.json({ version: 'v1', users: [] });
});
const v2Router = express.Router();
v2Router.get('/users', (req, res) => {
res.json({ version: 'v2', users: [], meta: {} });
});
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);
app.use('/api/users', (req, res, next) => {
const version = req.headers['api-version'] || 'v1';
if (version === 'v2') {
return v2UsersHandler(req, res, next);
}
return v1UsersHandler(req, res, next);
});
RESTful Route Organization
class UsersController {
async list(req, res, next) {
try {
const users = await User.find();
res.json({ users });
} catch (error) {
next(error);
}
}
async get(req, res, next) {
try {
res.json({ user: req.user });
} catch (error) {
next(error);
}
}
async create(req, res, next) {
try {
const user = await User.create(req.body);
res.status(201).json({ user });
} catch (error) {
next(error);
}
}
async update(req, res, next) {
try {
const user = await User.findByIdAndUpdate(
req.params.id,
req.body,
{ new: true, runValidators: true }
);
res.json({ user });
} catch (error) {
next(error);
}
}
async delete(req, res, next) {
try {
await User.findByIdAndDelete(req.params.id);
res.status(204).send();
} catch (error) {
next(error);
}
}
}
const router = express.Router();
const controller = new UsersController();
router.get('/', controller.list);
router.get('/:id', controller.get);
router.post('/', controller.create);
router.put('/:id', controller.update);
router.delete('/:id', controller.delete);
module.exports = router;
Scalability Patterns
Horizontal Scaling
Deploy multiple instances of your service behind a load balancer.
const cluster = require('cluster');
const os = require('os');
if (cluster.isMaster) {
const numCPUs = os.cpus().length;
console.log(`Master process ${process.pid} is running`);
console.log(`Forking ${numCPUs} workers...`);
for (let i = 0; i < numCPUs; i++) {
cluster.fork();
}
cluster.on('exit', (worker, code, signal) => {
console.log(`Worker ${worker.process.pid} died. Restarting...`);
cluster.fork();
});
} else {
const app = require('./app');
const port = process.env.PORT || 3000;
app.listen(port, () => {
console.log(`Worker ${process.pid} started on port ${port}`);
});
}
Load Balancing
# nginx.conf
upstream backend {
least_conn;
server localhost:3001;
server localhost:3002;
server localhost:3003;
server localhost:3004;
}
server {
listen 80;
location / {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
Caching Strategies
const Redis = require('ioredis');
const redis = new Redis({
host: process.env.REDIS_HOST,
port: process.env.REDIS_PORT,
});
const cacheMiddleware = (duration = 300) => {
return async (req, res, next) => {
if (req.method !== 'GET') {
return next();
}
const key = `cache:${req.originalUrl}`;
try {
const cached = await redis.get(key);
if (cached) {
return res.json(JSON.parse(cached));
}
const originalJson = res.json.bind(res);
res.json = (body) => {
redis.setex(key, duration, JSON.stringify(body));
return originalJson(body);
};
next();
} catch (error) {
console.error('Cache error:', error);
next();
}
};
};
app.get('/api/products', cacheMiddleware(600), async (req, res) => {
const products = await Product.find();
res.json({ products });
});
const invalidateCache = async (pattern) => {
const keys = await redis.keys(pattern);
if (keys.length > 0) {
await redis.del(...keys);
}
};
app.post('/api/products', async (req, res) => {
const product = await Product.create(req.body);
await invalidateCache('cache:/api/products*');
res.status(201).json({ product });
});
Database Connection Pooling
const mongoose = require('mongoose');
mongoose.connect(process.env.MONGODB_URI, {
useNewUrlParser: true,
useUnifiedTopology: true,
poolSize: 10,
socketTimeoutMS: 45000,
family: 4,
});
const { Pool } = require('pg');
const pool = new Pool({
host: process.env.DB_HOST,
port: process.env.DB_PORT,
database: process.env.DB_NAME,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
max: 20,
idleTimeoutMillis: 30000,
connectionTimeoutMillis: 2000,
});
const query = async (text, params) => {
const start = Date.now();
const res = await pool.query(text, params);
const duration = Date.now() - start;
console.log('Executed query', { text, duration, rows: res.rowCount });
return res;
};
module.exports = { query, pool };
Response Compression
const compression = require('compression');
app.use(compression());
app.use(compression({
filter: (req, res) => {
if (req.headers['x-no-compression']) {
return false;
}
return compression.filter(req, res);
},
level: 6,
threshold: 1024,
}));
Request Throttling
const { Throttle } = require('stream-throttle');
app.get('/api/large-dataset', (req, res) => {
const dataStream = getLargeDataStream();
const throttle = new Throttle({ rate: 1024 * 1024 });
res.setHeader('Content-Type', 'application/json');
dataStream.pipe(throttle).pipe(res);
});
Production Architecture
Docker Containerization
# Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
# Copy package files
COPY package*.json ./
# Install dependencies
RUN npm ci --only=production
# Copy source code
COPY . .
# Production image
FROM node:18-alpine
WORKDIR /app
# Create non-root user
RUN addgroup -g 1001 -S nodejs && \
adduser -S nodejs -u 1001
# Copy from builder
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --chown=nodejs:nodejs . .
# Switch to non-root user
USER nodejs
# Expose port
EXPOSE 3000
# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s \
CMD node healthcheck.js
# Start application
CMD ["node", "server.js"]
version: '3.8'
services:
api:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- REDIS_HOST=redis
- MONGODB_URI=mongodb://mongo:27017/app
depends_on:
- redis
- mongo
restart: unless-stopped
deploy:
replicas: 3
resources:
limits:
cpus: '0.5'
memory: 512M
redis:
image: redis:7-alpine
volumes:
- redis-data:/data
restart: unless-stopped
mongo:
image: mongo:6
volumes:
- mongo-data:/data/db
restart: unless-stopped
nginx:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
depends_on:
- api
restart: unless-stopped
volumes:
redis-data:
mongo-data:
Process Management with PM2
module.exports = {
apps: [{
name: 'api',
script: './server.js',
instances: 'max',
exec_mode: 'cluster',
autorestart: true,
watch: false,
max_memory_restart: '1G',
env: {
NODE_ENV: 'development',
PORT: 3000
},
env_production: {
NODE_ENV: 'production',
PORT: 3000
},
error_file: './logs/err.log',
out_file: './logs/out.log',
log_file: './logs/combined.log',
time: true,
merge_logs: true,
}]
};
Health Checks
const http = require('http');
const options = {
host: 'localhost',
port: process.env.PORT || 3000,
path: '/health',
timeout: 2000
};
const healthCheck = http.request(options, (res) => {
console.log(`HEALTHCHECK STATUS: ${res.statusCode}`);
if (res.statusCode === 200) {
process.exit(0);
} else {
process.exit(1);
}
});
healthCheck.on('error', (err) => {
console.error('ERROR:', err);
process.exit(1);
});
healthCheck.end();
app.get('/health', async (req, res) => {
const health = {
uptime: process.uptime(),
message: 'OK',
timestamp: Date.now()
};
try {
await mongoose.connection.db.admin().ping();
health.database = 'connected';
await redis.ping();
health.cache = 'connected';
res.status(200).json(health);
} catch (error) {
health.message = error.message;
res.status(503).json(health);
}
});
app.get('/ready', (req, res) => {
res.status(200).json({ ready: true });
});
app.get('/live', (req, res) => {
res.status(200).json({ alive: true });
});
Graceful Shutdown
const gracefulShutdown = () => {
console.log('Received shutdown signal, closing server gracefully...');
server.close(async () => {
console.log('HTTP server closed');
try {
await mongoose.connection.close();
console.log('MongoDB connection closed');
await redis.quit();
console.log('Redis connection closed');
console.log('Graceful shutdown completed');
process.exit(0);
} catch (err) {
console.error('Error during shutdown:', err);
process.exit(1);
}
});
setTimeout(() => {
console.error('Forcing shutdown after timeout');
process.exit(1);
}, 10000);
};
process.on('SIGTERM', gracefulShutdown);
process.on('SIGINT', gracefulShutdown);
Monitoring and Observability
const promClient = require('prom-client');
const register = new promClient.Registry();
promClient.collectDefaultMetrics({ register });
const httpRequestDuration = new promClient.Histogram({
name: 'http_request_duration_seconds',
help: 'Duration of HTTP requests in seconds',
labelNames: ['method', 'route', 'status_code'],
buckets: [0.1, 0.5, 1, 2, 5]
});
const httpRequestTotal = new promClient.Counter({
name: 'http_requests_total',
help: 'Total number of HTTP requests',
labelNames: ['method', 'route', 'status_code']
});
register.registerMetric(httpRequestDuration);
register.registerMetric(httpRequestTotal);
app.use((req, res, next) => {
const start = Date.now();
res.on('finish', () => {
const duration = (Date.now() - start) / 1000;
const route = req.route ? req.route.path : req.path;
httpRequestDuration.labels(req.method, route, res.statusCode).observe(duration);
httpRequestTotal.labels(req.method, route, res.statusCode).inc();
});
next();
});
app.get('/metrics', async (req, res) => {
res.set('Content-Type', register.contentType);
res.end(await register.metrics());
});
Distributed Tracing
const { trace, context } = require('@opentelemetry/api');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
const provider = new NodeTracerProvider();
provider.register();
registerInstrumentations({
instrumentations: [
new HttpInstrumentation(),
new ExpressInstrumentation(),
],
});
const tracer = trace.getTracer('user-service');
const tracingMiddleware = (req, res, next) => {
const span = tracer.startSpan(`HTTP ${req.method} ${req.path}`);
span.setAttributes({
'http.method': req.method,
'http.url': req.url,
'http.user_agent': req.get('user-agent'),
});
res.on('finish', () => {
span.setAttributes({
'http.status_code': res.statusCode,
});
span.end();
});
next();
};
app.use(tracingMiddleware);
Best Practices
Project Structure
express-microservice/
├── src/
│ ├── config/
│ │ ├── database.js
│ │ ├── redis.js
│ │ └── logger.js
│ ├── controllers/
│ │ ├── users.controller.js
│ │ └── auth.controller.js
│ ├── middleware/
│ │ ├── auth.js
│ │ ├── validation.js
│ │ ├── errorHandler.js
│ │ └── requestLogger.js
│ ├── models/
│ │ └── user.model.js
│ ├── routes/
│ │ ├── index.js
│ │ ├── users.routes.js
│ │ └── auth.routes.js
│ ├── services/
│ │ ├── users.service.js
│ │ ├── auth.service.js
│ │ └── email.service.js
│ ├── utils/
│ │ ├── apiError.js
│ │ ├── catchAsync.js
│ │ └── validators.js
│ ├── app.js
│ └── server.js
├── tests/
│ ├── unit/
│ ├── integration/
│ └── e2e/
├── .env
├── .env.example
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
├── ecosystem.config.js
├── package.json
└── README.md
Environment Configuration
const dotenv = require('dotenv');
const Joi = require('joi');
dotenv.config();
const envSchema = Joi.object({
NODE_ENV: Joi.string()
.valid('development', 'production', 'test')
.default('development'),
PORT: Joi.number().default(3000),
MONGODB_URI: Joi.string().required(),
REDIS_HOST: Joi.string().required(),
REDIS_PORT: Joi.number().default(6379),
JWT_SECRET: Joi.string().required(),
JWT_EXPIRES_IN: Joi.string().default('7d'),
LOG_LEVEL: Joi.string()
.valid('error', 'warn', 'info', 'debug')
.default('info'),
}).unknown();
const { value: env, error } = envSchema.validate(process.env);
if (error) {
throw new Error(`Config validation error: ${error.message}`);
}
module.exports = {
env: env.NODE_ENV,
port: env.PORT,
mongodb: {
uri: env.MONGODB_URI,
},
redis: {
host: env.REDIS_HOST,
port: env.REDIS_PORT,
},
jwt: {
secret: env.JWT_SECRET,
expiresIn: env.JWT_EXPIRES_IN,
},
logging: {
level: env.LOG_LEVEL,
},
};
Error Handling Best Practices
class ApiError extends Error {
constructor(statusCode, message, isOperational = true, stack = '') {
super(message);
this.statusCode = statusCode;
this.isOperational = isOperational;
if (stack) {
this.stack = stack;
} else {
Error.captureStackTrace(this, this.constructor);
}
}
}
module.exports = ApiError;
const catchAsync = (fn) => {
return (req, res, next) => {
Promise.resolve(fn(req, res, next)).catch(next);
};
};
module.exports = catchAsync;
const config = require('../config/env');
const logger = require('../config/logger');
const ApiError = require('../utils/apiError');
const errorConverter = (err, req, res, next) => {
let error = err;
if (!(error instanceof ApiError)) {
const statusCode = error.statusCode || 500;
const message = error.message || 'Internal Server Error';
error = new ApiError(statusCode, message, false, err.stack);
}
next(error);
};
const errorHandler = (err, req, res, next) => {
let { statusCode, message } = err;
if (config.env === 'production' && !err.isOperational) {
statusCode = 500;
message = 'Internal Server Error';
}
res.locals.errorMessage = err.message;
const response = {
code: statusCode,
message,
...(config.env === 'development' && { stack: err.stack }),
};
if (config.env === 'development') {
logger.error(err);
}
res.status(statusCode).json(response);
};
module.exports = {
errorConverter,
errorHandler,
};
Testing Strategies
const request = require('supertest');
const app = require('../../src/app');
const { User } = require('../../src/models');
describe('User API', () => {
beforeEach(async () => {
await User.deleteMany({});
});
describe('POST /api/users', () => {
it('should create a new user', async () => {
const userData = {
name: 'John Doe',
email: 'john@example.com',
password: 'password123',
};
const res = await request(app)
.post('/api/users')
.send(userData)
.expect(201);
expect(res.body).toHaveProperty('user');
expect(res.body.user).toHaveProperty('id');
expect(res.body.user.email).toBe(userData.email);
expect(res.body.user).not.toHaveProperty('password');
});
it('should return 400 for invalid email', async () => {
const userData = {
name: 'John Doe',
email: 'invalid-email',
password: 'password123',
};
const res = await request(app)
.post('/api/users')
.send(userData)
.expect(400);
expect(res.body).toHaveProperty('error');
});
});
describe('GET /api/users/:id', () => {
it('should return user by id', async () => {
const user = await User.create({
name: 'John Doe',
email: 'john@example.com',
password: 'hashedpassword',
});
const res = await request(app)
.get(`/api/users/${user.id}`)
.expect(200);
expect(res.body.user.id).toBe(user.id);
});
it('should return 404 for non-existent user', async () => {
await request(app)
.get('/api/users/507f1f77bcf86cd799439011')
.expect(404);
});
});
});
Performance Optimization
const compression = require('compression');
app.use(compression());
app.use(express.json({ limit: '10mb' }));
const getUsers = async (filters) => {
return User.find(filters)
.select('name email role')
.lean()
.limit(100);
};
const paginateResults = async (model, page = 1, limit = 10) => {
const skip = (page - 1) * limit;
const [results, total] = await Promise.all([
model.find().skip(skip).limit(limit).lean(),
model.countDocuments(),
]);
return {
results,
pagination: {
page,
limit,
total,
pages: Math.ceil(total / limit),
},
};
};
userSchema.index({ email: 1 });
userSchema.index({ role: 1, createdAt: -1 });
const agent = new http.Agent({
keepAlive: true,
maxSockets: 50,
});
Security Best Practices
const { body } = require('express-validator');
const userValidation = [
body('email').isEmail().normalizeEmail(),
body('password').isLength({ min: 8 }).trim(),
body('name').trim().escape(),
];
const loginLimiter = rateLimit({
windowMs: 15 * 60 * 1000,
max: 5,
skipSuccessfulRequests: true,
});
app.post('/api/auth/login', loginLimiter, loginHandler);
const getUserByEmail = async (email) => {
return User.findOne({ email });
};
const csrf = require('csurf');
app.use(csrf({ cookie: true }));
res.cookie('token', token, {
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
sameSite: 'strict',
maxAge: 7 * 24 * 60 * 60 * 1000,
});
const bcrypt = require('bcrypt');
const hashPassword = async (password) => {
return bcrypt.hash(password, 12);
};
Examples
Example 1: Basic Express Microservice
const express = require('express');
const helmet = require('helmet');
const cors = require('cors');
const morgan = require('morgan');
const app = express();
app.use(helmet());
app.use(cors());
app.use(morgan('combined'));
app.use(express.json());
app.get('/health', (req, res) => {
res.json({ status: 'healthy' });
});
app.get('/api/users', (req, res) => {
res.json({ users: [] });
});
app.use((err, req, res, next) => {
console.error(err.stack);
res.status(500).json({ error: 'Something went wrong!' });
});
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`Server running on port ${PORT}`);
});
Example 2: Authentication Service
const express = require('express');
const jwt = require('jsonwebtoken');
const bcrypt = require('bcrypt');
const { body, validationResult } = require('express-validator');
const router = express.Router();
router.post('/register',
body('email').isEmail(),
body('password').isLength({ min: 8 }),
async (req, res, next) => {
try {
const errors = validationResult(req);
if (!errors.isEmpty()) {
return res.status(400).json({ errors: errors.array() });
}
const { email, password } = req.body;
const existingUser = await User.findOne({ email });
if (existingUser) {
return res.status(409).json({ error: 'User already exists' });
}
const hashedPassword = await bcrypt.hash(password, 12);
const user = await User.create({
email,
password: hashedPassword,
});
const token = jwt.sign(
{ userId: user.id },
process.env.JWT_SECRET,
{ expiresIn: '7d' }
);
res.status(201).json({ token, user: { id: user.id, email: user.email } });
} catch (error) {
next(error);
}
}
);
router.post('/login',
body('email').isEmail(),
body('password').exists(),
async (req, res, next) => {
try {
const errors = validationResult(req);
if (!errors.isEmpty()) {
return res.status(400).json({ errors: errors.array() });
}
const { email, password } = req.body;
const user = await User.findOne({ email }).select('+password');
if (!user) {
return res.status(401).json({ error: 'Invalid credentials' });
}
const isValidPassword = await bcrypt.compare(password, user.password);
if (!isValidPassword) {
return res.status(401).json({ error: 'Invalid credentials' });
}
const token = jwt.sign(
{ userId: user.id },
process.env.JWT_SECRET,
{ expiresIn: '7d' }
);
res.json({ token, user: { id: user.id, email: user.email } });
} catch (error) {
next(error);
}
}
);
module.exports = router;
Example 3: API Gateway Pattern
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');
const app = express();
const services = {
users: 'http://users-service:3001',
products: 'http://products-service:3002',
orders: 'http://orders-service:3003',
};
const authenticate = (req, res, next) => {
const token = req.headers.authorization?.split(' ')[1];
if (!token) {
return res.status(401).json({ error: 'No token provided' });
}
try {
const decoded = jwt.verify(token, process.env.JWT_SECRET);
req.user = decoded;
next();
} catch (error) {
res.status(401).json({ error: 'Invalid token' });
}
};
const limiter = rateLimit({
windowMs: 15 * 60 * 1000,
max: 100,
});
app.use(limiter);
app.use('/api/users', authenticate, createProxyMiddleware({
target: services.users,
changeOrigin: true,
pathRewrite: { '^/api/users': '' },
}));
app.use('/api/products', createProxyMiddleware({
target: services.products,
changeOrigin: true,
pathRewrite: { '^/api/products': '' },
}));
app.use('/api/orders', authenticate, createProxyMiddleware({
target: services.orders,
changeOrigin: true,
pathRewrite: { '^/api/orders': '' },
}));
app.use((err, req, res, next) => {
console.error(err);
res.status(500).json({ error: 'Gateway error' });
});
const PORT = process.env.PORT || 8000;
app.listen(PORT, () => {
console.log(`API Gateway running on port ${PORT}`);
});
See EXAMPLES.md for 15+ additional comprehensive examples including circuit breakers, event-driven patterns, service mesh integration, and more.
Skill Version: 1.0.0
Last Updated: October 2025
Skill Category: Microservices, Backend Development, Node.js, Production Architecture
Compatible With: Express.js 4.x/5.x, Node.js 16+, Docker, Kubernetes