Best practices for configuration management

The Importance of Configuration Management

Configuration management is an indispensable part of modern software development, especially in Node.js frameworks like Koa2. Proper configuration management enhances code maintainability, reduces issues caused by environmental differences, and ensures consistent application behavior across different deployment environments. Koa2's lightweight nature makes configuration management more flexible but also necessitates standardized practices.

Environment Variable Management

Environment variables are the core tool for configuration management. The dotenv package simplifies managing configurations for different environments:

// .env
PORT=3000
DB_HOST=localhost
DB_PORT=27017
JWT_SECRET=your_secret_key

// config.js
require('dotenv').config();

module.exports = {
  port: process.env.PORT || 3000,
  db: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT
  },
  jwt: {
    secret: process.env.JWT_SECRET
  }
};

Usage in a Koa2 application:

const Koa = require('koa');
const config = require('./config');

const app = new Koa();

app.listen(config.port, () => {
  console.log(`Server running on port ${config.port}`);
});

Multi-Environment Configuration Strategy

For different environments like development, testing, and production, the following directory structure is recommended:

config/
├── default.js
├── development.js
├── test.js
└── production.js

Each environment file can be organized as follows:

// config/default.js
module.exports = {
  logLevel: 'info',
  db: {
    poolSize: 10
  }
};

// config/production.js
const config = require('./default');

module.exports = Object.assign({}, config, {
  logLevel: 'error',
  db: {
    poolSize: 50
  }
});

Loading configurations in Koa2:

const env = process.env.NODE_ENV || 'development';
const config = require(`./config/${env}`);

Configuration Validation

Use validation libraries like Joi to ensure configuration integrity:

const Joi = require('joi');

const schema = Joi.object({
  port: Joi.number().required(),
  db: Joi.object({
    host: Joi.string().required(),
    port: Joi.number().required()
  }).required()
});

const { error, value } = schema.validate(config);
if (error) {
  throw new Error(`Config validation error: ${error.message}`);
}

Handling Sensitive Information

Sensitive configurations like API keys and database passwords require special handling:

1. Never commit to version control
2. Use encrypted storage
3. Access via key management systems

// Example using AWS Secrets Manager
const { SecretsManager } = require('aws-sdk');

async function getSecret(secretName) {
  const client = new SecretsManager();
  const data = await client.getSecretValue({ SecretId: secretName }).promise();
  return JSON.parse(data.SecretString);
}

Hot Reload for Configuration

Implement hot reload mechanisms for configurations that need runtime updates:

const fs = require('fs');
const path = require('path');

let config = require('./config');

fs.watch(path.join(__dirname, 'config.js'), (eventType, filename) => {
  if (eventType === 'change') {
    try {
      delete require.cache[require.resolve('./config')];
      config = require('./config');
      console.log('Configuration reloaded');
    } catch (err) {
      console.error('Error reloading config:', err);
    }
  }
});

Configuration Center Integration

For large projects, consider using configuration centers like Consul, Etcd, or Nacos:

const Consul = require('consul');

const consul = new Consul({
  host: 'consul-server'
});

async function getConfig(key) {
  const result = await consul.kv.get(key);
  return JSON.parse(result.Value);
}

// Usage in Koa2 middleware
app.use(async (ctx, next) => {
  ctx.config = await getConfig('app/config');
  await next();
});

Configuration Version Control

Configuration changes should be version-controlled like code changes:

1. Create a dedicated Git repository for configurations
2. Use semantic versioning
3. Implement rollback mechanisms

# Example configuration rollback
git checkout tags/v1.0.0 -- config/
pm2 restart app

Configuration Documentation

Maintain detailed documentation for all configuration items:

## Database Configuration

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| host | string | localhost | Database server address |
| port | number | 27017 | Database port |
| poolSize | number | 10 | Connection pool size |

```javascript
// Example configuration
{
  db: {
    host: 'db.prod.example.com',
    port: 27017,
    poolSize: 50
  }
}
```

Configuration Testing

Write test cases to ensure configuration validity:

const assert = require('assert');
const config = require('../config');

describe('Configuration', () => {
  it('should have valid database config', () => {
    assert.ok(config.db.host);
    assert.ok(config.db.port);
    assert.ok(config.db.poolSize > 0);
  });

  it('should have valid JWT secret', () => {
    assert.ok(config.jwt.secret);
    assert.ok(config.jwt.secret.length >= 32);
  });
});

Configuration Performance Optimization

For frequently accessed configurations, consider caching strategies:

const LRU = require('lru-cache');

const configCache = new LRU({
  max: 100,
  maxAge: 1000 * 60 * 5 // 5-minute cache
});

async function getConfigWithCache(key) {
  let value = configCache.get(key);
  if (!value) {
    value = await fetchConfigFromRemote(key);
    configCache.set(key, value);
  }
  return value;
}

Configuration Change Notifications

Implement publish/subscribe mechanisms for configuration changes:

const EventEmitter = require('events');
class ConfigEmitter extends EventEmitter {}
const configEmitter = new ConfigEmitter();

// Listen for configuration changes
configEmitter.on('configChanged', (key, newValue) => {
  console.log(`Config ${key} changed to`, newValue);
  // Perform related cleanup or reinitialization
});

// Trigger change events
function updateConfig(key, value) {
  config[key] = value;
  configEmitter.emit('configChanged', key, value);
}

Middleware Integration with Configuration

Elegantly manage middleware configurations in Koa2:

// config/middleware.js
module.exports = {
  bodyParser: {
    enable: true,
    options: {
      jsonLimit: '1mb'
    }
  },
  cors: {
    enable: true,
    options: {
      origin: '*'
    }
  }
};

// app.js
const middlewareConfig = require('./config/middleware');

if (middlewareConfig.bodyParser.enable) {
  const bodyParser = require('koa-bodyparser');
  app.use(bodyParser(middlewareConfig.bodyParser.options));
}

if (middlewareConfig.cors.enable) {
  const cors = require('@koa/cors');
  app.use(cors(middlewareConfig.cors.options));
}

Internationalization Support for Configuration

For multilingual applications, consider internationalization in configuration:

// config/locales/en-US.js
module.exports = {
  welcome: 'Welcome to our app',
  errors: {
    notFound: 'Resource not found'
  }
};

// config/locales/zh-CN.js
module.exports = {
  welcome: '欢迎使用我们的应用',
  errors: {
    notFound: '资源未找到'
  }
};

// Usage in middleware
app.use(async (ctx, next) => {
  const locale = ctx.acceptsLanguages(['en-US', 'zh-CN']) || 'en-US';
  ctx.i18n = require(`./config/locales/${locale}`);
  await next();
});

Configuration Dependency Management

Handle dependencies between configuration items:

// config/dependencies.js
module.exports = {
  // Dependency declarations between configuration items
  dependencies: {
    'redis.cacheEnabled': {
      requires: ['redis.host', 'redis.port']
    }
  },
  // Conflict declarations between configuration items
  conflicts: {
    'db.useMongo': {
      conflictsWith: ['db.useMySQL']
    }
  }
};

// Validate dependencies during configuration validation
function validateConfigDependencies(config) {
  const { dependencies, conflicts } = require('./config/dependencies');
  
  // Check dependencies
  Object.entries(dependencies).forEach(([key, { requires }]) => {
    if (config[key] && requires.some(req => !config[req])) {
      throw new Error(`Configuration item ${key} requires ${requires.join(', ')}`);
    }
  });
  
  // Check conflicts
  Object.entries(conflicts).forEach(([key, { conflictsWith }]) => {
    if (config[key] && conflictsWith.some(conflict => config[conflict])) {
      throw new Error(`Configuration item ${key} conflicts with ${conflictsWith.join(', ')}`);
    }
  });
}