جافا: Spring Data و JPA

عندما يبدأ كثير من المطورين في بناء تطبيقات Java حقيقية، يكتشفون بسرعة أن كتابة SQL في كل مكان داخل المشروع ليست فقط متعبة، بل تصبح مع الوقت عبئًا ثقيلًا على الصيانة والاختبار والتوسع. هنا يأتي Spring Data JPA كواحد من تلك الأدوات التي تشعر معها أن المشروع صار أكثر هدوءًا وتنظيمًا، وكأنك نقلت جزءًا كبيرًا من الفوضى إلى مكان أكثر ترتيبًا. الفكرة ليست أن Spring Data JPA "يكتب لك كل شيء" بطريقة سحرية، بل أنه يمنحك طبقة وسطى ذكية بين Java Objects وقاعدة البيانات، طبقة تقلل التكرار، وتمنحك أسلوبًا واضحًا للتعامل مع البيانات، وتجعلك تركز أكثر على منطق العمل بدل الانشغال في كل مرة بكيفية كتابة نفس الاستعلامات من الصفر.

في هذا المقال الطويل سنمشي خطوة خطوة، لكن ليس بطريقة جافة أو نظرية فقط. سنحاول أن نفهم الفكرة من الداخل، ثم ننتقل إلى الأمثلة العملية، ثم إلى أنماط الاستخدام الشائعة، ثم إلى التفاصيل التي غالبًا ما تُهمل في البداية مثل العلاقات بين الجداول، المعاملات Transaction، الترحيل Pagination، البحث الديناميكي، الأداء، وتحسين الاستعلامات. سأكتب بأسلوب هادئ ومباشر، وكأننا نجلس معًا أمام مشروع حقيقي ونبني طبقة البيانات قطعة قطعة. والهدف أن تخرج من هنا بصورة واضحة: متى تستخدم JPA، ومتى تعتمد على Spring Data، وكيف تكتب كودًا نظيفًا لا ينهار بعد أول توسع في المشروع.

ما هو JPA أصلًا؟

JPA اختصار لـ Java Persistence API، وهي ليست تنفيذًا Implementation بحد ذاتها، بل مواصفة Specification تحدد الطريقة القياسية للتعامل مع البيانات العلائقية في تطبيقات Java. بمعنى آخر، JPA تقول لك: "هذا هو الشكل العام الذي ينبغي أن تلتزم به إذا أردت أن تتعامل مع الكائنات Objects وكأنها صفوف Rows في قاعدة البيانات". أما التنفيذ الحقيقي فيأتي من أدوات مثل Hibernate، وهو الأكثر شهرة وانتشارًا.

الهدف الأساسي من JPA هو Object-Relational Mapping أو اختصارًا ORM، أي ربط الكائنات في Java بالجداول في قاعدة البيانات. بدل أن تكتب SQL في كل مرة لتجلب مستخدمًا أو تحفظ منتجًا أو تحدث طلبًا، يمكنك أن تمثل هذه الأشياء على شكل Entities في Java، ثم تترك JPA تتولى عملية التخزين والاسترجاع والتحويل بين العالمين. هذه النقطة وحدها كفيلة بتغيير طريقة تفكيرك في تصميم التطبيقات، لأنك تبدأ في بناء النموذج منطقياً حول الكائنات وعلاقاتها، وليس فقط حول الجداول والاستعلامات.

لكن يجب أن أكون صريحًا: JPA لا تلغي الحاجة إلى فهم SQL أو قواعد البيانات. من الأخطاء الشائعة جدًا أن يتعامل المطور مع JPA وكأنه "بديل سحري" لا يحتاج معه إلى التفكير. الحقيقة أن JPA يخفف العمل، لكنه لا يعفيك من فهم الأداء، الفهارس Indexes، العلاقات، التحميل الكسول Lazy Loading، والقيود Constraints. كلما فهمت قاعدة البيانات أكثر، استفدت من JPA أكثر.

ما هي Spring Data JPA؟

إذا كانت JPA هي المواصفة، فـ Spring Data JPA هي طبقة من Spring تجعل استخدام JPA أسهل بكثير وأكثر عملية. Spring Data لا تستبدل JPA، بل تبني فوقها abstractions مريحة جدًا. بدل أن تكتب طبقات DAO كاملة بنفسك، أو تكرر العمليات الأساسية مثل save وfindById وdelete، يمنحك Spring Data Repository interfaces جاهزة، ويولد لك تنفيذًا تلقائيًا لكثير من هذه العمليات.

وهنا تكمن القوة الحقيقية: أنت لا تحتاج إلى كتابة boilerplate code لكل كيان. يمكنك أن تعلن فقط عن interface يمتد من JpaRepository أو CrudRepository، ثم تحصل على مجموعة عمليات أساسية مجانية تقريبًا. ثم إذا أردت استعلامات مخصصة، يمكنك إضافة methods بأسماء مفهومة، مثل findByEmail أو findByStatusAndCreatedAtAfter، وسيقوم Spring Data بتحليل الاسم وتوليد الاستعلام المناسب.

هذه البساطة ليست مجرد رفاهية. هي السبب في أن كثيرًا من مشاريع Spring تكون مرتبة وسهلة التوسع عندما تُبنى بشكل صحيح. فبدل التعمق في تفاصيل التنفيذ المباشر لكل مرة، أنت تحدد سلوكًا عالي المستوى، وSpring Data يقوم بالباقي.

الفرق بين JPA و Hibernate و Spring Data JPA

هذا السؤال يتكرر كثيرًا، وهو مهم جدًا لأن الخلط بين هذه المصطلحات يسبب ارتباكًا عند البداية.

JPA هي المواصفة القياسية. Hibernate هو أشهر تنفيذ لهذه المواصفة. Spring Data JPA هو مشروع من Spring يبسط استخدام JPA ويقدم abstraction أعلى فوقها.

يمكنك أن تتخيلها هكذا: JPA هي القواعد، Hibernate هو اللاعب الذي يطبق القواعد، وSpring Data JPA هو المدرب الذي يسهل عليك استخدام اللاعب داخل فريق Spring. عمليًا، أغلب المشاريع الحديثة التي تستخدم Spring Data JPA تعتمد داخليًا على Hibernate كـ provider، لكنك لا تُجبر على أن تكتب Hibernate-specific code طوال الوقت.

الفائدة من هذا الفصل أن يبقى كودك أقرب إلى القياسي. فإذا انتقلت من Hibernate إلى provider آخر، أو أردت صيانة المشروع بعد سنوات، فإن اعتمادك على المفاهيم القياسية يجعل الأمور أكثر أمانًا واستقرارًا.

إعداد المشروع

لنأخذ مثالًا بسيطًا في Spring Boot. عادة ستحتاج dependencies الخاصة بـ Spring Web وSpring Data JPA وقاعدة البيانات التي ستستخدمها مثل PostgreSQL أو MySQL أو H2 للتجارب المحلية.

في pom.xml قد يبدو الأمر كالتالي:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>

    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
</dependencies>

وفي application.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/shop_db
spring.datasource.username=postgres
spring.datasource.password=secret
spring.datasource.driver-class-name=org.postgresql.Driver

spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

هناك أمر مهم هنا: ddl-auto=update مفيد أثناء التطوير، لكنه ليس الخيار المفضل في الإنتاج. في المشاريع الجادة، من الأفضل الاعتماد على migration tools مثل Flyway أو Liquibase بدل ترك Hibernate يغير بنية الجداول تلقائيًا دون ضبط دقيق. لكن للتعلم والتجارب الأولى، هذا الخيار يسهّل الحياة.

أول Entity: تمثيل كائن Java كجدول

لنبدأ بكيان بسيط يمثل مستخدمًا في النظام:

import jakarta.persistence.*;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import java.time.LocalDateTime;

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotBlank
    @Size(max = 100)
    @Column(nullable = false, length = 100)
    private String name;

    @Email
    @NotBlank
    @Column(nullable = false, unique = true, length = 150)
    private String email;

    @Column(nullable = false)
    private boolean active = true;

    @Column(name = "created_at", nullable = false, updatable = false)
    private LocalDateTime createdAt;

    @PrePersist
    public void onCreate() {
        this.createdAt = LocalDateTime.now();
    }

    public User() {
    }

    public User(String name, String email) {
        this.name = name;
        this.email = email;
    }

    public Long getId() {
        return id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public boolean isActive() {
        return active;
    }

    public void setActive(boolean active) {
        this.active = active;
    }

    public LocalDateTime getCreatedAt() {
        return createdAt;
    }
}

في هذا المثال، نلاحظ عدة أشياء مهمة. @Entity تعني أن هذا الصف مرتبط بجدول قاعدة البيانات. @Table تمنحك اسمًا مخصصًا للجدول. @Id و@GeneratedValue تحددان المفتاح الأساسي وطريقة توليده. أما التعليقات التوضيحية مثل @NotBlank و@Email فهي من Bean Validation وتساعدك على التحقق من صحة البيانات قبل الحفظ. هذا المزج بين validation وJPA عملي جدًا، لأنه يمنع كثيرًا من المشاكل من الوصول إلى قاعدة البيانات أصلًا.

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

Repository: البوابة إلى البيانات

الآن ننتقل إلى Spring Data Repository:

import org.springframework.data.jpa.repository.JpaRepository;
import java.util.Optional;
import java.util.List;

public interface UserRepository extends JpaRepository<User, Long> {
    Optional<User> findByEmail(String email);

    List<User> findByActiveTrue();

    List<User> findByNameContainingIgnoreCase(String name);

    boolean existsByEmail(String email);
}

هذا الملف صغير جدًا، لكن تأثيره كبير. بمجرد أن ترث من JpaRepository<User, Long> ستحصل على عمليات مثل save, findById, findAll, deleteById, count, flush وغيرها. ثم بإضافة methods بأسماء معبرة، يمكنك الحصول على استعلامات مشتقة Derived Queries دون كتابة JPQL يدويًا في كل مرة.

مستوى الراحة هنا قد يبدو بسيطًا في البداية، لكنه يصبح ضخمًا عندما يكبر المشروع. تخيل عدد الأسطر التي توفرها عندما يكون لديك عشرات الكيانات، وكل كيان يحتاج عمليات CRUD أساسية. Spring Data يتولى هذه الطبقة المتكررة، وأنت تتفرغ لباقي التصميم.

لماذا اسم method مهم جدًا في Spring Data؟

Spring Data يقرأ اسم method ويحاول فهم نيتك. فمثلًا:

List<User> findByNameAndActiveTrue(String name);

هذا يعني أنه سيبحث عن مستخدمين الاسم لديهم يطابق القيمة المعطاة، والحالة active تساوي true. ويمكنك أيضًا استخدام كلمات مثل Or, Between, LessThan, GreaterThan, Containing, StartsWith, OrderBy, وIgnoreCase.

أمثلة:

List<User> findByCreatedAtAfter(LocalDateTime dateTime);

List<User> findByEmailEndingWith(String domain);

List<User> findByNameOrderByCreatedAtDesc(String name);

هذا الأسلوب رائع للاحتياجات البسيطة والمتوسطة. لكن حين تصبح الشروط كثيرة أو ديناميكية جدًا، قد يكون الأفضل التوجه إلى @Query أو Specifications أو QueryDSL، لأن أسماء الطرق الطويلة تصبح مرهقة وغير مقروءة.

طبقة Service: مكان منطق العمل

واحدة من أفضل الممارسات في مشاريع Spring هي ألا تضع كل شيء داخل Controller أو Repository. الـ Repository مسؤول عن الوصول للبيانات، أما الـ Service فمهمته تنفيذ منطق العمل Business Logic. هذا الفصل يجعل الكود أنظف وأسهل في الاختبار.

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

@Service
public class UserService {

    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Transactional
    public User createUser(User user) {
        if (userRepository.existsByEmail(user.getEmail())) {
            throw new IllegalArgumentException("Email already exists");
        }
        return userRepository.save(user);
    }

    @Transactional(readOnly = true)
    public User getUserById(Long id) {
        return userRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("User not found"));
    }

    @Transactional(readOnly = true)
    public List<User> getActiveUsers() {
        return userRepository.findByActiveTrue();
    }

    @Transactional
    public User updateUserName(Long id, String newName) {
        User user = getUserById(id);
        user.setName(newName);
        return userRepository.save(user);
    }

    @Transactional
    public void deactivateUser(Long id) {
        User user = getUserById(id);
        user.setActive(false);
        userRepository.save(user);
    }
}

هنا نرى قيمة @Transactional. المعاملات ليست مجرد تزيين للكود، بل هي ضمانة عملية أن العمليات المرتبطة ببعضها تنفذ ضمن سياق واحد. فإذا فشلت خطوة في المنتصف، يمكن التراجع Rollback بسهولة. هذا مهم جدًا في أي نظام فيه حفظ متعدد الخطوات أو تحديثات مترابطة.

لاحظ أيضًا أن @Transactional(readOnly = true) مفيدة للعمليات القرائية لأنها تعطي إشارة أوضح للإطار، وقد تحسن السلوك والأداء في بعض الحالات.

Controller بسيط للتجربة

import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @PostMapping
    public User create(@RequestBody User user) {
        return userService.createUser(user);
    }

    @GetMapping("/{id}")
    public User getById(@PathVariable Long id) {
        return userService.getUserById(id);
    }

    @GetMapping
    public List<User> getAllActiveUsers() {
        return userService.getActiveUsers();
    }

    @PutMapping("/{id}/name")
    public User updateName(@PathVariable Long id, @RequestParam String name) {
        return userService.updateUserName(id, name);
    }

    @PutMapping("/{id}/deactivate")
    public void deactivate(@PathVariable Long id) {
        userService.deactivateUser(id);
    }
}

في مشروع واقعي، قد لا ترغب في إرجاع Entity مباشرة من الـ Controller، خاصة إذا كانت العلاقات كثيرة أو فيها بيانات حساسة. الأفضل كثيرًا استخدام DTOs، لكنني هنا أبقي المثال واضحًا ومباشرًا كي نركز على JPA نفسها.

الحذر من إرجاع Entity مباشرة

هذه نقطة مهمة جدًا، ويفضل الانتباه لها مبكرًا. عندما تعيد Entity مباشرة من API، قد تواجه مشكلات مثل:

التحكم في ما يظهر للعميل يصبح أضعف.
العلاقات المرتبطة قد تسبب حلقات لا نهائية في serialization.
قد تتسرب حقول لا تريد كشفها.
قد يكون شكل الـ API مرتبطًا جدًا بشكل الجداول، وهذا يجعل التغييرات مؤلمة.

لذلك من الحكمة استخدام DTO layer. مثال:

public record UserResponse(Long id, String name, String email, boolean active) {
}

ثم في الخدمة أو الـ mapper تحوّل من Entity إلى DTO. قد يبدو هذا العمل إضافيًا في البداية، لكنه يريحك كثيرًا عندما يتوسع المشروع.

العلاقات بين الكيانات

قوة JPA الحقيقية تظهر عندما تبدأ في التعامل مع العلاقات. فالعالم الحقيقي ليس جداول منفصلة بلا ارتباطات، بل كيانات لها علاقات متعددة مثل مستخدم لديه طلبات، طلب يحتوي عناصر، عنصر ينتمي إلى منتج، وهكذا.

OneToMany وManyToOne

لنقم ببناء مثال متجر بسيط. المستخدم يمكن أن يملك عدة طلبات.

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;

@Entity
@Table(name = "customers")
public class Customer {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String fullName;

    @OneToMany(mappedBy = "customer", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<Order> orders = new ArrayList<>();

    public Customer() {
    }

    public Customer(String fullName) {
        this.fullName = fullName;
    }

    public void addOrder(Order order) {
        orders.add(order);
        order.setCustomer(this);
    }

    public void removeOrder(Order order) {
        orders.remove(order);
        order.setCustomer(null);
    }

    public Long getId() {
        return id;
    }

    public String getFullName() {
        return fullName;
    }

    public List<Order> getOrders() {
        return orders;
    }
}

والطرف الآخر:

import jakarta.persistence.*;
import java.time.LocalDateTime;

@Entity
@Table(name = "orders")
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String orderNumber;

    private LocalDateTime createdAt = LocalDateTime.now();

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "customer_id")
    private Customer customer;

    public Order() {
    }

    public Order(String orderNumber) {
        this.orderNumber = orderNumber;
    }

    public Long getId() {
        return id;
    }

    public String getOrderNumber() {
        return orderNumber;
    }

    public Customer getCustomer() {
        return customer;
    }

    public void setCustomer(Customer customer) {
        this.customer = customer;
    }
}

في هذا المثال، لاحظ أن Customer هو الطرف الرئيسي، وOrder هو الطرف الذي يملك المفتاح الخارجي. في @OneToMany نستخدم mappedBy = "customer" لنقول إن العلاقة تُدار من جهة Order. كما نستخدم cascade = CascadeType.ALL حتى تنتقل العمليات الأساسية من العميل إلى طلباته عند الحاجة، وorphanRemoval = true لحذف الطلب من قاعدة البيانات إذا أزلته من القائمة ولم يعد مرتبطًا بأي عميل.

هذه الخصائص مفيدة جدًا، لكنها تحتاج فهمًا دقيقًا. فـ cascade قوي، وإذا استخدمته دون انتباه قد تجد أن حذف كائن واحد أدى إلى حذف سلسلة من الكائنات المرتبطة به. لهذا السبب لا ينبغي استخدامه بعشوائية.

ManyToMany

علاقة كثير إلى كثير شائعة مثل الطلاب والدورات، أو المقالات والوسوم Tags. مثال مبسط:

@Entity
public class Student {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @ManyToMany
    @JoinTable(
        name = "student_courses",
        joinColumns = @JoinColumn(name = "student_id"),
        inverseJoinColumns = @JoinColumn(name = "course_id")
    )
    private List<Course> courses = new ArrayList<>();
}

@Entity
public class Course {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String title;

    @ManyToMany(mappedBy = "courses")
    private List<Student> students = new ArrayList<>();
}

عند هذه النقطة يجب أن تتذكر أن علاقة ManyToMany المباشرة ليست دائمًا أفضل حل في المشاريع الواقعية، لأن كثيرًا من العلاقات "الكثير إلى الكثير" تحتاج حقولًا إضافية في جدول الربط، مثل تاريخ الانضمام أو الحالة أو الدرجة. عندها من الأفضل تحويلها إلى Entity مستقلة تمثل علاقة الربط نفسها.

Fetch Types: Lazy وEager

من أكثر المواضيع التي تربك المطورين في JPA مسألة التحميل Lazy vs Eager. باختصار، FetchType.LAZY يعني أن البيانات المرتبطة لن تُجلب فورًا، بل عند الحاجة الفعلية إليها. أما FetchType.EAGER فيعني تحميلها فورًا مع الكيان الرئيسي.

على الورق يبدو الأمر بسيطًا، لكن في الواقع له أثر كبير على الأداء وعلى احتمال ظهور أخطاء مثل LazyInitializationException. لذلك من الأفضل أن تتعامل مع lazy loading بوعي، لا بارتجال.

مثال:

@ManyToOne(fetch = FetchType.LAZY)
private Customer customer;

لو جلبت الطلب Order ثم حاولت الوصول إلى customer خارج سياق transaction مفتوح، قد تواجه مشكلة لأن JPA لم يعد قادرًا على تحميل البيانات المؤجلة. هذا يعني أن التصميم الصحيح لحدود المعاملات مهم جدًا. غالبًا يُنصح أن تكون البيانات المطلوبة جاهزة داخل service layer، وأن لا تعتمد على التحميل المؤجل بعد خروجك من السياق المناسب.

الاستعلامات المخصصة باستخدام @Query

أحيانًا لا تكفي أسماء methods المشتقة. هنا يأتي دور @Query.

import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

import java.util.List;

public interface UserRepository extends JpaRepository<User, Long> {

    @Query("SELECT u FROM User u WHERE u.active = true AND u.name LIKE %:keyword%")
    List<User> searchActiveUsers(@Param("keyword") String keyword);

    @Query("SELECT u FROM User u WHERE u.email = :email")
    User findUserByEmail(@Param("email") String email);
}

يمكنك كتابة JPQL، وهو يشبه SQL لكنه يعمل على الكيانات وليس على الجداول مباشرة. هذه نقطة ممتازة لأنك تفكر في User وOrder وCustomer بدل أسماء الجداول فقط.

وإذا احتجت SQL أصليًا Native Query:

@Query(value = "SELECT * FROM users WHERE active = true AND email LIKE %:domain%", nativeQuery = true)
List<User> findUsersByEmailDomain(@Param("domain") String domain);

الاستعلام الأصلي مفيد عندما تحتاج ميزة خاصة بقاعدة بيانات معينة أو تحسينًا دقيقًا جدًا، لكن استخدامه ينبغي أن يكون محسوبًا، لأنك حينها تقترب أكثر من تفاصيل القاعدة وتفقد بعض مرونة JPA.

Pagination وSorting

عندما يتضخم عدد السجلات، لا يمكنك أن تعيد كل شيء دفعة واحدة. الترحيل Pagination هنا يصبح ضروريًا. Spring Data يجعل هذا سهلًا جدًا.

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

public interface UserRepository extends JpaRepository<User, Long> {
    Page<User> findByActiveTrue(Pageable pageable);
}

ثم في service أو controller:

import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Sort;

@Service
public class UserPagingService {

    private final UserRepository userRepository;

    public UserPagingService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public Page<User> getUsers(int page, int size) {
        return userRepository.findAll(PageRequest.of(page, size, Sort.by("createdAt").descending()));
    }
}

الجميل هنا أنك لا تحتاج لتخصيص الكثير من الكود. ومع ذلك، يجب أن تتأكد من أن واجهتك الأمامية تفهم pagination بشكل جيد، وأنك تعرض البيانات بطريقة سلسة للمستخدم. فالتقنيات الخلفية الجيدة يجب أن تنعكس على تجربة استخدام جيدة، وإلا فستبقى مجرد تحسينات داخلية لا يشعر بها أحد.

Sort وحده

إذا كنت لا تحتاج pagination ولكن تريد ترتيب النتائج فقط:

List<User> findAllByOrderByNameAsc();

أو عبر Sort:

List<User> users = userRepository.findAll(Sort.by(Sort.Direction.DESC, "createdAt"));

Projections: جلب ما تحتاجه فقط

في بعض الأحيان لا تريد كل حقول الكيان. قد تحتاج فقط الاسم والبريد الإلكتروني مثلاً. هنا تأتي projections لتخفيف الوزن وتحسين الأداء.

public interface UserSummary {
    String getName();
    String getEmail();
}

وفي repository:

List<UserSummary> findByActiveTrue();

أو باستخدام constructor projection:

public record UserDto(Long id, String name) {
}

@Query("SELECT new com.example.demo.UserDto(u.id, u.name) FROM User u")
List<UserDto> findAllUserDtos();

هذه التقنية مفيدة جدًا عندما تكون البيانات المطلوبة لواجهة معينة صغيرة، ولا داعي لجلب كل شيء من قاعدة البيانات ثم إعادة تصفيته في الذاكرة.

Auditing: من أنشأ السجل ومتى؟

في المشاريع الحقيقية، ستحتاج غالبًا إلى معرفة من أنشأ السجل ومتى، ومن عدله ومتى. JPA وSpring Data يوفران auditing بشكل أنيق.

أولًا نفعّل الدعم:

@Configuration
@EnableJpaAuditing
public class JpaConfig {
}

ثم نضيف حقلًا مشتركًا:

import jakarta.persistence.Column;
import jakarta.persistence.MappedSuperclass;
import jakarta.persistence.EntityListeners;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;

import java.time.LocalDateTime;

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class AuditableEntity {

    @CreatedDate
    @Column(updatable = false)
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

    public LocalDateTime getCreatedAt() {
        return createdAt;
    }

    public LocalDateTime getUpdatedAt() {
        return updatedAt;
    }
}

ثم ترث منه الكيانات:

@Entity
public class Product extends AuditableEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
}

هذا الأسلوب يقلل التكرار ويجعل البنية أكثر نظافة. والمهم هنا أن تفكر في الحقول المشتركة كجزء من التصميم العام، لا كحقول متناثرة في كل كيان على حدة.

Optimistic Locking: الحماية من التضارب

عندما يعمل أكثر من مستخدم أو عملية على نفس السجل، قد يحدث تضارب في التحديثات. JPA توفر optimistic locking باستخدام @Version.

import jakarta.persistence.*;

@Entity
public class Account {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String ownerName;

    private double balance;

    @Version
    private Long version;
}

هذا يعني أن JPA تتأكد عند التحديث أن النسخة لم تتغير من قِبل عملية أخرى. إذا تغيرت، يتم رمي استثناء، ويمكنك التعامل معه بشكل مناسب. هذا مهم جدًا في الأنظمة المالية أو أي نظام فيه تحديثات متزامنة.

معاملات Transaction بشكل عملي

من السهل أن نكتب @Transactional ونمضي، لكن من المفيد فهم ما الذي يحدث فعليًا. عندما تبدأ المعاملة، Spring يفتح سياقًا يحافظ على اتساق العمليات. إذا حدث خطأ قبل نهاية العملية، فهناك rollback.

مثال:

@Transactional
public void placeOrder(Long customerId, List<String> items) {
    Customer customer = customerRepository.findById(customerId)
            .orElseThrow(() -> new RuntimeException("Customer not found"));

    Order order = new Order("ORD-" + System.currentTimeMillis());
    customer.addOrder(order);

    customerRepository.save(customer);
}

هنا تعتمد على cascade لحفظ الطلب الجديد مع العميل. ولو حدث استثناء قبل الإنهاء، فلن يتم حفظ شيء. هذا النوع من الاتساق هو ما يجعل الأنظمة التجارية أكثر أمانًا.

لكن لا تنسَ أن حدود الـ transaction ينبغي أن تكون مدروسة. لا تجعلها واسعة جدًا بلا داعٍ، ولا صغيرة جدًا بحيث تفصل خطوات يجب أن تبقى مترابطة. التوازن هنا جزء من الخبرة.

Specifications: البحث الديناميكي

أحيانًا يحتاج المستخدم إلى فلترة معقدة: الاسم اختياري، الحالة اختيارية، التاريخ اختياري، والمدينة اختيارية. كتابة methods منفصلة لكل احتمال تصبح فوضوية بسرعة. هنا تأتي Specifications.

أولًا نجعل repository يدعمها:

import org.springframework.data.jpa.repository.JpaSpecificationExecutor;

public interface UserRepository extends JpaRepository<User, Long>, JpaSpecificationExecutor<User> {
}

ثم نكتب المواصفات:

import org.springframework.data.jpa.domain.Specification;

public class UserSpecifications {

    public static Specification<User> nameContains(String name) {
        return (root, query, cb) -> 
                name == null ? null : cb.like(cb.lower(root.get("name")), "%" + name.toLowerCase() + "%");
    }

    public static Specification<User> activeEquals(Boolean active) {
        return (root, query, cb) ->
                active == null ? null : cb.equal(root.get("active"), active);
    }
}

ثم الاستخدام:

import org.springframework.data.jpa.domain.Specification;

Specification<User> spec = Specification.where(UserSpecifications.nameContains("ali"))
        .and(UserSpecifications.activeEquals(true));

List<User> results = userRepository.findAll(spec);

هذا الأسلوب ممتاز عندما يكون لديك بحث متقدم ومركب. صحيح أنه يتطلب فهمًا أعمق، لكنه يفتح بابًا قويًا جدًا لبناء بحث مرن دون تحويل الكود إلى سلسلة من if/else غير المنتهية.

Entity Graphs لتقليل مشكلة N+1

من أكثر المشاكل التي يواجهها مطورو JPA مشكلة N+1 query. ببساطة، قد تجلب قائمة من الكيانات، ثم يقوم JPA بعمل استعلام إضافي لكل كيان مرتبط. هذا يضرب الأداء أحيانًا بشكل مزعج.

أحد الحلول هو @EntityGraph:

import org.springframework.data.jpa.repository.EntityGraph;

public interface OrderRepository extends JpaRepository<Order, Long> {

    @EntityGraph(attributePaths = {"customer"})
    List<Order> findAll();
}

بهذا توجه JPA إلى جلب العلاقة المطلوبة ضمن الاستعلام أو بطريقة أكثر كفاءة. ولكن مرة أخرى، يجب مراقبة SQL الناتج فعليًا، لأن التحسين الحقيقي لا يأتي من التعليق التوضيحي وحده، بل من فهم ما يُنفذ على مستوى القاعدة.

كيف تفكر بطريقة صحيحة مع JPA؟

هناك فرق كبير بين مطور "يستخدم JPA" ومطور "يفكر بـ JPA بشكل سليم". الأول قد يكتب Entity ثم Repository ثم يعمل كل شيء. الثاني يفكر في:

ما حدود الكيان؟
ما العلاقة الحقيقية بين الجداول؟
هل أحتاج DTO أم Entity مباشرة؟
هل الاستعلام سيكبر مع الوقت؟
هل التحميل الكسول سيكسر API لاحقًا؟
هل cascade مناسب هنا أم خطر؟
هل يوجد N+1؟
هل هذا التحديث يجب أن يكون ضمن transaction واحدة؟

هذه الأسئلة هي التي تصنع الفرق في المشاريع الكبيرة. وأقولها ببساطة: JPA تجعل البداية سهلة، لكن الصعوبة الحقيقية ليست في كتابة أول كود، بل في كتابة كود يبقى واضحًا بعد ستة أشهر وسنة وسنتين.

مثال كامل: متجر صغير

لنجمع بعض الأجزاء في مثال شبه متكامل. لدينا Product وCategory.

import jakarta.persistence.*;

@Entity
public class Category {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String name;

    public Category() {
    }

    public Category(String name) {
        this.name = name;
    }

    public Long getId() {
        return id;
    }

    public String getName() {
        return name;
    }
}

import jakarta.persistence.*;
import java.math.BigDecimal;

@Entity
public class Product {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    private BigDecimal price;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "category_id")
    private Category category;

    public Product() {
    }

    public Product(String name, BigDecimal price, Category category) {
        this.name = name;
        this.price = price;
        this.category = category;
    }

    public Long getId() {
        return id;
    }

    public String getName() {
        return name;
    }

    public BigDecimal getPrice() {
        return price;
    }

    public Category getCategory() {
        return category;
    }
}

Repository:

import org.springframework.data.jpa.repository.JpaRepository;
import java.util.List;

public interface ProductRepository extends JpaRepository<Product, Long> {
    List<Product> findByCategory_Name(String name);
}

Service:

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.math.BigDecimal;
import java.util.List;

@Service
public class ProductService {

    private final ProductRepository productRepository;
    private final CategoryRepository categoryRepository;

    public ProductService(ProductRepository productRepository, CategoryRepository categoryRepository) {
        this.productRepository = productRepository;
        this.categoryRepository = categoryRepository;
    }

    @Transactional
    public Product createProduct(String productName, BigDecimal price, Long categoryId) {
        Category category = categoryRepository.findById(categoryId)
                .orElseThrow(() -> new RuntimeException("Category not found"));

        Product product = new Product(productName, price, category);
        return productRepository.save(product);
    }

    @Transactional(readOnly = true)
    public List<Product> getProductsByCategory(String categoryName) {
        return productRepository.findByCategory_Name(categoryName);
    }
}

هذا المثال يوضح كيف تتعاون القطع معًا: Entity تمثل البيانات، Repository للوصول، Service لمنطق العمل، Transaction لضبط العملية، وSpring Data لتقليل الكود المتكرر. عندما ترى هذا النمط مرارًا، يصبح أسهل بكثير أن تبني عليه أي مشروع جديد.

أخطاء شائعة يجب الانتباه لها

من الأخطاء الشائعة جدًا أن يضع المطور كل منطق المشروع داخل Repository أو Controller، ثم يندهش بعد أشهر أن الكود صار متشابكًا. كذلك من الشائع إساءة استخدام EAGER في كل علاقة "احتياطًا"، وهذا غالبًا يؤدي إلى استعلامات ثقيلة ومفاجآت في الأداء. ومن الأخطاء أيضًا تجاهل equals وhashCode في بعض السياقات الحساسة، أو اعتماد toString على العلاقات المرتبطة فيسبب استدعاءات غير متوقعة.

هناك خطأ آخر يكرره كثيرون: استخدام save للتحديث وكأنها تعمل دائمًا كما يتخيلون. في JPA، الكيان managed داخل persistence context يختلف عن الكيان detached، وفهم هذا الفارق مهم لتجنب سلوك غير متوقع. كذلك، لا تعتمد على Hibernate لتصحيح تصميمك. إذا كان النموذج غير جيد، فالأداة لن تنقذ الفكرة بالكامل.

متى تستخدم Native Query؟

استخدمها عندما تحتاج:

استعلامًا معقدًا جدًا يصعب التعبير عنه في JPQL.
ميزة محددة بقاعدة بيانات معينة.
أداءً عاليًا يتطلب كتابة SQL مخصص.
وظيفة تقريرية أو تحليلية خاصة.

لكن لا تجعل Native Query الخيار الأول دائمًا، لأنك حينها تعود خطوة إلى الخلف من حيث المرونة وقابلية النقل. القاعدة العامة الجيدة هي: ابدأ بالأبسط والأكثر قياسية، ثم انتقل للأخصّ فقط عندما يكون هناك سبب حقيقي.

تحسين الأداء في JPA

الأداء في JPA ليس سحرًا، بل نتيجة قرارات جيدة. بعض النصائح المهمة:

لا تجلب ما لا تحتاجه.
راقب عدد الاستعلامات.
استخدم pagination للبيانات الكبيرة.
تجنب العلاقات EAGER غير الضرورية.
انتبه إلى N+1.
فكر في projections عند الحاجة.
استخدم indices في قاعدة البيانات على الأعمدة التي تُستخدم في البحث كثيرًا.
لا تفتح معاملات أطول من اللازم.
اختبر SQL الناتج فعليًا.

وأقولها بصراحة: أحيانًا أفضل تحسين لا يكون في الكود، بل في تغيير شكل السؤال نفسه. ربما لا تحتاج إلى جلب كل المستخدمين ثم فلترتهم في Java، بل تحتاج إلى استعلام مناسب منذ البداية. JPA قوية، لكن العقلية الصحيحة أقوى.

JPA في المشاريع الكبيرة

في المشاريع الكبيرة، عادة ما تصبح البنية أكثر وضوحًا:

Entity layer
Repository layer
Service layer
DTO/Mapper layer
Controller/API layer

هذا الفصل ليس ترفًا معماريًا. هو ما يجعل كل طبقة تمارس دورها فقط. عندما يأتي تغيير في واجهة API، لا تريد أن تهدم بنية قاعدة البيانات. وعندما تتغير بنية الجدول، لا تريد أن تنهار كل الطبقات الأخرى. JPA تساعدك في بناء هذه المرونة، بشرط أن تحترم boundaries واضحة.

كذلك من المهم أن تعتمد naming conventions واضحة، وأن تكتب اختبارات repository وservice، وأن لا تعتبر persistence layer جزءًا ثانويًا. هي قلب النظام في كثير من التطبيقات، وأي خطأ فيها يظهر على شكل مشاكل يصعب تعقبها لاحقًا.

لمسة أخيرة: كيف تتعامل مع JPA بثقة؟

أفضل نصيحة أستطيع أن أقدمها لك هي ألا تتعامل مع Spring Data JPA على أنه "مجرد library". هو في الحقيقة أسلوب عمل كامل. كلما بنيت ذهنيًا فكرة أن البيانات ليست مجرد rows بل domain entities لها معنى وعلاقات وسلوك، كلما صار استخدامك له أنضج.

ابدأ بالمفاهيم الأساسية: Entity, Repository, Service, Transaction.
ثم انتقل إلى العلاقات: OneToMany, ManyToOne, ManyToMany.
بعدها تعمق في البحث والتصفية: Derived Queries, @Query, Specifications.
ثم راقب الأداء: Lazy loading, EntityGraph, pagination, projections.
وأخيرًا، لا تنسَ أن كل مشروع حقيقي سيجبرك على الموازنة بين النظافة والسرعة والبساطة.

وفي النهاية، Spring Data JPA ليست فقط وسيلة لكتابة كود أقل، بل وسيلة لكتابة كود أوضح. وهذه قيمة كبيرة جدًا عندما تبدأ المشاريع في النمو، لأن الكود الواضح يبقى صديقك وقت الضغط، بينما الكود المربك يتحول إلى عبء ثقيل مهما كان أنيقًا في أول يوم.

إذا كنت تبني مشروعًا جديدًا في Java، فتعلم Spring Data JPA بجدية. ليس لأن الجميع يستخدمه، بل لأنه عندما يُستخدم بشكل صحيح يمنحك راحة حقيقية في التطوير، ويجعل الوصول إلى البيانات أكثر تنظيمًا، وأقل ضجيجًا، وأكثر احترامًا لعقلك ووقت فريقك.