Java Academy · درس

ربط الكيانات باستخدام تعليقات JPA

عرّف @Entity و@Table و@Id و@GeneratedValue و@Column و@Embedded لتصميم كيانات منظم

ربط الكيانات باستخدام تعليقات JPA درس مجاني في Java Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Java Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Java Academy 4 دروس في المجموع.

ما المقصود بتعيين كيانات JPA؟

يعيّن JPA (Jakarta Persistence API) فئات Java إلى جداول قاعدة البيانات باستخدام التعليقات التوضيحية. ويُعد Hibernate موفّر JPA الأكثر شيوعًا. لا حاجة إلى SQL DDL — إذ ينشئ JPA المخططات من التعليقات التوضيحية.

@Entity و@Table

يضع @Entity علامة على الفئة باعتبارها كيان JPA. ويخصّص @Table اسم الجدول والمخطط والقيود الفريدة. يجب أن يتضمن كل كيان مُنشئًا بلا معاملات (ويمكن أن يكون محميًا).

@Entity
@Table(name = "users", uniqueConstraints = @UniqueConstraint(columnNames = "email"))
public class User {
    // ...
    protected User() {} // required by JPA
}

@Id و@GeneratedValue

يضع @Id علامة على حقل المفتاح الأساسي. ويهيّئ @GeneratedValue استراتيجية التوليد التلقائي: IDENTITY (الزيادة التلقائية في قاعدة البيانات)، أو SEQUENCE (تسلسل قاعدة البيانات، وهو أفضل للإدراج المجمّع)، أو AUTO.

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
}

@Column: تخصيص الأعمدة

يحدّد @Column اسم العمود وطوله وقابليته لقبول القيمة الفارغة وتفرّده. وبدونه، يصبح اسم الحقل هو اسم العمود.

@Column(name = "full_name", nullable = false, length = 100)
private String name;
@Column(name = "email", unique = true, nullable = false)
private String email;
@Column(name = "created_at", updatable = false)
private LocalDateTime createdAt;

@Embedded و@Embeddable

استخرج مجموعة من الأعمدة إلى كائن قيمة قابل لإعادة الاستخدام، وأضف إليه التعليق التوضيحي @Embeddable. واستخدم @Embedded في الكيان لتضمين حقوله.

@Embeddable
public class Address {
    private String street, city, country;
    @Column(name = "zip_code") private String zipCode;
}
@Entity
public class User {
    @Embedded private Address address;
}

@Enumerated: تخزين التعدادات

خزّن التعدادات كسلسلة نصية لاسمها (STRING) أو كعدد صحيح ترتيبي (ORDINAL). استخدم STRING دائمًا — إذ تتعطل القيم الترتيبية عند إعادة ترتيب قيم التعداد.

@Enumerated(EnumType.STRING)
@Column(nullable = false)
private UserStatus status; // stored as "ACTIVE", "INACTIVE", etc.

@CreationTimestamp و@UpdateTimestamp

تعليقات توضيحية خاصة بـHibernate تضبط الطابع الزمني تلقائيًا عند الإدراج والتحديث على التوالي — فلا حاجة إلى @PrePersist يدويًا.

@CreationTimestamp
@Column(updatable = false)
private LocalDateTime createdAt;
@UpdateTimestamp
private LocalDateTime updatedAt;

@Transient: استبعاد الحقول

لا تُخزَّن الحقول التي تحمل التعليق التوضيحي @Transient. استخدمه للحقول المشتقة أو المحسوبة التي لا ينبغي تخزينها في قاعدة البيانات.

@Transient
public String getFullName() { return firstName + " " + lastName; }

@Lob: الكائنات الكبيرة

استخدم @Lob لتعيين أعمدة النصوص الكبيرة (TEXT/CLOB) أو البيانات الثنائية (BLOB). ويعيّن PostgreSQL‏ @Lob String إلى TEXT.

@Lob
@Column(name = "content")
private String content; // maps to TEXT in PostgreSQL

عقد equals وhashCode

يجب أن تنفّذ كيانات JPA الموجودة في المجموعات equals / hashCode استنادًا إلى مفتاح الأعمال (وليس المعرّف المُولَّد، الذي تكون قيمته null قبل الحفظ). استخدم @NaturalId أو مفتاحًا بديلًا من نوع UUID.

@Override public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof User u)) return false;
    return email != null && email.equals(u.email);
}
@Override public int hashCode() { return getClass().hashCode(); }

@Version للقفل التفاؤلي

أضف حقلًا يحمل التعليق التوضيحي @Version. يزيد Hibernate قيمته عند كل تحديث. وإذا حدّثت معاملتان الصف نفسه بالتزامن، تطرح المعاملة الثانية OptimisticLockException.

@Version
private Long version; // auto-managed by Hibernate

فحص سريع

لماذا ينبغي أن يستخدم @Enumerated‏ STRING بدلًا من ORDINAL؟

مراجعة

استخدم @Entity/@Table لتعيين الفئة إلى الجدول. واستخدم @Id+@GeneratedValue للمفاتيح الأساسية. واستخدم @Column للقيود. واستخدم @Embedded لكائنات القيمة. استخدم @Enumerated(STRING) دائمًا. أضف @Version للقفل التفاؤلي.

الأسئلة الشائعة

هل درس «ربط الكيانات باستخدام تعليقات JPA» مجاني؟

نعم — نص درس «ربط الكيانات باستخدام تعليقات JPA» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Java Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Java Academy 4 دروس في المجموع.

ماذا ستتعلم في «ربط الكيانات باستخدام تعليقات JPA»؟

عرّف @Entity و@Table و@Id و@GeneratedValue و@Column و@Embedded لتصميم كيانات منظم تتمرن على Java Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Java Academy؟

لا تُشترط خبرة سابقة. Java Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «ربط الكيانات باستخدام تعليقات JPA»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Java Academy هذا؟

نعم. كل درس في Java Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Java Academy