O que Validador de Configuração faz?
Valida arquivos de configuração e variáveis de ambiente para prevenir erros de runtime e configurações ausentes.
Quando Usar
- Trabalhando com variáveis de ambiente ou arquivos de configuração
- Problemas de deploy ou configuração
- Usuário menciona ".env", "config", "variáveis de ambiente" ou "configurações"
Instruções
1. Encontrar Arquivos de Configuração
Procurar por:
.env,.env.example,.env.localconfig/,config.js,config.jsonsettings.py,application.ymlappsettings.json,.env.production
2. Detectar Variáveis Ausentes
Comparar .env.example vs .env:
# Variáveis no exemplo mas não no .env
comm -23 <(grep -o '^[A-Z_]*' .env.example | sort) <(grep -o '^[A-Z_]*' .env | sort)
Variáveis comuns necessárias:
DATABASE_URL
API_KEY
SECRET_KEY
NODE_ENV
PORT
3. Validar Formato das Variáveis
Verificar problemas comuns:
// Faltando aspas para valores com espaços
DATABASE_URL=postgres://localhost/db name // Ruim
DATABASE_URL="postgres://localhost/db name" // Bom
// Protocolo ausente
API_URL=example.com // Ruim
API_URL=https://example.com // Bom
// Booleano como string
DEBUG=true // Pode ser interpretado como string
DEBUG=1 // Mais explícito
4. Validar Variáveis Obrigatórias em Tempo de Execução
Exemplo Node.js:
const requiredEnvVars = [
'DATABASE_URL',
'API_KEY',
'JWT_SECRET'
];
const missing = requiredEnvVars.filter(v => !process.env[v]);
if (missing.length > 0) {
throw new Error(`Variáveis de ambiente obrigatórias ausentes: ${missing.join(', ')}`);
}
Exemplo Python:
import os
REQUIRED_ENV_VARS = [
'DATABASE_URL',
'SECRET_KEY',
'ALLOWED_HOSTS'
]
missing = [var for var in REQUIRED_ENV_VARS if not os.getenv(var)]
if missing:
raise EnvironmentError(f"Variáveis de ambiente ausentes: {', '.join(missing)}")
5. Validação de Tipos
Validar tipos:
const config = {
port: parseInt(process.env.PORT || '3000', 10),
debug: process.env.DEBUG === 'true',
apiUrl: new URL(process.env.API_URL), // Lança erro se inválido
maxConnections: Number(process.env.MAX_CONNECTIONS),
};
// Validar
if (isNaN(config.port) || config.port < 1 || config.port > 65535) {
throw new Error('PORT deve ser um número de porta válido');
}
6. Gerar .env.example
Criar template a partir do .env real:
# Remover valores, manter chaves
sed 's/=.*/=/' .env > .env.example
Ou com placeholders:
DATABASE_URL=postgres://usuario:senha@localhost:5432/nomedb
API_KEY=sua_api_key_aqui
SECRET_KEY=gerar_segredo_aleatorio
PORT=3000
NODE_ENV=desenvolvimento
7. Schema de Configuração
Definir schema (exemplo usando Joi):
const Joi = require('joi');
const envSchema = Joi.object({
NODE_ENV: Joi.string()
.valid('development', 'production', 'test')
.required(),
PORT: Joi.number()
.port()
.default(3000),
DATABASE_URL: Joi.string()
.uri()
.required(),
API_KEY: Joi.string()
.min(32)
.required(),
DEBUG: Joi.boolean()
.default(false),
}).unknown();
const { error, value } = envSchema.validate(process.env);
if (error) {
throw new Error(`Erro de validação de configuração: ${error.message}`);
}
module.exports = value;
8. Verificações de Segurança
Não commitar segredos:
# Verificar se .env está no .gitignore
if ! grep -q "^\.env$" .gitignore; then
echo "Aviso: .env não está no .gitignore"
fi
# Verificar segredos hardcoded no código
grep -r "api_key.*=.*['\"]" --exclude-dir=node_modules
Problemas de segurança comuns:
- Senhas/chaves hardcoded
- Segredos padrão em produção
- Configurações sensíveis expostas
- Segredos não criptografados
9. Configurações Específicas por Ambiente
Organizar por ambiente:
.env.development
.env.staging
.env.production
.env.test
Carregar adequadamente:
require('dotenv').config({
path: `.env.${process.env.NODE_ENV || 'development'}`
});
10. Documentar Todas as Variáveis
Criar CONFIG.md:
# Configuração
## Variáveis de Ambiente
### Obrigatórias
- `DATABASE_URL`: String de conexão PostgreSQL
- Formato: `postgres://usuario:senha@host:porta/db`
- Exemplo: `postgres://app:secret@localhost:5432/myapp`
- `API_KEY`: Chave de API de terceiros
- Obter em: https://dashboard.example.com
- Escopos necessários: read, write
### Opcionais
- `PORT`: Porta do servidor (padrão: 3000)
- `DEBUG`: Habilitar logging de depuração (padrão: false)
- `MAX_CONNECTIONS`: Tamanho do pool de conexões do banco (padrão: 10)
## Configuração
1. Copiar `.env.example` para `.env`
2. Preencher todos os valores obrigatórios
3. Executar `npm run validate-config` para verificar
11. Script de Validação
Criar scripts/validate-config.js:
const fs = require('fs');
function validateConfig() {
const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter(v => !process.env[v]);
if (missing.length > 0) {
console.error(`❌ Ausente: ${missing.join(', ')}`);
process.exit(1);
}
console.log('✓ Todas as variáveis de configuração obrigatórias presentes');
}
validateConfig();
12. Melhores Práticas
- Nunca commitar .env: Sempre incluir no .gitignore
- Manter .env.example atualizado: Mantê-lo sincronizado
- Validar na inicialização: Falhar rapidamente se mal configurado
- Usar valores padrão robustos: Fallbacks sensíveis
- Documentar tudo: Explicar cada variável
- Rotacionar segredos: Atualizar chaves regularmente
- Usar gerenciadores de segredos: Vault, AWS Secrets Manager para produção
- Verificar tipos: Validar tipos, não apenas presença
Arquivos de Suporte
templates/config-validator.jstemplates/.env.examplescripts/generate-env-example.sh