إعداد Spring والملفّات الشخصية

مشروع: ضبط الإعدادات لبيئات متعددة

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

مشروع: ضبط الإعدادات لبيئات متعددة

على مدار هذا البرنامج التعليمي درستَ كل عنصر من عناصر إعداد Spring بمعزل عن غيره: الملفات الشخصية (profiles) ومصادر الخصائص و@Value و@Conditional وتجريد Environment. يجمع هذا الدرس الختامي كل هذه العناصر في مشروع Spring Boot 3 واقعي. الهدف هو قاعدة شيفرة تعمل بشكل متطابق على حاسوب المطوّر ومشغّل اختبارات CI وخادم الإنتاج — دون تعديل يدوي لأي ملف، ودون كتل معطّلة بعلامات التعليق، ودون مسارات شيفرة خاصة ببيئات مدفونة في منطق الأعمال.

البنية المستهدفة

يكشف التطبيق عن واجهة برمجية REST مدعومة بقاعدة بيانات علائقية. ويستخدم إرسال البريد الإلكتروني بشكل غير متزامن ويتكامل مع بوابة دفع خارجية. يجب أن تستوفي استراتيجية الإعداد أربعة متطلبات:

بيئة التطوير (Dev) — بدء تشغيل سريع، قاعدة بيانات H2 في الذاكرة، طباعة البريد الإلكتروني على وحدة التحكم، بوابة الدفع معطّلة.
بيئة الاختبار (Test) — حتمية ولا مكالمات شبكية، H2 أو Testcontainers، جميع العملاء الخارجيين مستبدَلون بنسخ مزيّفة.
بيئة الاستعراض (Staging) — تعكس بنية الإنتاج ولكن تستخدم بيانات اعتماد غير حساسة وبوابة دفع اختبارية.
بيئة الإنتاج (Prod) — PostgreSQL، SMTP حقيقي، بوابة دفع حقيقية، حدود اتصال صارمة، لا سجلات تصحيح.

تخطيط ملفات الخصائص

يحلّ Spring Boot هرمية محددة من مصادر الخصائص. بالنسبة لملف شخصي يسمى prod، يحمّل (بترتيب الأولوية، الأعلى أولًا):

متغيرات بيئة نظام التشغيل وخصائص JVM النظامية (-Dkey=value)
application-prod.properties (أو .yml)
application.properties (الإعدادات الافتراضية الأساسية)

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

# src/main/resources/application.properties  (الإعدادات المشتركة)
spring.application.name=payments-api
spring.jpa.open-in-view=false
spring.jpa.hibernate.ddl-auto=validate

# الملف الشخصي الافتراضي: dev
spring.profiles.default=dev

# مستوى التسجيل الأساسي
logging.level.root=INFO
logging.level.com.example=DEBUG

# application-dev.properties
spring.datasource.url=jdbc:h2:mem:devdb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.jpa.hibernate.ddl-auto=create-drop
spring.h2.console.enabled=true

mail.simulate=true
payment.gateway.sandbox=true
payment.gateway.base-url=https://sandbox.pay.example.com

# application-prod.properties
# القيم الحساسة تُقرأ من متغيرات البيئة — لا تُضمَّن هنا أبدًا
spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASS}

spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=30000

spring.mail.host=${SMTP_HOST}
spring.mail.port=587
spring.mail.username=${SMTP_USER}
spring.mail.password=${SMTP_PASS}
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
mail.simulate=false

payment.gateway.sandbox=false
payment.gateway.base-url=${PAYMENT_GATEWAY_URL}

logging.level.root=WARN
logging.level.com.example=INFO

لا تودع الأسرار في نظام التحكم بالإصدارات. يخبر نمط ${ENV_VAR} في application-prod.properties Spring بحل القيمة من البيئة الفعلية عند بدء التشغيل. يمكن إيداع الملف نفسه بأمان في نظام التحكم بالإصدارات لأنه لا يحتوي على أي بيانات اعتماد فعلية.

اختيار الحبوب بحسب الملف الشخصي

الحبوب التي تتطلب بنية تحتية حقيقية تنتمي وراء الملفات الشخصية. أنشئ فئة إعداد مخصصة لكل تكامل خارجي:

package com.example.config;

import com.example.mail.ConsoleMailSender;
import com.example.mail.SmtpMailSender;
import com.example.mail.AppMailSender;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

@Configuration
public class MailConfig {

    /** مرسل SMTP الحقيقي — نشط في staging و prod فقط */
    @Bean
    @Profile({"staging", "prod"})
    public AppMailSender smtpMailSender(
            org.springframework.mail.javamail.JavaMailSender javaMailSender) {
        return new SmtpMailSender(javaMailSender);
    }

    /** نسخة المحاكاة على وحدة التحكم — نشطة في dev و test؛ لا شبكة مطلوبة */
    @Bean
    @Profile({"dev", "test"})
    public AppMailSender consoleMailSender() {
        return new ConsoleMailSender();
    }
}

تعتمد خدمات الأعمال على الواجهة AppMailSender — لا على التنفيذ الملموس. يحقن Spring الحبة الصحيحة تلقائيًا بناءً على الملف الشخصي النشط. لا if/else في شيفرة الأعمال، ولا علامات منطقية تُفحص في وقت التشغيل.

ربط خصائص الإعداد بفئة مكتوبة بأنواع

تشتيت حقن @Value عبر فئات كثيرة يجعل سطح الإعداد صعب الرؤية وصعب التحقق. اجمع الخصائص ذات الصلة في سجل @ConfigurationProperties واحد:

package com.example.config;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "payment.gateway")
public record PaymentGatewayProperties(
        String baseUrl,
        boolean sandbox,
        int connectTimeoutMs,
        int readTimeoutMs
) {}

// تفعيل الربط — عادةً في فئة @SpringBootApplication الرئيسية
@SpringBootApplication
@EnableConfigurationProperties(PaymentGatewayProperties.class)
public class PaymentsApiApplication {
    public static void main(String[] args) {
        SpringApplication.run(PaymentsApiApplication.class, args);
    }
}

يتحقق Spring Boot من الخصائص عند بدء التشغيل. إذا كانت payment.gateway.base-url مفقودة في ملف شخصي، يفشل التطبيق فورًا برسالة خطأ واضحة بدلًا من رمي NullPointerException في عمق معالج الطلب.

أضف spring-boot-configuration-processor إلى بنائك. يولّد بيانات وصفية لبيئة التطوير المتكاملة حتى يحصل application.properties على إكمال تلقائي وتوثيق لكل فئة @ConfigurationProperties. إنه معالج تعليقات وقت الترجمة فحسب — لا تكلفة في وقت التشغيل.

حبوب البنية التحتية الشرطية

بعض الحبوب لا ينبغي إنشاؤها أصلًا إذا كانت علامة الميزة معطّلة. استخدم @ConditionalOnProperty لهذا الغرض:

package com.example.config;

import com.example.payment.LivePaymentClient;
import com.example.payment.SandboxPaymentClient;
import com.example.payment.PaymentClient;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class PaymentConfig {

    @Bean
    @ConditionalOnProperty(name = "payment.gateway.sandbox", havingValue = "false")
    public PaymentClient livePaymentClient(PaymentGatewayProperties props) {
        return new LivePaymentClient(props.baseUrl(), props.connectTimeoutMs(), props.readTimeoutMs());
    }

    @Bean
    @ConditionalOnProperty(name = "payment.gateway.sandbox", havingValue = "true", matchIfMissing = true)
    public PaymentClient sandboxPaymentClient(PaymentGatewayProperties props) {
        return new SandboxPaymentClient(props.baseUrl());
    }
}

يضمن matchIfMissing = true على حبة الاختبار أنه إذا كانت الخاصية غائبة — مثلًا في اختبار وحدة لا يحمّل أي ملف خاص بملف شخصي — تُستخدم النسخة الآمنة لا العميل الحقيقي.

تفعيل الملفات الشخصية

ثمة ثلاث طرق معيارية لتفعيل ملف شخصي:

وسيطة JVM (CI / Docker): -Dspring.profiles.active=prod
متغير بيئة (12-factor / Kubernetes): SPRING_PROFILES_ACTIVE=prod
تعليق اختبار: @ActiveProfiles("test") على فئة اختبار JUnit

في النشر المعتمد على الحاويات، يُعدّ تعيين SPRING_PROFILES_ACTIVE كمتغير بيئة في مواصفات الحاوية أو أمر تشغيل Docker الأسلوبَ المفضّل: إذ يبقي ملف JAR متطابقًا عبر البيئات وتحدد البيئة دورها بنفسها.

إعداد الاختبار

تحتاج اختبارات التكامل إلى شريحة إعداد خاصة بها. يوفر Spring Boot الجمعَ بين @SpringBootTest وملف application-test.properties مخصص:

# src/test/resources/application-test.properties
spring.datasource.url=jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1
spring.datasource.driver-class-name=org.h2.Driver
spring.jpa.hibernate.ddl-auto=create-drop
mail.simulate=true
payment.gateway.sandbox=true
payment.gateway.base-url=http://localhost:9999/stub
payment.gateway.connect-timeout-ms=500
payment.gateway.read-timeout-ms=500

package com.example;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;

@SpringBootTest
@ActiveProfiles("test")
class PaymentFlowIntegrationTest {

    @Test
    void completePurchase_chargesCorrectAmount() {
        // جميع الحبوب حقيقية باستثناء PaymentClient (اختباري) و AppMailSender (وحدة التحكم)
        // سريع وحتمي ولا مكالمات شبكية خارجية
    }
}

لا تدع إعدادات الاختبار تتسرب إلى الإنتاج. ضع ملف application-test.properties الخاص بالاختبار ضمن src/test/resources، لا src/main/resources. سيعثر عليه Spring Boot تلقائيًا حين يكون الملف الشخصي للاختبار نشطًا، ولن يُدرَج أبدًا في ملف JAR الإنتاجي.

الخلاصة: القواعد التي تُبقيه صامدًا

يلتزم إعداد Spring Boot متعدد البيئات الذي يصمد عمليًا بمجموعة صغيرة من القواعد:

ملف أساسي واحد للإعدادات الافتراضية المشتركة فعلًا؛ وملف شخصي واحد لكل بيئة للتجاوزات.
الأسرار في متغيرات البيئة فقط — لا في الملفات الموجودة في نظام التحكم بالإصدارات.
حبوب مدفوعة بالملف الشخصي عوضًا عن فحوصات if/else في وقت التشغيل داخل منطق الأعمال.
@ConfigurationProperties مكتوب بأنواع لجميع الخصائص المخصصة — تُتحقق عند بدء التشغيل وتكتمل تلقائيًا في بيئة التطوير.
الملف الشخصي للاختبار في src/test/resources — سريع وحتمي ومعزول تمامًا عن البنية التحتية الحقيقية.

حين تُتّبع هذه القواعد، يمكنك تسليم نفس ملف JAR لأي بيئة والوثوق بأنه سيضبط نفسه بشكل صحيح من السياق المحيط به — وهو بالضبط ما تطلبه منهجية التطبيقات ذات الاثني عشر عاملًا وما تتوقعه خطوط أنابيب النشر الحديثة.