حقن التبعيات ودورة حياة الـ Bean

حقن القيم والمجموعات والخصائص

18 دقيقة الدرس 9 من 13

حقن القيم والمجموعات والخصائص

يُتيح حقن المُنشئ والحقن عبر الضابط (setter) ربط الـ Beans ببعضها. لكن التطبيقات الحقيقية تحتاج أيضًا إلى تهيئة قيم عددية — مهل الانتظار، عناوين URL، أعلام الميزات، أحجام التجمّعات — وبيانات منظّمة كقوائم أصول مسموح بها أو خرائط تُربط المناطق بالعملات. يوفّر Spring آليتين متكاملتين لهذا: الإضافة التوضيحية @Value والربط الآمن نوعيًا عبر @ConfigurationProperties. إنّ معرفة متى وكيف تستخدم كلًّا منهما يُميّز التهيئة النظيفة القابلة للصيانة عن تشابك السلاسل السحرية.

الإضافة التوضيحية @Value

تحلّ @Value تعبيرًا بلغة Spring Expression Language أو نمطًا لملء العناصر النائبة للخصائص، وتحقن النتيجة في حقل أو معامل مُنشئ أو وسيط ضابط. تعتمد الصيغة الأكثر شيوعًا على نحو ${...} للبحث عن مفتاح في Environment، الذي يجمع جميع مصادر الخصائص (خصائص النظام، ومتغيرات بيئة نظام التشغيل، وapplication.properties، وملفات YAML، والمصادر المخصصة) وفق ترتيب أولوية محدد.

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class PaymentGateway {

    private final String  apiUrl;
    private final int     timeoutMs;
    private final boolean sandboxMode;

    // الحقن عبر المُنشئ — مُوصى به: غير قابل للتغيير وسهل الاختبار
    public PaymentGateway(
            @Value("${payment.api.url}")        String apiUrl,
            @Value("${payment.timeout.ms:5000}") int timeoutMs,
            @Value("${payment.sandbox:false}")   boolean sandboxMode) {

        this.apiUrl      = apiUrl;
        this.timeoutMs   = timeoutMs;
        this.sandboxMode = sandboxMode;
    }
}

تُزوّد صيغة النقطتين — ${key:defaultValue} — قيمةً احتياطية تُستخدم عندما يكون المفتاح غائبًا. بدون قيمة افتراضية، يُرمى استثناء BeanCreationException عند بدء التشغيل في حال غياب المفتاح، وهو السلوك المطلوب للإعدادات الإلزامية. استخدم القيم الافتراضية فقط للعناصر الاختيارية حقًا.

ملف application.properties المقابل:

payment.api.url=https://api.stripe.com/v1
payment.timeout.ms=3000
payment.sandbox=true

أولوية خصائص Spring (من الأعلى إلى الأدنى): وسيطات سطر الأوامر > متغيرات بيئة نظام التشغيل > application-{profile}.properties > application.properties > ملفات @PropertySource > القيم الافتراضية. هذا يعني إمكانية تجاوز أي خاصية وقت النشر دون المساس بملف JAR — وهو مبدأ أساسي من مبادئ تطبيق Twelve-Factor.

تعبيرات SpEL داخل @Value

يُفعّل نحو #{...} لغة Spring Expression Language التي تتجاوز البحث البسيط. يمكنك استدعاء توابع، والوصول إلى Beans أخرى، وإجراء عمليات حسابية، واستدعاء أدوات ثابتة:

@Value("#{systemProperties['user.home']}")
private String userHome;

@Value("#{T(java.lang.Runtime).getRuntime().availableProcessors()}")
private int cpuCount;

// الإشارة إلى خاصية Bean أخرى
@Value("#{dataSource.maxPoolSize * 2}")
private int maxBatchSize;

تعبيرات SpEL قوية، لكن أبقها بسيطة داخل @Value. المنطق المعقد ينتمي إلى تابع مصنع @Bean أو فئة خدمة، لا إلى سلسلة تعليق توضيحي يصعب قراءتها ويستحيل تصحيح أخطائها بنقطة توقف.

لا تضع منطق الأعمال في تعبيرات SpEL. إذا نما التعبير ليتجاوز سطرًا واحدًا قابلًا للقراءة فهذا مؤشر على ضرورة استخراجه إلى مكوّن منفصل مناسب. التعليقات التوضيحية ليست المكان المناسب للحسابات.

حقن القوائم والمصفوفات

تُقسَّم قيمة الخاصية المفصولة بفواصل تلقائيًا إلى List أو مصفوفة عندما يكون الحقل المُحقن من النوع المقابل:

# application.properties
cors.allowed.origins=https://app.example.com,https://admin.example.com,http://localhost:3000
notification.channels=EMAIL,SMS,PUSH

import java.util.List;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class CorsConfig {

    @Value("${cors.allowed.origins}")
    private List<String> allowedOrigins;   // تقسّم Spring على الفواصل تلقائيًا

    @Value("${notification.channels}")
    private String[] channels;              // تعمل أيضًا كمصفوفة عادية
}

تتولّى ConversionService في Spring عملية التقسيم وتحويل النوع. تنجح نفس التقنية مع القوائم الرقمية مثل List<Integer> وint[] — يُحوَّل كل رمز مميّز إلى النوع المستهدف.

حقن الخرائط (Maps)

تتطلب الخرائط صيغة SpEL لأن الخاصية البسيطة key=value لا تستطيع وحدها حمل بنية الخريطة:

@Value("#{${locale.currency.map}}")
private Map<String, String> localeCurrencyMap;

# application.properties — يجب أن تكون القيمة تعبير خريطة SpEL صالحًا
locale.currency.map={en_US:'USD', en_GB:'GBP', ar_SA:'SAR', ja_JP:'JPY'}

يُقيّم #{} الخارجي قيمة الخاصية كتعبير SpEL، ويوسّع ${} الداخلي القيمة أولًا. هذا التعشيش مقصود: يُوسَّع ${locale.currency.map} إلى السلسلة الحرفية {en_US:'USD',...}، ثم يُحلّلها SpEL كخريطة.

لأي شيء أكثر تعقيدًا من بضعة مفاتيح، فضّل استخدام @ConfigurationProperties (انظر أدناه). حقن الخريطة عبر SpEL هشّ — خطأ إملائي في ملف الخصائص ينتج خطأ تحليل غامضًا عند بدء التشغيل بدلًا من رسالة تحقق واضحة.

تحميل ملفات الخصائص الخارجية باستخدام @PropertySource

لا يجب أن تعيش الخصائص في application.properties فقط. يمكنك توجيه Spring إلى أي مورد على مسار الفئات أو نظام الملفات:

import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;

@Configuration
@PropertySource("classpath:payment-gateway.properties")
@PropertySource(value = "file:/etc/myapp/secrets.properties", ignoreResourceNotFound = true)
public class PaymentConfig {
    // ستحلّ الـ beans التي تستخدم @Value الآن المفاتيح من هذه الملفات أيضًا
}

يُفيد ignoreResourceNotFound = true للملفات الاختيارية التي توجد فقط في بيئات معينة (أسرار الإنتاج، التجاوزات الخاصة بالمطوّرين). بدونه، يُفشل الملف المفقود تحميل السياق.

الربط الآمن نوعيًا باستخدام @ConfigurationProperties

عندما تنتمي مجموعة من الإعدادات ذات الصلة معًا — تجمّع قاعدة بيانات، خادم بريد إلكتروني، بوابة دفع — فإن @ConfigurationProperties هو الأداة الصحيحة. إنها تربط بادئة نطاق الخصائص بكائن Java عادي (POJO)، مع تحويل نوع كامل وتحقق ودعم الإكمال التلقائي في بيئات التطوير.

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.List;
import java.util.Map;

@Component
@ConfigurationProperties(prefix = "mail")
public class MailProperties {

    private String     host;
    private int        port     = 587;
    private String     username;
    private String     password;
    private boolean    startTls = true;
    private List<String>        recipients = List.of();
    private Map<String, String> templates  = Map.of();

    // getters وsetters قياسية (تستخدمها Spring للربط)
    public String getHost()                    { return host; }
    public void   setHost(String host)         { this.host = host; }
    public int    getPort()                    { return port; }
    public void   setPort(int port)            { this.port = port; }
    public String getUsername()                { return username; }
    public void   setUsername(String u)        { this.username = u; }
    public String getPassword()                { return password; }
    public void   setPassword(String p)        { this.password = p; }
    public boolean isStartTls()                { return startTls; }
    public void   setStartTls(boolean s)       { this.startTls = s; }
    public List<String> getRecipients()        { return recipients; }
    public void setRecipients(List<String> r) { this.recipients = r; }
    public Map<String, String> getTemplates()  { return templates; }
    public void setTemplates(Map<String, String> t) { this.templates = t; }
}

# application.properties
mail.host=smtp.resend.com
mail.port=465
mail.username=resend
mail.password=${MAIL_PASSWORD}
mail.start-tls=false
mail.recipients=ops@example.com,alerts@example.com
mail.templates.welcome=templates/welcome.html
mail.templates.reset=templates/password-reset.html

لاحظ أن mail.start-tls في ملف الخصائص يُعيَّن إلى setStartTls في الفئة. يُطبّع Relaxed Binding في Spring الكتابة بالشرطة (kebab-case) وcamelCase والشرطات السفلية والأحرف الكبيرة — فهي كلها متكافئة لأغراض الربط. لهذا يمكن لمتغير بيئة نظام التشغيل MAIL_PASSWORD إشباع خاصية باسم mail.password.

أضف التحقق: علّم الفئة بـ @Validated واستخدم قيود Bean Validation مثل @NotBlank و@Min و@Max و@Pattern وما شابهها على الحقول. سترفض Spring البدء إذا انتهكت القيم المرتبطة هذه القيود — وهو أفضل بكثير من اكتشاف خطأ في التهيئة أثناء التشغيل.

import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import org.springframework.validation.annotation.Validated;

@Component
@ConfigurationProperties(prefix = "mail")
@Validated
public class MailProperties {

    @NotBlank
    private String host;

    @Min(1)
    private int port = 587;

    // ... بقية الفئة
}

@Value مقابل @ConfigurationProperties — قاعدة القرار

استخدم @Value للقيم المعزولة الفردية — مهلة انتظار واحدة، أو علم ميزة، أو مفتاح API يُستخدم في Bean واحد فقط. إنها سريعة ولا تتطلب فئة إضافية.
استخدم @ConfigurationProperties لأي مجموعة متجانسة من ثلاثة إعدادات مترابطة أو أكثر. إنها توثّق نفسها، وتتحقق عند بدء التشغيل، وتُولّد البيانات الوصفية لبيئة التطوير لتوفير الإكمال التلقائي في application.properties.
لا تتشتّت نفس البادئة عبر عشرات من تعليقات @Value في Beans مختلفة. مركزها في فئة @ConfigurationProperties واحدة وحقن تلك الفئة أينما احتجت إليها.

الخلاصة

تُعدّ @Value بصيغة ${key:default} نقطة الدخول لحقن القيم العددية والمجموعات البسيطة؛ بينما يُفتح صيغة #{spel} آفاق الخرائط والقيم المحسوبة. تُتيح @PropertySource تحميل ملفات خصائص إضافية. لمجموعات الإعدادات المترابطة، تقدّم @ConfigurationProperties أمانًا نوعيًا وتحقّقًا وربطًا مرنًا — وينبغي أن تكون خيارك الافتراضي لكل ما يُشكّل نطاقًا للتهيئة. تُبقي هذه الآليات معًا التهيئة خارج كودك وتحت سيطرة بيئة النشر.