refactor: 리펙토링 진행중 의존성 gradle은 얇게 유지, 각 모듈에서 처리하고 있는 부분에 대해서 리펙토링

This commit is contained in:
donghyeon-ka
2026-09-23 17:27:09 +09:00
parent 60b6a319e7
commit 9da00eb782
2485 changed files with 56091 additions and 23550 deletions
+64
View File
@@ -0,0 +1,64 @@
# JPA batch write configuration
`HibernateJpaBatchExecutor` is an advanced opt-in. The template does not enable Hibernate batch
write settings globally because statistics and statement reordering add runtime cost even in
applications that never perform bulk writes.
## What the executor owns
A `JpaBatchProfile` owns the JDBC batch size for one batch run. Before the first item is written,
the executor applies `profile.jdbcBatchSize()` to the current Hibernate `Session`. The previous
Session value is restored in `finally`, including failed runs.
The executor does **not** open a transaction. The application service must enter a
`TransactionPort.inWrite(...)` boundary first.
## What the application must configure
If a profile requests insert or update ordering, the matching Hibernate setting must already be
enabled on the SessionFactory:
```yaml
spring:
jpa:
properties:
hibernate:
order_inserts: true
order_updates: true
generate_statistics: true
```
`hibernate.generate_statistics=true` is required because `BatchExecutionResult` reports measured
flush and prepared-statement deltas. A disabled statistics registry would turn those values into
convincing zeros.
The `HibernateStatisticsCollector` must also receive an instrumented `JdbcBatchCounter`.
`HibernateStatisticsCollector.of(sessionFactory)` is intentionally insufficient for this executor:
Hibernate statistics do not expose actual JDBC batch executions.
`hibernate.default_batch_fetch_size` is unrelated to this write executor. It affects association
fetching and belongs to query/fetch tuning instead.
## Entity identifier constraint
When `JpaBatchProfile.batchingRequired()` is true, an entity using
`GenerationType.IDENTITY` is rejected by `HibernateBatchConfigurationGuard`. Hibernate must issue
each INSERT immediately to obtain the generated identifier, so JDBC insert batching cannot satisfy
that profile.
Prefer a sequence-based identifier when a workload requires insert batching. Keep the sequence
allocation size aligned with the database migration.
## Failure behavior
Configuration is checked before the persister receives the first item:
- missing `hibernate.order_inserts=true` when the profile requests insert ordering: fail;
- missing `hibernate.order_updates=true` when the profile requests update ordering: fail;
- disabled Hibernate statistics: fail;
- missing JDBC batch instrumentation: fail;
- no caller-owned transaction: fail.
These failures are deliberate. A batch API that silently degrades to one statement per row produces
correct data but false performance evidence, which is harder to detect than a startup or invocation
failure.