Spring Boot / الأساسي: التركيب وعقود HTTP / الدرس 3
الضبط الخارجي والملفات التعريفية
اربط عقد ضبط صغيراً محدد النوع، واشرح أسبقية المصادر وتفعيل الملفات، وأبعد الأسرار وسياسة النشر عن الافتراضات العرضية.
في هذه الصفحة
أهداف الدرس
- استخدام ConfigurationProperties متحققة للإعدادات المرتبطة.
- شرح القيم الفعلية من طبقات المصادر.
- اختبار الملف والأسرار دون طباعة اعتماد.
عامل الإعدادات كواجهة إدخال للتطبيق
للإعداد نوع ووحدة ووجوب ومدى ومالك؛ فمهلة 2 بلا وحدة ليست عقداً. اجمع الإعدادات المرتبطة بـ@ConfigurationProperties بدلاً من نشر @Value متفرقة. توفر records نموذجاً ثابتاً مختصراً، ويرفض التحقق ضبطاً كان سيفشل تحت الطلبات فقط.
الضبط حد ثقة أيضاً؛ فقد ترتبط قيمة نوعياً وتخالف السعة. يصلح مليون لحقل int لكنه قد يستهلك الذاكرة والزمن. افحص علاقات الحقول التي لا تعبر عنها annotation، ولا تستخدم افتراضياً مريحاً لإخفاء قرار نشر مطلوب لم يُتخذ.
سجل نموذج خصائص واحداً وتحقق منه
يحدد الجزء حد الصفحة و Duration محددة النوع ويسجل النموذج صراحة. يحتاج اعتماديات الضبط والتحقق في 3.5 فيبقى مثال إطار. يهم التسجيل؛ فالنوع الموسوم الذي لم يُمسح أويمكن ليس كائناً قابلاً للحقن تلقائياً. ولا يلزم نسخ نمط setters قديم لربط record في الأساس.
تفحص Min و Max العدد، وتفحص NotNull وجود المهلة فقط؛ فتحتاج إيجابيتها قاعدة أخرى. تحقق من العقد الفعلي ولا تمنح كل annotation ضماناً أوسع. ينبغي أن يحدد الخطأ الإعداد دون كشف الأسرار أو طباعة البيئة كلها.
package training.catalog;
import java.time.Duration;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotNull;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.validation.annotation.Validated;
@ConfigurationProperties("catalog")
@Validated
record CatalogProperties(@Min(1) @Max(200) int maxPageSize,
@NotNull Duration timeout) {}
@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(CatalogProperties.class)
class CatalogConfiguration {}
تعلن الحدود ووجود المهلة وتبقى إيجابيتها قاعدة منفصلة؛ ولم يُنفذ ربط الحاوية.
اشرح أثر كل وثيقة ملف على القيمة
تضم YAML وثيقة أساس وتراكباً يفعل مع training. عند دمج صحيح وتفعيله يُقصد أن تصير الصفحة 20 وتبقى المهلة 2s. هذا تفسير شرطي لا ملاحظة بدء. يفحص محلل YAML البنية ولا يثبت ربط Boot وترتيب المصادر والتحقق كله.
تختار الملفات الضبط لا التفويض؛ فلا يؤمن اسم production المسار. وقد يضيف الملف كائناً أو يحذفه. أظهر قرار التفعيل وراع قيود موضع خصائصه؛ ولا تضع spring.profiles.active في أي وثيقة تبدو مريحة وتفترض صحتها دائماً.
catalog:
max-page-size: 50
timeout: 2s
---
spring:
config:
activate:
on-profile: training
catalog:
max-page-size: 20
يغير التراكب المقصود الحد فقط؛ ولا ينفذ التحليل تفعيل الملف أو فحص البيئة كاملة.
افحص المصدر الفعلي دون كشف السر
يحدد Boot ترتيب مصادر موثقاً؛ فقد تأتي القيمة من الملف المرفق أو الخارجي أو البيئة أو خصائص النظام أو الأمر أو الاختبار، ويغلب اللاحق بحسب الترتيب. ليس ملف المستودع القيمة الفعلية بالضرورة، وتضيف الاختبارات طبقات؛ فلا تعمم أن مصدراً يفوز دائماً.
لأسماء البيئة قواعد: تتحول النقطة لشرطة سفلية وتحذف الشرطات ويكبر الحرف؛ فيكون catalog.max-page-size بالشكل CATALOG_MAXPAGESIZE. وزع الأسرار بآلية معتمدة ولا تدخلها السجل والمصدر. لا تطبع رمزاً أو سلسلة اتصال كاملة لتشخيص الأسبقية فقط.
اختبر السياسة الفعلية لا صياغة الملف فقط
اختبر الافتراض والتجاوز والغياب والمدى والملفات والفشل الآمن. قد يفحص ApplicationContextRunner محدود الربط دون مستمع إذا توفرت الاعتماديات والتهيئة المناسبة؛ وتبقى أمثلته هنا توضيحية ما لم تُشغّل صراحة، ولا تُحمل بيئة خدمة فعلية.
سجل أصل المصدر وفئة قيمة منقحة لا المحتوى الحساس. اربط الضبط بتوافق التطبيق وراجعه عند النشر. يجعل الحد الجيد النشر غير الصالح يفشل مبكراً بوضوح، ويسمح للأثر نفسه بسياسات مختلفة معتمدة ومقصودة، لا بتبدل عرضي خفي.
الأخطاء الشائعة وإصلاحها
ConfigurationPropertiesBindException
- لماذا يحدث؟
- تعذر تحقيق عقد الربط أو التحقق.
- كيف تصلحه؟
- افحص الخاصية ومصدرها دون طباعة الجميع.
- كيف تتجنب تكراره؟
- اختبر الغائب والتالف والحدود.
بدا تجاوز البيئة مهملاً.
- لماذا يحدث؟
- اختلف الاسم أو ترتيب المصدر عن الافتراض.
- كيف تصلحه؟
- اتبع الاسم الموثق وافحص الأصل بأمان.
- كيف تتجنب تكراره؟
- اختبر الربط الفعلي.
أزال ملف خدمة دون توقع.
- لماذا يحدث؟
- تغير التركيب لا القيمة المفردة فقط.
- كيف تصلحه؟
- راجع التفعيل والتسجيل المشروط معاً.
- كيف تتجنب تكراره؟
- اختبر تركيبات الملفات.
اختبر فهمك
1. هل تضمن NotNull للمدة إيجابيتها؟
اعرض الحل المشروح
لا؛ تفحص الوجود. تحتاج الصفر والسالب قاعدة منفصلة، مع الوحدة والحد واختبارهما قبل ضبط عميل أو منفذ.
2. ماذا لا يثبته نجاح تحليل الوثيقتين؟
اعرض الحل المشروح
الأسبقية والتفعيل والتسجيل والتحويل والتحقق واستخدام القيم فعلياً. الصياغة دليل أضيق من اختبار السياق ولا تثبت نشراً ناجحاً.
أهم ما تعلمته
- الضبط إدخال محدد بوحدة ومالك.
- تتبع القيمة طبقات المصادر الموثقة.
- للملف والسر والصياغة والربط فحوص مختلفة.