أساسيات Spring Boot

الضبط التلقائي

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

الضبط التلقائي

من أبرز ميزات Spring Boot — وأحيانًا أكثرها سوء فهم — هي الضبط التلقائي (Auto-Configuration): القدرة على فحص ما يوجد على مسار الفئات (classpath)، والـ beans التي عرّفتها بالفعل، والخصائص التي ضبطتها، ثم الربط التلقائي للبنية التحتية التي يحتاجها تطبيقك. يُفصّل هذا الدرس آلية عمل هذه الميزة من الداخل، والسبب وراء تصميمها بهذه الطريقة، وكيفية التحكم بها أو تجاوزها عندما لا تناسبك القيم الافتراضية.

التعليق التوجيهي @SpringBootApplication

كل تطبيق Spring Boot يبدأ بفئة تحمل التعليق التوجيهي @SpringBootApplication. هذا التعليق هو اختصار مُركَّب لثلاثة تعليقات منفصلة:

@SpringBootConfiguration — يُعلّم الفئة بوصفها مصدرًا لتعريفات @Bean (وهي نفسها تخصيص لـ @Configuration).
@EnableAutoConfiguration — يُشغّل آلية الضبط التلقائي الموصوفة في هذا الدرس.
@ComponentScan — يُخبر Spring بمسح حزمة الفئة المُعلَّمة (وحزمها الفرعية) بحثًا عن فئات @Component و@Service و@Repository و@Controller.

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication   // = @SpringBootConfiguration + @EnableAutoConfiguration + @ComponentScan
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

موضع الفئة في الحزمة مهم. لأن @ComponentScan يمسح حزمة الفئة المُعلَّمة وجميع حزمها الفرعية، ينبغي أن تكون الفئة الرئيسية في حزمة جذرية (مثل com.example.demo)، لا في حزمة اسمها فارغ أو في حزمة متداخلة بعمق. يجب أن تكون بقية الفئات في الحزم الفرعية لهذا الجذر.

كيف يعمل الضبط التلقائي من الداخل

عند وجود @EnableAutoConfiguration، يُحمّل Spring Boot قائمة بفئات الضبط التلقائي المُرشَّحة. في Spring Boot 3، تُقرأ هذه القائمة من ملفات META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports على مسار الفئات (في Spring Boot 2 كان الأمر عبر spring.factories — تغيّرت الآلية لكن الفكرة ذاتها). كل فئة من فئات الضبط التلقائي المدمجة — وعددها يتجاوز 150 — هي فئة @Configuration اعتيادية محمية بـ تعليقات شرطية (conditional annotations).

أهم التعليقات الشرطية:

@ConditionalOnClass — يُطبَّق الضبط فقط إذا كانت فئة معينة موجودة على مسار الفئات.
@ConditionalOnMissingBean — يُنشأ الـ bean المُضبَط تلقائيًا فقط إذا لم يحتوِ سياق التطبيق بعدُ على bean من هذا النوع.
@ConditionalOnProperty — يُفعَّل الضبط فقط إذا كانت خاصية معينة مضبوطة (أو تحمل قيمة محددة).
@ConditionalOnWebApplication — يُفعَّل فقط في سياق ويب servlet أو reactive.
@ConditionalOnMissingClass — عكس @ConditionalOnClass.

على سبيل المثال، لا تعمل DataSourceAutoConfiguration في Spring Boot إلا إذا كان HikariCP (أو مجمّع آخر) موجودًا على مسار الفئات ولم تُعرَّف DataSource bean من قِبلك. إليك نسخة مبسّطة تُوضّح النمط:

@AutoConfiguration
@ConditionalOnClass({ DataSource.class, EmbeddedDatabaseType.class })
@ConditionalOnMissingBean(type = "io.r2dbc.spi.ConnectionFactory")
@EnableConfigurationProperties(DataSourceProperties.class)
public class DataSourceAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public DataSource dataSource(DataSourceProperties properties) {
        return properties.initializeDataSourceBuilder().build();
    }
}

نمط "missing bean" هو مفتاح التخصيص. إذا أعلنتَ الـ @Bean الخاص بك من النوع ذاته، فإن حارس @ConditionalOnMissingBean يجعل Spring Boot يتراجع ويستخدم تعريفك بدلًا منه. لا تحارب الإطار — بل أمدّه بتعريفك الخاص وسيتنحّى الضبط التلقائي.

التعليق التوجيهي @AutoConfiguration

في Spring Boot 3، تُعلَّم فئات الضبط التلقائي بـ @AutoConfiguration (بدلًا من @Configuration المجردة). يُشير هذا إلى أن الفئة تشارك في خط أنابيب تحميل الضبط التلقائي وينبغي معالجتها بعد فئات @Configuration الخاصة بالتطبيق — مما يضمن أن الـ beans المُعرَّفة من قِبل المستخدم تتفوق على الإعدادات الافتراضية المُضبَطة تلقائيًا.

فحص ما تم ضبطه تلقائيًا (وما لم يتم)

يمكنك أن تطلب من Spring Boot طباعة تقرير الشروط عند بدء التشغيل. اضبط الخاصية التالية:

# application.properties
logging.level.org.springframework.boot.autoconfigure=DEBUG

يُشغّل هذا تقرير الشروط (conditions report) في الكونسول. تظهر كل فئة ضبط تلقائي مع بيان إما لماذا طُبِّقت (تطابق إيجابي) أو لماذا جرى تخطّيها (تطابق سلبي). هذا أول ما تقرأه عندما لا يتصرف الضبط التلقائي كما تتوقع.

بديلًا عن ذلك، أضف spring-boot-starter-actuator واستعرض نقطة النهاية /actuator/conditions بصيغة JSON للحصول على عرض منظّم للبيانات ذاتها أثناء التشغيل.

استبعاد فئة ضبط تلقائي

في بعض الأحيان تريد منع تشغيل ضبط تلقائي معين — مثلًا تعطيل إعداد DataSource التلقائي في خدمة لا تحتاج قاعدة بيانات:

@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class ReportingApplication {
    public static void main(String[] args) {
        SpringApplication.run(ReportingApplication.class, args);
    }
}

يمكنك أيضًا الاستبعاد باسم الفئة (مفيد عندما لا تكون الفئة على مسار فئاتك وقت الترجمة):

# application.properties
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

كتابة الضبط التلقائي الخاص بك

الضبط التلقائي ليس حكرًا على فريق Spring Boot. يمكن لأي مكتبة أن تُرسِل فئات الضبط التلقائي الخاصة بها وتُسجّلها في META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. هكذا بالضبط تندمج المبتدئات الخارجية (مثل تلك المخصصة لـ Redis أو Kafka أو Flyway) بشفافية في أي مشروع Spring Boot. النمط دائمًا واحد: الشروط تحرس الـ beans، و@ConditionalOnMissingBean يُؤجّل إلى تخصيص المستخدم، وخصائص الضبط تُربط عبر @ConfigurationProperties.

لا تعتمد على ترتيب الضبط التلقائي لـ beans التطبيق. رغم أن Spring Boot يضمن تشغيل فئات الضبط التلقائي الخاصة به بعد فئات @Configuration التابعة للمستخدم، يجب ألا تربط فئات الضبط التلقائي الخاصة بك ببعضها عبر ترتيب ضمني. استخدم @AutoConfigureAfter أو @AutoConfigureBefore بشكل صريح إذا كان الترتيب بين فئات الضبط التلقائي مهمًا.

لماذا يُهم الضبط التلقائي للإنتاجية

قبل Spring Boot، كان ربط تطبيق ويب يعني كتابة عشرات الأسطر من XML أو Java: تسجيل DispatcherServlet، وإعداد DataSource، وضبط Jackson ObjectMapper، والإعلان عن مدير المعاملات، وأكثر. يُقنّن الضبط التلقائي أفضل ممارسات المجتمع كإعدادات افتراضية لكل قطعة من البنية التحتية. تُضيف مبتدئًا (starter) وتظهر ضبط جاهز للإنتاج ومعقول — يمكنك تجاوزه بدقة حيثما تحتاج، دون المساس بكل شيء آخر.

الخلاصة

يُركّب @SpringBootApplication ثلاثة تعليقات توجيهية؛ والأهم في هذا الدرس هو @EnableAutoConfiguration. يُشغّل هذا مسح مسار الفئات بحثًا عن فئات الضبط التلقائي المُرشَّحة، كل منها محمية بتعليقات شرطية — أبرزها @ConditionalOnClass و@ConditionalOnMissingBean. الإعلان عن الـ bean الخاص بك من نوع معين هو كل ما يلزم لتجاوز إعداد افتراضي مُضبَط تلقائيًا. عندما لا يعمل شيء كما تتوقع، فعّل تقرير الشروط بـ logging.level.org.springframework.boot.autoconfigure=DEBUG واقرأ التطابقات الإيجابية والسلبية. في الدرس القادم ستتعرّف على كيفية ضبط الخادم المُضمَّن بالضبط بهذه الآلية ذاتها.