الفصل 5: القاموس الكامل للتعليقات التوضيحية (A-Z)
مرجع سريع لكل التعليقات التوضيحية في Spring Boot، مرتبة أبجدياً. للحصول على أمثلة كود مفصلة، راجع الفصول من 1 إلى 4.
أ
| التعليق التوضيحي | الوصف |
|---|---|
| @ActiveProfiles | يُفعّل ملفات تعريف Spring محددة لاختبارات الوحدات. يسمح بتحميل application-test.yml على سبيل المثال. |
| @After | (JUnit 4) ينفذ الكود بعد كل طريقة اختبار. |
| @AfterClass | (JUnit 4) ينفذ الكود بعد كل طرق الاختبار في فئة. |
| @AfterEach | (JUnit 5) ينفذ الكود بعد كل طريقة اختبار. يحل محل @After. |
| @Async | ينفذ طريقة بشكل غير متزامن في خيط منفصل. يتطلب @EnableAsync. |
| @AutoConfigureDataJpa | يضبط JPA تلقائياً لاختبار وحدة. |
| @AutoConfigureJsonTesters | يضبط أدوات التسلسل/إلغاء التسلسل JSON تلقائياً للاختبارات. |
| @AutoConfigureMockMvc | يضبط كائن MockMvc تلقائياً لاختبار وحدة. |
| @AutoConfigureWebTestClient | يضبط WebTestClient تلقائياً لاختبارات WebFlux. |
| @Autowired | يحقن تبعية (bean Spring) تلقائياً في فئة. يفضل الحقن عبر المنشئ. |
ب
| التعليق التوضيحي | الوصف |
|---|---|
| @Bean | يعلن عن طريقة تعيد كائنًا مُدارًا بواسطة حاوية Spring. تُستخدم في الفئات @Configuration. |
| @Before | (JUnit 4) ينفذ الكود قبل كل طريقة اختبار. |
| @BeforeClass | (JUnit 4) ينفذ الكود قبل كل طرق الاختبار في فئة. |
| @BeforeEach | (JUnit 5) ينفذ الكود قبل كل طريقة اختبار. يحل محل @Before. |
ج
| التعليق التوضيحي | الوصف |
|---|---|
| @Cacheable | يخزن نتيجة طريقة في الذاكرة المؤقتة. تعيد المكالمات اللاحقة نتيجة الذاكرة المؤقتة. |
| @CacheConfig | يضبط إعدادات الذاكرة المؤقتة (الاسم، مدة الحياة، الحجم الأقصى) لفئة كاملة. |
| @CacheEvict | يزيل إدخالًا أو كل الإدخالات من الذاكرة المؤقتة عند استدعاء الطريقة. |
| @CachePut | يُحدث الذاكرة المؤقتة بنتيجة الطريقة، دون استخدام الذاكرة المؤقتة الحالية. |
| @CircuitBreaker | (Spring Cloud) يحمي طريقة من الفشل المتكرر عن طريق تحديد المكالمات عندما تكون الخدمة معطلة. |
| @Column | يضبط الربط بين خاصية JPA وعمود قاعدة البيانات (الاسم، nullable، فريد، الطول). |
| @Component | يميز فئة كـ bean Spring عام، يتم اكتشافه تلقائياً بواسطة فحص المكونات. |
| @ComponentScan | يفحص الحزم لاكتشاف الفئات المميزة بـ @Component, @Service, @Repository, إلخ. |
| @Conditional | يشترط إنشاء bean بناءً على شرط مخصص. |
| @ConditionalOnClass | ينشئ bean فقط إذا كانت فئة معينة موجودة في classpath. |
| @ConditionalOnMissingBean | ينشئ bean فقط إذا لم يكن هناك bean آخر من نفس النوع موجود بالفعل. |
| @ConditionalOnProperty | ينشئ bean فقط إذا كانت خاصية معينة لها قيمة معينة في التكوين. |
| @Configuration | يميز فئة تكوين Spring تحتوي على طرق @Bean. |
| @ConfigurationProperties | يربط مجموعة من الخصائص من ملف التكوين إلى كائن Java (مثل: app.mail.host). |
| @Controller | يميز فئة كـ Spring MVC controller الذي يعيد طرق العرض (قوالب HTML). |
| @ControllerAdvice | يحدد مستشارًا عامًا لجميع المتحكمات (إدارة استثناءات مركزية، الربط، إلخ). |
| @CrossOrigin | يسمح بطلبات HTTP عبر الأصل (CORS) من نطاقات محددة أو جميع النطاقات. |
د
| التعليق التوضيحي | الوصف |
|---|---|
| @DataJpaTest | اختبار متخصص يقوم بتحميل طبقة JPA فقط (المستودعات، EntityManager، قاعدة بيانات في الذاكرة). |
| @DeleteMapping | اختصار لـ @RequestMapping(method = DELETE). يربط طريقة بطلب HTTP DELETE. |
| @Disabled | (JUnit 5) يعطل مؤقتًا اختبار وحدة دون حذفه من الكود. |
هـ
| التعليق التوضيحي | الوصف |
|---|---|
| @EnableAsync | يُفعل التنفيذ غير المتزامن في التطبيق. ضروري لكي يعمل @Async. |
| @EnableCaching | يُفعل التخزين المؤقت في التطبيق. ضروري لكي يعمل @Cacheable. |
| @EnableConfigurationProperties | يُفعل الربط التلقائي لخصائص التكوين إلى كائنات @ConfigurationProperties. |
| @EnableJms | يُفعل دعم JMS (Java Message Service) للرسائل في التطبيق. |
| @EnableJpaRepositories | يُفعل دعم مستودعات Spring Data JPA. يتم تكوينه تلقائيًا بواسطة Spring Boot. |
| @EnableScheduling | يُفعل جدولة المهام. ضروري لكي يعمل @Scheduled. |
| @EnableWebMvc | يُفعل تكوين Spring MVC. نادرًا ما يكون ضروريًا لأن Spring Boot يُفعله تلقائيًا. |
| @EnableWebSecurity | يُفعل التكوين المخصص لـ Spring Security. |
| @EnableMethodSecurity | يُفعل الأمان على مستوى الطرق (@PreAuthorize, @PostAuthorize, @Secured). |
| @Entity | يميز فئة ككيان JPA، مرتبط بجدول في قاعدة البيانات. |
| @Enumerated | يحدد كيفية تخزين enum Java في قاعدة البيانات: STRING (نص) أو ORDINAL (رقم). |
| @EventListener | يستمع للأحداث Spring (بدء التطبيق، أحداث مخصصة، إلخ). |
| @ExceptionHandler | يدير استثناءً محددًا في متحكم أو @ControllerAdvice. يعيد استجابة خطأ مخصصة. |
| @ExtendWith | (JUnit 5) يمدد وظائف الاختبارات مع الإضافات (مثل: SpringExtension, MockitoExtension). |
ف
| التعليق التوضيحي | الوصف |
|---|---|
| @Fallback | (Spring Cloud) يوفر طريقة احتياطية عندما تكون طريقة @CircuitBreaker معطلة. |
| @FlywayTest | يختبر ترحيلات قاعدة البيانات Flyway في اختبارات التكامل. |
| @Formula | (Hibernate) يحدد عمودًا محسوبًا على جانب SQL، بدون عمود فعلي في القاعدة. |
ج
| التعليق التوضيحي | الوصف |
|---|---|
| @GeneratedValue | يحدد استراتيجية التوليد التلقائي للمفتاح الأساسي (IDENTITY, SEQUENCE, UUID, AUTO). |
| @GetMapping | اختصار لـ @RequestMapping(method = GET). يربط طريقة بطلب HTTP GET. |
ع
| التعليق التوضيحي | الوصف |
|---|---|
| @Id | يميز حقلًا كمفتاح أساسي لكيان JPA. |
| @Import | يستورد فئات تكوين أخرى في فئة @Configuration. |
| @InitBinder | يخصص ربط البيانات بين طلبات HTTP وكائنات Java (التحويل، التحقق، التنسيق). |
ي
| التعليق التوضيحي | الوصف |
|---|---|
| @JoinColumn | يحدد عمود المفتاح الأجنبي لعلاقة JPA (@ManyToOne, @OneToOne). |
| @JoinTable | يحدد جدول الربط لعلاقة @ManyToMany (اسم الجدول، أعمدة الربط). |
| @JmsListener | يحدد طريقة تستمع للرسائل JMS على قائمة انتظار أو موضوع. |
| @JsonFormat | يخصص تنسيق التسلسل JSON (التواريخ، الأرقام). مثل: @JsonFormat(pattern = "yyyy-MM-dd"). |
| @JsonIgnore | يستبعد خاصية من التسلسل/إلغاء التسلسل JSON. |
| @JsonInclude | يتحكم في الخصائص المضمنة في JSON (مثل: استبعاد القيم null). |
| @JsonProperty | يعيد تسمية خاصية في JSON. مثل: @JsonProperty("full_name") لحقل fullName. |
| @JsonSubTypes | يحدد الأنواع الفرعية للتسلسل المتعدد الأشكال JSON. |
| @JsonTest | اختبار متخصص للتسلسل/إلغاء التسلسل JSON فقط. |
| @JsonTypeInfo | يضيف معلومات النوع في JSON للسماح بالتسلسل المتعدد الأشكال. |
| @JsonView | يرشح الخصائص JSON وفقًا للعرض المطلوب (مثل: العرض العام مقابل عرض المسؤول). |
ك
| التعليق التوضيحي | الوصف |
|---|---|
| @Lazy | يؤخر تهيئة bean حتى يتم استخدامه لأول مرة. يحسن وقت البدء. |
| @Lob | يشير إلى حقل من نوع Large Object: CLOB (نص طويل) أو BLOB (ثنائي). |
م
| التعليق التوضيحي | الوصف |
|---|---|
| @ManyToMany | يحدد علاقة عدة إلى عدة بين كيانين JPA. يستخدم جدول ربط. |
| @ManyToOne | يحدد علاقة عدة إلى واحد. الجانب "Many" يحمل المفتاح الأجنبي. |
| @MessageMapping | (WebSocket/STOMP) يربط طريقة بوجهة رسائل. |
| @MessagingGateway | (Spring Integration) يحدد واجهة بوابة لإرسال الرسائل. |
| @MockBean | يستبدل bean Spring بـ mock Mockito في اختبار. |
| @MockMvc | يحقن مثيل MockMvc لمحاكاة طلبات HTTP في الاختبارات. |
| @ModelAttribute | يربط معلمات طلب HTTP بكائن Java. يستخدم أيضًا لإضافة سمات إلى نموذج MVC. |
| @Modifying | يشير إلى أن طريقة @Query تنفذ UPDATE أو DELETE (وليس SELECT). |
ن
| التعليق التوضيحي | الوصف |
|---|---|
| @NamedQuery | يحدد استعلام JPQL مسمى مباشرة على كيان. |
| @NamedQueries | يجمع عدة @NamedQuery على نفس الكيان. |
و
| التعليق التوضيحي | الوصف |
|---|---|
| @OneToMany | يحدد علاقة واحد إلى عدة بين كيانين JPA. الجانب "One" هو الوالد. |
| @OneToOne | يحدد علاقة واحد إلى واحد بين كيانين JPA. |
| @Order | يحدد ترتيب أولوية bean. كلما كان الرقم أصغر، كانت الأولوية أعلى. |
ب
| التعليق التوضيحي | الوصف |
|---|---|
| @PatchMapping | اختصار لـ @RequestMapping(method = PATCH). تحديث جزئي لمورد. |
| @PathVariable | يستخرج متغيرًا من مسار URL. مثل: /users/\{id\} → @PathVariable Long id. |
| @PostAuthorize | يتحقق من الأذونات بعد تنفيذ طريقة (يمكنه التحقق من القيمة المعادة). |
| @PostConstruct | ينفذ طريقة مباشرة بعد حقن جميع تبعيات bean. |
| @PostMapping | اختصار لـ @RequestMapping(method = POST). إنشاء مورد جديد. |
| @PreAuthorize | يتحقق من الأذونات قبل تنفيذ طريقة. يدعم تعبيرات SpEL. |
| @PreDestroy | ينفذ طريقة مباشرة قبل تدمير bean (تنظيف، إغلاق الاتصالات). |
| @Primary | يحدد bean الافتراضي عندما يوجد عدة beans من نفس النوع. |
| @Profile | يُفعل bean أو تكوين فقط لبعض ملفات التعريف (dev، test، prod). |
| @PutMapping | اختصار لـ @RequestMapping(method = PUT). استبدال كامل لمورد. |
س
| التعليق التوضيحي | الوصف |
|---|---|
| @Qualifier | يحدد أي bean يتم حقنه عندما يوجد عدة beans من نفس النوع. |
| @Query | يحدد استعلام JPQL أو SQL أصلي مخصص على طريقة مستودع. |
ر
| التعليق التوضيحي | الوصف |
|---|---|
| @Repository | يميز فئة كطبقة وصول إلى البيانات. يُفعل ترجمة الاستثناءات SQL إلى استثناءات Spring. |
| @RequestBody | يُلغي تسلسل جسم طلب HTTP (JSON) إلى كائن Java. |
| @RequestHeader | يستخرج قيمة رأس HTTP (Authorization، Content-Type، User-Agent، إلخ). |
| @RequestMapping | تعليق توضيحي أساسي لربط URL بمتحكم أو طريقة. يمكن تحديد طريقة HTTP. |
| @RequestParam | يستخرج معلمة من سلسلة الاستعلام. مثل: /search?name=Java → @RequestParam String name. |
| @RequestPart | يستخرج جزءًا من طلب HTTP متعدد الأجزاء (ملفات، صور محملة). |
| @ResponseBody | يجبر الطريقة على إعادة JSON/XML مباشرة في جسم استجابة HTTP. |
| @ResponseStatus | يحدد رمز HTTP المعاد بواسطة طريقة (200، 201، 204، 404، إلخ) أو استثناء. |
| @RestClientTest | اختبار متخصص للعملاء REST. يقوم بتحميل تكوين العميل فقط. |
| @RestController | مزيج من @Controller + @ResponseBody. كل طريقة تعيد JSON مباشرة. |
| @RestControllerAdvice | مزيج من @ControllerAdvice + @ResponseBody. إدارة استثناءات عامة لـ API REST. |
| @Retryable | (Spring Retry) يعيد محاولة تنفيذ طريقة تلقائيًا في حالة الفشل (مثل: خطأ شبكة أو قاعدة بيانات). |
| @RolesAllowed | (JSR-250) يحدد الأدوار المسموح بها لطريقة. بديل قياسي لـ @Secured. |
ش
| التعليق التوضيحي | الوصف |
|---|---|
| @Scheduled | يخطط لتنفيذ دوري لطريقة (fixedRate, fixedDelay, cron). يتطلب @EnableScheduling. |
| @Scope | يحدد نطاق bean: singleton (افتراضي)، prototype, request, session, application. |
| @Secured | يحدد الأدوار المطلوبة للوصول إلى طريقة. أبسط من @PreAuthorize. |
| @SendTo | (WebSocket/STOMP) يحدد وجهة الرد لرسالة WebSocket. |
| @Service | يميز فئة كطبقة منطق الأعمال. يتم اكتشافه بواسطة فحص المكونات. |
| @SessionAttributes | يخزن سمات النموذج في جلسة HTTP بين الطلبات. |
| @SessionScope | يحدد نطاق bean كجلسة HTTP (bean واحد لكل جلسة مستخدم). |
| @SpyBean | يلف bean حقيقي بـ spy Mockito في الاختبارات (استدعاءات حقيقية باستثناء تلك المُعوَّضة/stub). |
| @SpringBootApplication | نقطة دخول التطبيق. يجمع بين @Configuration, @EnableAutoConfiguration و @ComponentScan. |
| @SpringBootTest | يقوم بتحميل سياق Spring الكامل لاختبارات التكامل. |
| @Sql | ينفذ نصوص SQL قبل أو بعد اختبار لإعداد أو تنظيف قاعدة البيانات. |
ت
| التعليق التوضيحي | الوصف |
|---|---|
| @Table | يخصص اسم الجدول، المخطط، قيود التفرد والفهارس لكيان JPA. |
| @Test | (JUnit) يميز طريقة كاختبار وحدة. |
| @TestConfiguration | يوفر تكوين Spring خاص بالاختبارات (beans اختبار، mocks). |
| @Timeout | (JUnit 5) يحدد حدًا زمنيًا أقصى لتنفيذ اختبار. يفشل الاختبار إذا تم تجاوز الحد. |
| @Transactional | يدير المعاملات قاعدة البيانات. يلتزم إذا نجح، يتراجع إذا كان هناك استثناء. readOnly = true يحسن القراءات. |
| @TransactionalEventListener | يستمع لحدث Spring وينفذه فقط بعد الالتزام (أو التراجع) للمعاملة. |
| @Transient | يستبعد حقلًا من الاستمرارية JPA (لا يوجد عمود في قاعدة البيانات). |
ف
| التعليق التوضيحي | الوصف |
|---|---|
| @Valid | يُفعل التحقق من صحة Bean Validation على كائن (@NotNull, @Size, @Email, إلخ). |
| @Validated | نسخة Spring من @Valid مع دعم مجموعات التحقق. |
| @Value | يحقن قيمة من ملف التكوين. مثل: @Value("${app.name}"). يدعم القيم الافتراضية وSpEL. |
| @ValueSource | (JUnit 5) يوفر قيم إدخال لاختبار معلمات. |
و
| التعليق التوضيحي | الوصف |
|---|---|
| @WebFluxTest | اختبار متخصص للمتحكمات WebFlux (برمجة تفاعلية). |
| @WebMvcTest | اختبار متخصص يقوم بتحميل طبقة المتحكم MVC فقط (لا قاعدة بيانات، لا خدمات حقيقية). |
| @WebTestClient | يحقن WebTestClient لمحاكاة طلبات HTTP في اختبارات WebFlux. |
التعليقات التوضيحية للتحقق (Bean Validation)
| التعليق التوضيحي | الوصف |
|---|---|
| @NotNull | لا يمكن أن يكون الحقل null. |
| @NotEmpty | لا يمكن أن يكون الحقل null ولا فارغًا (String، Collection، Map). |
| @NotBlank | لا يمكن أن يكون الحقل null، فارغًا أو يحتوي فقط على مسافات. |
| @Size(min, max) | يجب أن يكون الحجم بين min و max (String، Collection). |
| @Min(value) | يجب أن تكون القيمة الرقمية أكبر من أو تساوي value. |
| @Max(value) | يجب أن تكون القيمة الرقمية أقل من أو تساوي value. |
| يجب أن يكون الحقل بتنسيق عنوان بريد إلكتروني صالح. | |
| @Pattern(regexp) | يجب أن يتطابق الحقل مع التعبير العادي المعطى. |
| @Positive | يجب أن يكون الرقم موجبًا تمامًا (> 0). |
| @PositiveOrZero | يجب أن يكون الرقم موجبًا أو صفرًا (>= 0). |
| @Negative | يجب أن يكون الرقم سالبًا تمامًا (< 0). |
| @Past | يجب أن يكون التاريخ في الماضي. |
| @Future | يجب أن يكون التاريخ في المستقبل. |
| @DecimalMin | يجب أن تكون القيمة العشرية أكبر من أو تساوي الحد الأدنى. |
| @DecimalMax | يجب أن تكون القيمة العشرية أقل من أو تساوي الحد الأقصى. |
الإحصائيات
في الملخص
يغطي هذا القاموس 120+ تعليق توضيحي موزعة على:
- Core Spring : ~25 تعليق توضيحي (IoC، DI، التكوين، دورة الحياة)
- Web / REST : ~20 تعليق توضيحي (الربط، المعلمات، الردود، الأخطاء)
- Data / JPA : ~20 تعليق توضيحي (الكيانات، العلاقات، الاستعلامات، المعاملات)
- JSON / Jackson : ~7 تعليقات توضيحية (التنسيق، الفلترة، التجاهل)
- Security : ~7 تعليقات توضيحية (التكوين، التفويض)
- Cache : ~5 تعليقات توضيحية (cacheable، evict، put، config)
- Async / Scheduling : ~5 تعليقات توضيحية
- Test : ~25 تعليق توضيحي (JUnit، Spring Test، mocks)
- Validation : ~15 تعليق توضيحي (Bean Validation)
- Messaging : ~5 تعليقات توضيحية (JMS، WebSocket)
- Cloud / Resilience : ~3 تعليقات توضيحية (CircuitBreaker، Retry، Fallback)