Spring Data JPA و تراکنش‌هاSpring Data JPA & Transactions

بیا رُک باشیم: بیشترِ ما با Spring Data شروع می‌کنیم، یک findById صدا می‌زنیم، جواب می‌گیریم و خوشحالیم — تا روزی که در production چیزی می‌ترکد. یک صفحه که باید ۱ کوئری بزند، ۵۰۱ کوئری می‌زند. یک save() که ظاهراً کار کرده ولی هیچ‌چیز ذخیره نشده. یک آپدیت که با IOException باید برمی‌گشت، ولی commit شد و پول از حساب کم شد. تمام این‌ها ریشه در یک مشت مفهوم دارد که اگر یک‌بار درست بفهمی، دیگر هیچ‌وقت غافلگیر نمی‌شوی.

این فصل دقیقاً همان یک‌بار است. قرار نیست چیزی را حفظ کنی؛ قرار است بفهمی چرا.

بخش ۰ — سه کلمه که باید از همین حالا بلد باشی

قبل از هر چیز، سه واژه را باز کنیم تا بعداً سرد و بدون توضیح پرتشان نکنم:

• Entity: یک کلاس جاوا که به یک جدولِ دیتابیس نگاشت شده. مثل User که به جدول users وصل است. هر شیءِ User معادلِ یک ردیف است.
• EntityManager: کارمندی که واقعاً با دیتابیس حرف می‌زند. تو به او می‌گویی «این کاربر را ذخیره کن» و او SQL می‌نویسد. در Spring معمولاً مستقیم با آن کار نمی‌کنی؛ Spring Data آن را از تو پنهان می‌کند.
• Transaction (تراکنش): یک «همه یا هیچ». مجموعه‌ای از تغییرات که یا همه با هم موفق می‌شوند (commit) یا همه با هم لغو می‌شوند (rollback). مثل انتقال پول بین دو حساب: یا هر دو طرف اتفاق می‌افتد یا هیچ‌کدام.

حالا با خیال راحت جلو برویم.

مدل ذهنی: واقعاً چه چیزی اجرا می‌شود؟

وقتی متدی از یک repository در Spring Data صدا می‌زنی، سه لایه با هم کار می‌کنند:

1. Spring Data JPA — پیاده‌سازیِ repository را برایت تولید می‌کند (derived query، ‏@Query‏، صفحه‌بندی). یک لایه‌ی نازک روی EntityManager است. خودش هیچ SQLای اجرا نمی‌کند.
2. JPA — خودِ مشخصات/استاندارد است (annotationها، ‏EntityManager‏، JPQL). فقط interface و قرارداد است، نه کدِ اجراشونده.
3. Hibernate — provider پیش‌فرضِ JPA که کارِ اصلی را انجام می‌دهد: تولید SQL، مدیریت persistence context، ‏dirty checking و مدیریت connection/تراکنش.

حالا مهم‌ترین جمله‌ی کل این فصل: مهم‌ترین مفهومی که باید همیشه در ذهن داشته باشی persistence context است — که همان first-level cache یا به‌اختصار L1 است.

تمام رفتار JPA — caching، ‏dirty checking، ‏lazy loading، ‏LazyInitializationException‏، تضمین‌های هویت (identity) — از درکِ همین یک شیء بیرون می‌آید. اگر این تصویر را در ذهن داشته باشی، بقیه‌ی فصل تقریباً بدیهی می‌شود:

مرز تراکنش  ──────────────────────────────────────────────
  ┌──────────────── PersistenceContext (L1 cache) ─────────┐
  │  { (User,1) -> userEntity,  (Order,7) -> orderEntity }  │
  │   • identity map: به ازای هر PK دقیقاً یک instance      │
  │   • snapshot از حالت لود شده برای dirty checking         │
  │   • صف اکشن‌ها (INSERT/UPDATE/DELETE) که به DB flush می‌شود│
  └─────────────────────────────────────────────────────────┘

سه چیز روی این میز هست، هر سه را در ادامه لمس می‌کنیم: یک identity map (به‌ازای هر کلیدِ اصلی، دقیقاً یک شیء)، یک snapshot (عکسِ لحظه‌ی لود، برای فهمیدنِ اینکه چه چیزی عوض شده)، و یک صفِ اکشن (INSERT/UPDATE/DELETEهایی که هنوز به دیتابیس نرفته‌اند).

چرخه‌ی حیاتِ entity: چهار حالتِ زندگی

هر instance از یک entity همیشه دقیقاً در یکی از این چهار حالت نسبت به persistence context قرار دارد:

بیایید همین چهار حالت را در کد ببینیم — دنبال کن که هر خط، شیء را از یک حالت به حالتِ بعدی می‌برد:

User u = new User("Ada");        // TRANSIENT
em.persist(u);                   // MANAGED (INSERT در صف، شاید هنوز اجرا نشده)
tx.commit();                     // flush -> INSERT اجرا می‌شود
// context بسته می‌شود -> u حالا DETACHED است
u.setName("Ada Lovelace");       // بی‌اثر روی DB: detached است، کسی نظارت نمی‌کند
User merged = em.merge(u);       // یک کپیِ MANAGED برمی‌گرداند؛ خودِ 'u' هنوز detached
em.remove(merged);               // REMOVED، ‏DELETE در صف

توجه کن به خطِ em.persist(u): بلافاصله INSERT اجرا نمی‌شود! فقط در صف می‌رود. این نکته‌ی ظریفی است که خیلی‌ها را غافلگیر می‌کند و در بخشِ flush به آن برمی‌گردیم.

User merged = em.merge(u);   // این managed است
u.setName("...");            // این هیچ اثری ندارد! u هنوز detached است
merged.setName("...");       // باید روی merged کار کنی

Dirty checking و flush: چرا بدونِ save() هم دیتابیس عوض می‌شود؟

اینجا اولین جادوی بزرگِ JPA است که تازه‌کارها را شگفت‌زده می‌کند: تو در JPA هرگز update() صدا نمی‌زنی.

این مقایسه‌ی خودکار را dirty checking می‌گویند (یعنی «آیا کثیف/دست‌خورده شده؟»). ببین چقدر تمیز است — نه save، نه update، هیچ:

@Transactional
public void renameUser(long id) {
    User u = repo.findById(id).orElseThrow(); // MANAGED، snapshot گرفته می‌شود
    u.setName("new name");                     // نیازی به save() نیست
}   // در commit -> flush -> UPDATE users SET name=? WHERE id=?

خب، این کلمه‌ی flush که مدام می‌گویم چیست؟ Flush یعنی همگام‌سازیِ context با دیتابیس؛ یعنی اجرای همه‌ی SQLهایی که در صف بودند. اما — و این مهم است — flush یعنی commit نیست. flush فقط دستورها را می‌فرستد؛ commit است که آن‌ها را دائمی می‌کند. یک flush می‌تواند بعداً rollback شود.

حالتِ پیش‌فرض FlushModeType.AUTO در این دو موقعیت به‌طور خودکار flush می‌کند:

• قبل از commitِ تراکنش،
• قبل از یک کوئریِ JPQL/HQL/Criteria که می‌تواند تحتِ تأثیرِ تغییراتِ معلق باشد (تا کوئری، نوشته‌های خودت را هم ببیند).

مشکل N+1: قاتلِ خاموشِ کارایی

قاتلِ کلاسیکِ کارایی همین است. اول N والد را لود می‌کنی، بعد یک association از نوعِ lazy را لمس می‌کنی که به‌ازای هر والد یک کوئریِ اضافه می‌زند:

List<Order> orders = orderRepo.findAll();     // ۱ کوئری
for (Order o : orders) {
    o.getCustomer().getName();                // N کوئری، یکی به ازای هر order
}                                             // مجموع: N+1

این با collectionهای @OneToMany هم رخ می‌دهد و — نکته‌ی مهم — حتی با FetchType.EAGER هم حل نمی‌شود. EAGER دسته‌ای (batch) لود نمی‌کند؛ فقط N+1 را زودتر جلو می‌اندازد. راه‌حل‌ها را تقریباً به‌ترتیبِ اولویت ببینیم:

۱. Fetch join (در JPQL): به دیتابیس بگو همه را در یک کوئریِ JOINشده بیاورد.

@Query("select o from Order o join fetch o.customer")
List<Order> findAllWithCustomer();

یک کوئری، همه‌چیز JOIN شده. عیبش: نمی‌توانی دو collection را در یک کوئری fetch-join کنی (ضربِ دکارتی می‌شود) و صفحه‌بندیِ سطحِ دیتابیس را هم می‌شکند (پایین‌تر مفصل می‌گوییم).

۲. ‏@EntityGraph — راهِ اعلانی (declarative)؛ با derived query و صفحه‌بندی هم سازگار است:

@EntityGraph(attributePaths = {"customer", "items"})
List<Order> findByStatus(OrderStatus status);

۳. Batch fetching — به‌جای N لودِ lazy، تعدادِ ceil(N/size) کوئری با یک IN می‌زند. یعنی به‌جای ۱۰۰ سفرِ تک‌نفره، چند اتوبوسِ ۵۰نفره می‌فرستد:

@BatchSize(size = 50)               // روی entity یا collection
@OneToMany(mappedBy = "order")
private List<Item> items;

# پیش‌فرض سراسری
spring.jpa.properties.hibernate.default_batch_fetch_size=50

برای collectionها این گزینه‌ی عملیِ پیش‌فرض است، چون از انفجارِ دکارتی جلوگیری می‌کند.

Lazy در برابر eager و LazyInitializationException

پیش‌فرض‌هایی که باید مثلِ اسمِ خودت حفظ باشی:

• @ManyToOne، ‏@OneToOne → EAGER
• @OneToMany، ‏@ManyToMany → LAZY

بهترین رویه: همه‌چیز را LAZY کن (@ManyToOne(fetch = LAZY)) و به‌ازای هر use case صریحاً fetch کن. چرا؟ چون EAGER یک تصمیمِ سراسری است که در mapping پخته می‌شود؛ نمی‌توانی آن را per-query خاموش کنی و همه‌جا بی‌سروصدا join و N+1 می‌سازد.

اما lazy یک دامِ معروف دارد. LazyInitializationException وقتی رخ می‌دهد که یک proxyِ lazy را بعد از بسته‌شدنِ persistence context لمس کنی — یعنی وقتی سراغِ غذا می‌روی که آشپزخانه دیگر تعطیل شده:

@Transactional
public Order load(long id){ return repo.findById(id).orElseThrow(); }
// در controller، تراکنش قبلاً commit شده:
order.getItems().size();   // LazyInitializationException: no Session

راه‌حل‌ها، از درست‌ترین به بدترین:

• آنچه لازم داری را داخلِ تراکنش fetch کن (fetch join یا entity graph). درست.
• یک DTO برگردان که داخلِ تراکنش ساخته شده، نه خودِ entity. بهترین گزینه برای لایه‌ی web.
• ‏Open Session In View (OSIV) — ‏Spring Boot آن را به‌طور پیش‌فرض فعال می‌کند (spring.jpa.open-in-view=true). این context را برای کلِ درخواستِ HTTP باز نگه می‌دارد تا lazy loadها در view «خودکار کار کنند». اما N+1ها را پنهان می‌کند، یک connection را برای کلِ مدتِ درخواست نگه می‌دارد، و در سرویس‌ها به‌شدت anti-pattern محسوب می‌شود. خاموشش کن و صریح fetch کن.

معناشناسیِ @Transactional: همه‌چیز از یک پروکسی شروع می‌شود

فنی‌اش: @Transactional با یک proxyِ Spring AOP پیاده‌سازی می‌شود. پروکسی قبل از متدت تراکنش را باز می‌کند، بعد از returnِ عادی commit و در صورتِ exception، ‏rollback می‌کند. همین ماهیتِ پروکسی، منشأِ تمامِ gotchaهای زیر است.

دامِ self-invocation (‏gotcha شماره ۱)

@Service
public class BillingService {
    public void run() {
        charge();               // ← THIS را صدا می‌زند، proxy را دور می‌زند
    }
    @Transactional
    public void charge() { ... } // وقتی از run() صدا زده شود transactional نیست
}

annotation فقط وقتی کار می‌کند که فراخوانی از میانِ پروکسی عبور کند (یعنی از یک beanِ دیگر بیاید). یک this.charge() داخلی، همان درِ مخفی است: شیءِ خام را صدا می‌زند، پس @Transactional (و به همین دلیل @Async و @Cacheable هم) بی‌صدا نادیده گرفته می‌شود.

راه‌حل‌ها: متد را به دو beanِ جدا تقسیم کن، یا پروکسی را به خودِ کلاس تزریق کن (self-injection)، یا از AopContext.currentProxy() استفاده کن.

قوانینِ rollback (‏gotcha شماره ۲)

اینجا یکی از خطرناک‌ترین رفتارهای پیش‌فرض است: Spring به‌طور پیش‌فرض فقط روی RuntimeException و Error ‏rollback می‌کند. یعنی exceptionهای checked باعث rollback نمی‌شوند و تراکنش با خیالِ راحت commit می‌شود:

@Transactional
public void doIt() throws IOException {
    repo.save(x);
    throw new IOException("boom");   // save را COMMIT می‌کند! چون checked است
}

تصور کن این x یک تراکنشِ مالی باشد و آن IOException یعنی «سرور نتوانست رسید بفرستد» — با رفتارِ پیش‌فرض، پول کم شده ولی خطا داده‌ای. برای اصلاح، صریح بگو:

@Transactional(rollbackFor = Exception.class)

Propagation (انتشار): وقتی تراکنش تودرتو می‌شود

Propagation یعنی: وقتی یک متدِ تراکنشی، متدِ تراکنشیِ دیگری را صدا می‌زند، رفتارشان چطور با هم ترکیب شود؟ آیا در یک تراکنش می‌مانند یا هرکدام مالِ خودشان؟

Isolation (انزوا)

Isolation یعنی: چقدر تراکنش‌های هم‌زمان از هم «بی‌خبر» باشند. به سطحِ isolationِ دیتابیس نگاشت می‌شود: READ_COMMITTED، ‏REPEATABLE_READ، ‏SERIALIZABLE، ‏READ_UNCOMMITTED.

نکاتِ نسخه‌ای که خوب است بدانی:

• Postgres پیش‌فرض READ_COMMITTED است و نکته اینکه READ_UNCOMMITTED را اصلاً پیاده‌سازی نمی‌کند (اگر بخواهی، مثلِ READ_COMMITTED رفتار می‌کند).
• MySQL/InnoDB پیش‌فرض REPEATABLE_READ است.

سطحِ isolationِ بالاتر، ناهنجاری‌های بیشتری را جلوگیری می‌کند — dirty read (خواندنِ چیزی که هنوز commit نشده)، non-repeatable read (دو خواندنِ مختلف در یک تراکنش) و phantom read (ظاهرشدنِ ردیف‌های جدید) — اما به قیمتِ قفل‌گذاری و retryِ بیشتر.

readOnly

readOnly = true یک hint (اشاره) است، نه یک قانونِ سفت‌وسخت: حالتِ flush در Hibernate را MANUAL می‌کند (بدونِ dirty checking) و connectionِ سطحِ JDBC را read-only علامت می‌زند (درایورها ممکن است بر اساسِ آن به یک replica مسیردهی یا بهینه‌سازی کنند). ولی این خودش به‌تنهایی یک دیتابیسِ فقط‌خواندنی را تحمیل نمی‌کند — اگر خیلی جدی SQLِ نوشتاری بزنی، ممکن است هنوز اجرا شود.

قفلِ خوش‌بینانه در برابر بدبینانه

قفلِ خوش‌بینانه (@Version): هیچ قفلی روی دیتابیس نمی‌گذارد؛ تعارض‌ها را فقط هنگامِ نوشتن، با کمکِ یک ستونِ version تشخیص می‌دهد.

@Entity
class Account {
    @Id Long id;
    @Version long version;      // در هر UPDATE افزایش می‌یابد
    long balance;
}
// UPDATE account SET balance=?, version=? WHERE id=? AND version=?
// اگر ۰ ردیف آپدیت شد -> OptimisticLockException (یکی دیگر زودتر commit کرد)

جادویش در WHERE ... AND version=? است: اگر بینِ لود و نوشتنِ تو، کسِ دیگری این ردیف را عوض کرده باشد، version عوض شده و شرطِ WHERE هیچ ردیفی را پیدا نمی‌کند → ۰ ردیف آپدیت → OptimisticLockException. بازنده retry می‌کند. برای تعارضِ کم و throughputِ بالا بهترین است. @Version از انواعِ int/long/short/Timestamp پشتیبانی می‌کند.

قفلِ بدبینانه (قفلِ واقعیِ دیتابیس با SELECT ... FOR UPDATE): دسترسی را از همان ابتدا سریالایز می‌کند، یعنی بقیه پشتِ در منتظر می‌مانند.

@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("select a from Account a where a.id = :id")
Account findForUpdate(@Param("id") Long id);

• PESSIMISTIC_READ → قفلِ اشتراکی (shared)، ‏PESSIMISTIC_WRITE → قفلِ انحصاری (FOR UPDATE).
• از PESSIMISTIC_FORCE_INCREMENT برای افزایشِ @Version حتی هنگامِ خواندن استفاده کن.
• حتماً یک timeout بگذار تا از انتظارِ نامحدود و deadlock جلوگیری کنی:

@QueryHints(@QueryHint(name = "jakarta.persistence.lock.timeout", value = "3000"))

Postgres همچنین از FOR UPDATE NOWAIT و SKIP LOCKED پشتیبانی می‌کند (که برای بارهای صف‌مانند فوق‌العاده‌اند — چند worker می‌توانند بدونِ انتظار، ردیف‌های مختلف را بردارند).

JPQL در برابر native در برابر Criteria

سه راه برای نوشتنِ کوئری داری. تفاوت‌شان را در یک نگاه ببین:

توضیح واژه‌ها: قابل‌حمل (portable) یعنی اگر دیتابیس را عوض کردی همچنان کار می‌کند؛ type-safe یعنی کامپایلر خطایت را می‌گیرد نه اینکه سرِ اجرا بترکد؛ داینامیک یعنی چقدر راحت می‌توانی کوئری را بر اساسِ شرایط (مثلاً فیلترهایی که ممکن است باشند یا نباشند) در لحظه بسازی.

// JPQL — به نام entity/فیلد توجه کن نه نام جدول/ستون
@Query("select u from User u where u.email = :email")
Optional<User> byEmail(@Param("email") String email);

// Native — nativeQuery، نام واقعی ستون‌ها
@Query(value = "SELECT * FROM users WHERE email = :email", nativeQuery = true)
Optional<User> byEmailNative(@Param("email") String email);

// کوئری تغییردهنده — باید annotate شود و context پاک شود
@Modifying(clearAutomatically = true, flushAutomatically = true)
@Query("update User u set u.active = false where u.lastLogin < :cutoff")
int deactivateStale(@Param("cutoff") Instant cutoff);

دقت کن که JPQL روی User و u.email کار می‌کند (اسمِ کلاس و فیلد)، ولی native روی users و ستونِ واقعی. این تفاوت را خیلی‌ها اشتباه می‌کنند.

دام‌های صفحه‌بندی با join

تله — ‏join fetch + ‏Pageable روی یک collection. وقتی fetch join روی collection ردیف‌های تکراری تولید می‌کند، ‏Hibernate نمی‌تواند LIMIT/OFFSET را در SQL اعمال کند، پس کلِ نتیجه را می‌آورد و صفحه‌بندی را در حافظه انجام می‌دهد. این هشدار را در log می‌بینی: firstResult/maxResults specified with collection fetch; applying in memory. روی یک جدولِ بزرگ باعثِ OOM (پرشدنِ حافظه) می‌شود.

راه‌حل‌ها:

• برای associationهای @ToOne از @EntityGraph روی یک متدِ derivedِ صفحه‌بندی‌شده استفاده کن (در SQL درست صفحه‌بندی می‌شود).
• برای collectionها رویکردِ دوکوئری‌ای: اول IDها را صفحه‌بندی کن، بعد collection را برای همان IDها fetch کن.

// ۱) صفحه‌بندیِ IDهای root (‏LIMIT کار می‌کند، بدون join fetch)
Page<Long> ids = repo.findIdsBy(status, pageable);
// ۲) fetch گراف کامل فقط برای همان IDها
List<Order> orders = repo.findWithItemsByIdIn(ids.getContent());

• یا default_batch_fetch_size را تنظیم کن تا collection بعد از یک کوئریِ rootِ تمیزِ صفحه‌بندی‌شده، با کوئری‌های INِ دسته‌ای لود شود.

WHERE id > :lastId ORDER BY id LIMIT n

چک‌لیستِ بهترین رویه‌ها

اگر فقط یک تصویر از این فصل قاب بگیری، این باشد:

• همه‌ی associationها را LAZY کن؛ به‌ازای هر کوئری صریحاً با entity graph / fetch join لود کن.
• OSIV را خاموش کن (spring.jpa.open-in-view=false) و از سرویس‌ها DTO برگردان.
• ‏@Transactional را روی لایه‌ی service (متدهای public) بگذار، نه repository و نه controller.
• به aggregateهایی که ممکن است هم‌زمان آپدیت شوند @Version اضافه کن.
• وقتی checked exceptionای می‌اندازی که می‌خواهی rollback شود، ‏rollbackFor = Exception.class بگذار.
• ‏default_batch_fetch_size را تنظیم کن؛ برای write batching مقادیرِ hibernate.jdbc.batch_size بعلاوه‌ی order_inserts/order_updates را فعال کن.
• در محیطِ dev لاگِ SQL را روشن کن (show-sql + ‏format_sql)، و برای گرفتنِ زودهنگامِ N+1 از LOG_QUERIES_SLOWER_THAN_MS یا یک datasource-proxy استفاده کن.
• هرگز کارِ کند (مثلِ فراخوانیِ HTTP) را داخلِ تراکنش نگذار — کلِ آن مدت یک connectionِ دیتابیس را نگه می‌داری.

سؤالات مصاحبه

حالا وقتِ آن است که بفهمی همه‌ی این‌ها در اتاقِ مصاحبه چطور پرسیده می‌شوند. هر سؤال را جوری بخوان که انگار خودت باید جواب بدهی.

@Transactional
public void run(){
   Account a = repo.findById(1L).get();
   Account b = repo.findById(1L).get();
   System.out.println(a == b);
}

@Transactional
public Order get(long id){ return repo.findById(id).orElseThrow(); }

// جای دیگر، بدون تراکنش:
service.get(1).getItems().forEach(...);   // items از نوع LAZY است