Manejo de variables de entorno

Las aplicaciones utiliza variables de entorno para definir su configuración en los distintos entornos (desarrollo, pruebas, producción). Estas variables permiten ajustar comportamientos sin necesidad de modificar el código fuente.

Por seguridad, el archivo .env no debe versionarse. En su lugar, se incluye un archivo .env.example que lista las variables requeridas, con los valores sensibles en blanco, para facilitar la configuración inicial del entorno local.

📌 Reglas generales de nomenclatura

Formato

• Siempre en mayúsculas.
• Separación de palabras con guion bajo (_).
• Alfabeto ASCII básico (sin tildes, ñ, etc).

Prefijos

• Usar prefijos relacionados al proveedor, contexto o servicio si aplica.

Dominio de aplicación

Las variables deben ser descriptivas, reflejando su propósito:

• ZOHO_URL (URL base de ZOHO)
• WOMPI_URL (URL base de Wompi)
• BD_NAME (nombre de la base de datos)
• JWT_EXPIRES (tiempo de expiración del token JWT)

Evitar palabras genéricas

• Ejemplos a evitar: USER, PASSWORD, TOKEN.
• Mejor: DB_USER, JWT_SECRET, API_TOKEN.

🔒 Seguridad en el manejo de variables de entorno

• Las variables sensibles (tokens, claves secretas) deben ser almacenadas de forma segura (Vault, Secret Manager, etc).
• Evitar exponerlas en logs o errores.

📝 Asegúrate de tener este contenido en un archivo .env.example dentro del proyecto. Cada desarrollador deberá duplicar este archivo como .env y completar los valores según su entorno local o de producción

📌 Buenas prácticas adicionales con el uso de variables de entorno

• Documentar siempre el uso de cada variable.
• Validar las variables en el arranque de la aplicación.
• Centralizar su carga (por ejemplo: config/env.config.js).

Nunca versionar archivos .env con datos reales en el repositorio.

Ofrecer plantillas de ejemplo: .env.example.

Convenciones de nombres para variables de entorno

✅ Ejemplos correctos

Variable	Descripción
ZOHO_URL	URL base de la API de Zoho
BD_NAME	Nombre de la base de datos
JWT_EXPIRES	Tiempo de expiración del token JWT
AWS_ACCESS_KEY	Access Key de AWS
REDIS_HOST	Hostname del servidor Redis
SMTP_SERVER	Servidor SMTP para envío de correos

❌ Ejemplos incorrectos (evitar)

Variable	Problema
url	Muy genérico, no indica contexto
db	Ambiguo, no indica si es nombre, host, usuario, etc.
token	No especifica a qué sistema pertenece
KEY	Sin prefijo, sin contexto
123abc	No es un nombre válido
myVar	Convención de camelCase no permitida
PASSWORD	Genérico y poco seguro, falta prefijo