NestJS — Node.js للمؤسسات

الإعداد والتحقّق من متغيّرات البيئة

16 دقيقة الدرس 17 من 30

الإعداد والتحقّق من متغيّرات البيئة

تتصرّف التطبيقات الحقيقية بشكل مختلف عبر البيئات — المحلية والتجريبية والإنتاجية — وتحمل أسرارًا ككلمات مرور قواعد البيانات ومفاتيح API. ترميزها مباشرةً خطأ. تُحمّل حزمة @nestjs/config الرسمية الإعدادات من متغيّرات البيئة وملفّات .env، وتتيح لك التحقّق منها عند الإقلاع.

إعداد ConfigModule

ثبّت الحزمة واستورد ConfigModule في وحدة الجذر. تجعل isGlobal: true خدمة الإعداد قابلة للحقن في كل مكان دون إعادة استيراد:

// npm install @nestjs/config

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
  ],
})
export class AppModule {}

افتراضيًا يقرأ ملف .env في جذر المشروع:

# .env
DATABASE_URL=postgres://localhost:5432/app
JWT_SECRET=super-secret
PORT=3000

قراءة الإعدادات

احقن ConfigService واستدعِ get():

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class AuthService {
  constructor(private config: ConfigService) {}

  signToken() {
    const secret = this.config.get<string>('JWT_SECRET');
    // ... استخدم secret
  }
}

لا تُضِف ملف .env إلى Git أبدًا. أضِفه إلى .gitignore وأودِع .env.example بالمفاتيح دون قيم حقيقية. الأسرار في إدارة المصادر خطر أمني جسيم.

إعدادات مخصّصة بمساحات أسماء

تجميع الإعدادات المرتبطة في كائنات إعداد مكتوبة الأنواع وذات مساحات أسماء يُبقي الأمور مرتّبة:

import { registerAs } from '@nestjs/config';

export default registerAs('database', () => ({
  url: process.env.DATABASE_URL,
  poolSize: parseInt(process.env.DB_POOL ?? '10', 10),
}));

// حمّلها
ConfigModule.forRoot({ load: [databaseConfig] });

// اقرأ قيمة ذات مساحة اسم
this.config.get('database.url');

التحقّق من الإعدادات عند الإقلاع

أثمن ميزة: الفشل المبكر. إن غاب متغيّر مطلوب أو كان مُشوَّهًا، يجب أن يرفض التطبيق الإقلاع بدل الانهيار لاحقًا. مرّر مخطّط تحقّق (غالبًا Joi):

import * as Joi from 'joi';

ConfigModule.forRoot({
  validationSchema: Joi.object({
    NODE_ENV: Joi.string().valid('development', 'production').required(),
    PORT: Joi.number().default(3000),
    DATABASE_URL: Joi.string().required(),
    JWT_SECRET: Joi.string().min(16).required(),
  }),
});

الفشل المبكر أفضل من المتأخّر. التحقّق من الإعداد عند الإقلاع يعني أنّ غياب JWT_SECRET يوقف النشر فورًا برسالة واضحة — بدل أن يظهر كخطأ تشغيلي محيّر عند أوّل محاولة تسجيل دخول في الإنتاج.

الخلاصة

استخدم @nestjs/config لتحميل متغيّرات البيئة وملفّات .env، واحقن ConfigService لقراءتها، وجمّع الإعدادات بمساحات أسماء registerAs. والأهم، زوّد validationSchema ليفشل التطبيق مبكرًا عند الإقلاع حين يكون الإعداد ناقصًا أو غير صالح. أبقِ الأسرار خارج إدارة المصادر. تاليًا: خطّافات دورة الحياة وسياق التطبيق.