Kotlin on 0AndWild_log

Choosing a Spring Batch Reader

Fri, 24 Jul 2026 04:43:44 +0900

TL;DR

When choosing a Spring Batch Reader, it is tempting to assume that large datasets always call for a Paging Reader.

In practice, which query gets executed repeatedly mattered more than the size of the data alone. A Paging Reader fits a simple scan in stable key order. A Cursor Reader may be a better fit when consuming the result of one expensive aggregate query sequentially.

I ran into this distinction while building a ranking batch. It read a period such as 30 days from product_metric_daily, aggregated with GROUP BY product_id, and built weekly and monthly ranking MVs. With paging, each page could require another scan and aggregation of the same period. I chose JdbcCursorItemReader to open the aggregate query once and consume its result through a cursor.

That comes with costs: a long-held connection, JDBC driver fetch behavior, and timeout settings. The right question is where the bottleneck lies, rather than simply whether the dataset is large.

Why choosing a Reader was harder than expected

A Spring Batch Step looks fairly simple at first.

Reader -> Processor -> Writer

The Reader reads, the Processor transforms, and the Writer stores the results.

But the Reader influences more than I expected: query execution, memory usage, restart behavior, connection duration, and processing speed.

My first thought was to use paging for a large dataset. Reading smaller pages seems safer because it avoids loading everything into memory at once. That is reasonable in many cases, but not every batch query looks like SELECT * FROM table ORDER BY id.

The ranking batch used a query like this:

SELECT
 product_id,
 SUM(view_count) AS view_count,
 SUM(like_count) AS like_count,
 SUM(sales_amount) AS sales_amount
FROM product_metric_daily
WHERE metric_date >= ?
 AND metric_date < ?
GROUP BY product_id
ORDER BY product_id;

It aggregates 30 days of daily metrics per product, calculates scores, and writes a monthly ranking MV.

Before the Reader can consume any rows, the database has to scan the period and produce the GROUP BY result. A paged approach can cause that work to be repeated for each page.

For this task, the number of times the expensive query runs mattered more than the number of rows read per call.

How I evaluate Spring Batch Readers

Even for database input alone, Spring Batch offers JdbcCursorItemReader, JdbcPagingItemReader, JpaPagingItemReader, and RepositoryItemReader.

The reference documentation describes JdbcCursorItemReader as reading a JDBC ResultSet sequentially through a cursor, while JdbcPagingItemReader uses a PagingQueryProvider to generate page queries.

Spring Batch Reference — Database Readers

Understanding the behavior matters more than remembering the names. These are the questions I now ask first:

Is the source query a simple read or an aggregate query?
Is there a stable sort key?
Is repeated execution of the query affordable?
Can the batch hold a database connection for a long time?
How important is managing a restart position after failure?
Do we need a JPA persistence context, or is JDBC row mapping enough?

Cursor Reader

A Cursor Reader opens a query and reads its results sequentially through a cursor. For JDBC, that means using JdbcCursorItemReader.

@Bean
@StepScope
fun rankingAggregateReader(
 dataSource: DataSource,
 @Value("#{jobParameters['baseDate']}") baseDate: String,
): JdbcCursorItemReader<ProductMetricAggregate> {
 return JdbcCursorItemReaderBuilder<ProductMetricAggregate>()
 .name("rankingAggregateReader")
 .dataSource(dataSource)
 .sql(
 """
 SELECT
 product_id,
 SUM(view_count) AS view_count,
 SUM(like_count) AS like_count,
 SUM(sales_amount) AS sales_amount
 FROM product_metric_daily
 WHERE metric_date >= ?
 AND metric_date < ?
 GROUP BY product_id
 ORDER BY product_id
 """.trimIndent(),
 )
 .preparedStatementSetter { ps ->
 ps.setDate(1, Date.valueOf(sourceStart(baseDate)))
 ps.setDate(2, Date.valueOf(sourceEnd(baseDate)))
 }
 .rowMapper { rs, _ ->
 ProductMetricAggregate(
 productId = rs.getLong("product_id"),
 viewCount = rs.getLong("view_count"),
 likeCount = rs.getLong("like_count"),
 salesAmount = rs.getLong("sales_amount"),
 )
 }
 .fetchSize(1000)
 .build()
}

Its main advantage here is executing the query once. For an expensive GROUP BY, that distinction matters: the database scans the period and produces the per-product aggregates, and the application consumes that result sequentially.

fetchSize is a hint about the number of rows to fetch at a time. It is different from chunk size.

fetchSize: the fetch batch size requested from the JDBC driver
chunkSize: the number of items Spring Batch processes and commits per transaction

fetchSize concerns database communication and ResultSet consumption. chunkSize concerns the batch transaction boundary.

A Cursor Reader fits when:

We want to process one query result sequentially.
The source query performs expensive aggregation.
We want to avoid repeating the aggregation for every page.
We want to consume results as a stream without loading them all into the JVM.
Simple row mapping is sufficient.

The cost is keeping a database connection open while the cursor is in use. Long jobs require attention to database and network timeouts, connection pool settings, and the JDBC driver’s fetch behavior.

Restarting also needs thought. Even if Spring Batch saves its state, resuming correctly partway through a cursor result depends on a stable query and ordering. For a long-running job, the restart position deserves explicit design.

Paging Reader

A Paging Reader reads data in pages. The JDBC implementation is JdbcPagingItemReader.

@Bean
@StepScope
fun orderPagingReader(
 dataSource: DataSource,
): JdbcPagingItemReader<OrderRow> {
 val sortKeys = mapOf("order_id" to Order.ASCENDING)

 return JdbcPagingItemReaderBuilder<OrderRow>()
 .name("orderPagingReader")
 .dataSource(dataSource)
 .selectClause("SELECT order_id, user_id, total_amount, status")
 .fromClause("FROM orders")
 .whereClause("WHERE status = :status")
 .parameterValues(mapOf("status" to "READY"))
 .sortKeys(sortKeys)
 .pageSize(1000)
 .rowMapper { rs, _ ->
 OrderRow(
 orderId = rs.getLong("order_id"),
 userId = rs.getLong("user_id"),
 totalAmount = rs.getLong("total_amount"),
 status = rs.getString("status"),
 )
 }
 .build()
}

It executes page queries repeatedly, so a stable sort key is important. A unique, increasing key such as order_id is well suited to this approach.

A Paging Reader fits when:

The source table can be read in stable key order.
The query is relatively simple.
Repeated page queries have an acceptable cost.
We don’t want to hold one connection open for the entire read.
Restart behavior and page-oriented processing matter.

The main risk is repeating expensive work for every page. Consider dividing an aggregate query like this into pages:

SELECT
 product_id,
 SUM(view_count) AS view_count,
 SUM(like_count) AS like_count,
 SUM(sales_amount) AS sales_amount
FROM product_metric_daily
WHERE metric_date >= :startDate
 AND metric_date < :endDate
GROUP BY product_id
ORDER BY product_id
LIMIT 1000 OFFSET 0;

The next page changes only the offset.

...
ORDER BY product_id
LIMIT 1000 OFFSET 1000;

The application appears to read just 1,000 rows at a time. The database may still need to scan the same period, build the grouped result again, and skip rows up to the offset on every query.

Actual cost depends on the optimizer’s execution plan. Paging alone doesn’t guarantee efficiency; the query shape is what matters.

Repository and JPA Readers

RepositoryItemReader and JpaPagingItemReader are also common choices. They make it convenient to reuse repository methods or JPA queries. If a Spring Data repository already exists and the job reads entities with simple conditions, implementation can be quick.

JPA hasn’t always been the most convenient choice for my batch work, though. Reading entities brings the persistence context into the picture. With many rows, context clearing and dirty checking costs need attention. When the job simply reads data and writes it to another table, avoiding the entity lifecycle can make the flow clearer.

JDBC row mapping is particularly suitable for aggregate results that aren’t entities in the first place.

product_metric_daily rows
 ↓ group by
ProductMetricAggregate
 ↓ calculate score
ProductRankingScore
 ↓ batch upsert
mv_product_rank_weekly / mv_product_rank_monthly

DTO-like rows fit this flow more naturally than JPA entities, so I used JDBC-based Readers and Writers for the ranking batch.

Why I chose a Cursor Reader for the ranking batch

The requirements were:

Store daily metrics in product_metric_daily.
Sum the previous week’s seven days for weekly rankings.
Sum the entire previous month for monthly rankings.
Apply current weights to each product’s aggregates to calculate a score.
Upsert the results into an MV table.
Publish a publication generation after the Job succeeds.

Paging initially seemed safer for large-scale processing. Looking at the query changed my mind.

The expensive part was scanning the period in product_metric_daily and running GROUP BY product_id. One million products over 30 days can mean 30 million daily metric rows. I wanted to avoid repeatedly aggregating that range for each page.

I chose this structure:

JdbcCursorItemReader
 - Execute the aggregate query once for the period range
 - Consume ProductMetricAggregate sequentially using fetchSize

ItemProcessor
 - Apply weights to view, like, and sales metrics
 - Dampen sales with ln(1 + salesAmount)

JdbcBatchItemWriter
 - Upsert into mv_product_rank_weekly or mv_product_rank_monthly

This is a choice for the current query shape, not a universal answer. If the source had been a simple orders table read by order_id, I would probably have chosen a Paging Reader. Here, the job consumes the result of one large period aggregation, so a Cursor Reader felt more appropriate.

Selection criteria at a glance

Situation	Reader to consider first	Reason
Process simple table rows in ID order	`JdbcPagingItemReader`	Stable sort key and inexpensive page queries
Consume an expensive aggregate result sequentially	`JdbcCursorItemReader`	Avoid repeated execution of the aggregate query
Reuse a Spring Data repository directly	`RepositoryItemReader`	Quick to implement, but query and paging costs still need checking
Processing requires the JPA entity lifecycle	`JpaPagingItemReader`	Suitable for entity-based processing
Process projections or aggregates rather than entities	JDBC Reader	Simple row mapping without persistence context overhead

I wouldn’t memorize a rule such as “large dataset means Reader A.” Paging may be a good fit for a large, simple key scan. A cursor may be simpler even for fewer rows when the query itself is expensive.

What to check with a Cursor Reader

1. Is fetchSize actually taking effect?

fetchSize is a JDBC driver hint. Drivers don’t all handle it the same way.

For MySQL, Connector/J settings affect fetching. Server-side cursors and streaming results can require different options.

Setting .fetchSize(1000) isn’t the end of the work. Check actual memory usage to make sure the result isn’t being loaded all at once.

2. Can the job hold a connection for that long?

A Cursor Reader keeps its ResultSet and connection open while reading.

Without a separate batch datasource or pool, it can compete with API traffic for connections. Long jobs need appropriate query timeouts, socket timeouts, pool sizes, and database idle timeouts.

3. Is the ordering stable?

Stable ordering matters even with a cursor.

This batch uses GROUP BY product_id ORDER BY product_id, giving a consistent product order for the same source range.

The final ranking is still score-based. The Reader only needs to process aggregates sequentially; the MV query later retrieves the Top 100 using ranking_score DESC, product_id ASC.

4. Is rerunning after failure safe?

A Job can fail regardless of the Reader type.

For this batch, rerunning with the same baseDate deletes the existing MV rows and upserts a rebuilt result. I chose to rebuild the result for that date instead of resuming midway.

The rebuild cost grows with the data, but the consistency model is easy to explain. If execution becomes too slow, partitioning or keyset-based range processing would be worth revisiting.

What to check with a Paging Reader

1. Is the sort key unique and stable?

Paging depends on a reliable order. Duplicate sort values or data changes during processing can lead to missing or repeated rows across pages.

Where possible, use a unique, immutable key such as id.

2. Is each repeated page query inexpensive?

Simple filtered reads may be fine. Queries with expensive joins, grouping, or sorting need closer inspection.

Use EXPLAIN for later-page conditions as well as the first page.

3. Does the implementation use offset or keyset paging?

Many paging implementations use offsets. As offsets grow, skipping earlier rows can become increasingly expensive. For large tables, keyset paging such as id > lastSeenId can offer more stable performance.

Rather than forcing every job into a built-in Reader, a custom Reader or a partitioner combined with range conditions may sometimes be clearer.

4. Are pageSize and chunkSize being confused?

A Paging Reader’s pageSize and a Step’s chunkSize are different settings.

pageSize: the number of items the Reader retrieves in one page query
chunkSize: the number of items processed before each transaction commit

They don’t have to match. Large differences can affect memory usage or query frequency in unexpected ways, though, so choose them deliberately.

The approach I use now

I start with the source query: is it a simple row scan, join-heavy, grouped, or expensive to sort? That already tells me a lot about whether a Cursor or Paging Reader is likely to fit.

Next, I consider restart strategy. Must the job resume midway, or can it delete and rebuild the result for the same reference date? If consistency matters more than rerun cost, a clean rebuild can be simpler.

Finally, I consider operational cost. A cursor holds a connection; paging repeats queries. The question is which cost the current system can handle better.

For this ranking batch, repeated query work looked more expensive, so I chose a Cursor Reader. That doesn’t make it the default for every batch. Settlement data that can be read reliably in ID ranges, for example, might fit a Paging Reader better. I want to understand what work the Reader asks the database to do.

Closing thoughts

Choosing a Spring Batch Reader is a design decision. I started with “large dataset means paging,” but query shape turned out to be more useful. Expensive GROUP BY or ORDER BY queries can end up repeating the same work when split into pages.

A Cursor Reader suits sequential consumption of one aggregate result, at the cost of connection duration and driver configuration. A Paging Reader suits simple reads over stable keys, at the cost of repeated queries and, depending on the implementation, offset handling.

My choice fits the requirement to aggregate product_metric_daily across periods and produce ranking MVs. If the data and execution time grow, I will need to reconsider partitioning, keyset paging, or pre-aggregation.

The question I want to keep asking is: with this Reader, what work will the database do, and how many times will it do it?

Handling Order Surges: Designing a Redis Waiting Queue

Fri, 10 Jul 2026 16:59:39 +0900

TL;DR

Instead of sending every request straight to the order API, I first placed users in a Redis Sorted Set.

A scheduler removes up to 50 users from the queue every second and issues entry tokens valid for five minutes. Users poll their position until they receive a token, and the order API accepts only requests with a valid X-Entry-Token.

After an order commits successfully, a local event listener receives OrderEvent.Created and deletes the token. If the order fails, the token remains so the user can try again.

This is an initial design for controlling admission rate, rather than a complete production waiting queue. Atomic queue entry, recovery during token issuance, global throughput across instances, and polling load still need more work.

Overview

Goals:
- Keep a sudden burst of order requests from reaching the order database all at once.
- Let users check their queue position and estimated wait time.
- Issue entry tokens to a limited number of users who can then call the order API.
- Remove entry tokens only after a successful order transaction.
- Keep the waiting queue and order domains independent of Redis implementation details.
Settings used in this implementation:
- Scheduler fixed delay: 1 second
- Scheduler batch size: 50 users
- Entry token TTL: 300 seconds
- Rank: zero-based, using the Redis ZRANK result directly

Why put a queue in front of the order API?

A modest rise in order traffic may be handled by scaling out application servers or tuning the database connection pool.

A sharp burst at the start of an event is different. Even with more application instances, requests converge on the same database to lock inventory and coupon rows and save orders. Accepting more requests at the application tier can make database connection demand and lock waits grow even faster.

The queue’s purpose is to admit requests at a rate the downstream system can handle, while other users wait outside that processing path.

I chose not to store order request payloads in the server-side queue. The queue contains only memberId; once admitted, the user sends the original order request again.

This avoids managing the state and retry policy of queued order payloads on the server. The client instead needs to poll its position and call the order API after reaching READY.

Overall architecture

The flow has three parts:

Register users in a Redis ZSET and expose their current status.
Let the scheduler remove users from the front and issue entry tokens.
Validate tokens at the order API and delete them through a local event after the order commits.

The layers have distinct responsibilities:

Layer	Responsibility
Interface	Waiting queue and order APIs, plus the order completion event listener
Application	User authentication, queue status assembly, token issuance, and order admission validation
Domain / Port	The `WaitingQueuePosition` state model and Repository interfaces that abstract Redis
Infrastructure	Repository port implementations using Spring Data Redis
Redis	A ZSET for waiting order and a String entry token for each admitted user

1. Representing queue order with a Redis Sorted Set

The queue needs to answer three main questions:

Is the user in the queue?
What is their current position?
How many users are waiting in total?

A Redis Sorted Set can represent all three.

key : queue:waiting
member : memberId
score : enteredAt

Because memberId is unique within the ZSET, adding the same user repeatedly doesn’t create duplicate members. Using enteredAt as the score places earlier users ahead of later ones. ZRANK returns their position, and ZPOPMIN removes users from the front.

I use the ZRANK value directly, so the first user’s rank is 0. Keeping both the internal model and API response zero-based avoids +1 and -1 conversions at every boundary.

Preserve the position on repeated entry

A waiting user may refresh the page or call the entry API again. Overwriting the score with the current time would send them to the back.

The current implementation checks for an existing score and adds only users who aren’t already registered.

override fun enterIfAbsent(memberId: Long, score: Double) {
 val member = memberId.toString()
 if (redisTemplate.opsForZSet().score(WAITING_QUEUE_KEY, member) == null) {
 redisTemplate.opsForZSet().add(WAITING_QUEUE_KEY, member, score)
 }
}

This preserves the score and rank across sequential repeated calls.

There is an important limitation: ZSCORE and ZADD are separate commands. Two simultaneous first-entry requests for the same user can both see no score and then write different scores. Strict idempotency requires a single atomic Redis operation such as ZADD NX or addIfAbsent.

2. One response model for waiting status

After entering, clients poll the same position API. It returns one of three states:

WAITING: the user is in the ZSET and has no entry token yet.
READY: the user has an entry token and can call the order API.
NOT_ENTERED: the user is neither in the queue nor holding a valid entry token.

Status checks look for the entry token first. The scheduler removes users from the ZSET before issuing tokens, so a READY user is no longer in the ZSET. Checking rank first could incorrectly classify an admitted user as NOT_ENTERED.

stateDiagram-v2
 [*] --> NOT_ENTERED
 NOT_ENTERED --> WAITING: enter() / register in queue
 WAITING --> WAITING: position polling
 WAITING --> READY: scheduler / issue token
 READY --> READY: order rollback / retain token
 READY --> NOT_ENTERED: order commit / delete token
 READY --> NOT_ENTERED: TTL expires

WaitingQueuePosition uses the retrieved rank and total waiting count to calculate these response values:

status
rank
currentTotalWaitingCount
estimatedWaitSeconds
pollingIntervalSeconds
entryToken

The estimated wait is the current rank divided by an assumed throughput of 50 users per second. The polling interval is one second with fewer than 100 users ahead, three seconds with fewer than 1,000, and five seconds otherwise.

Users near admission receive faster updates, while users further back make fewer Redis queries. Since the throughput assumption is fixed, this is only a rough estimate; it doesn’t reflect actual order processing speed.

3. Controlling admission rate with a scheduler

Sending all queued users to the order API at once would defeat the purpose of the queue.

WaitingQueueScheduler calls issueNextEntries() every second. The service uses ZPOPMIN to remove up to 50 users with the lowest scores and issues a token to each.

fun issueNextEntries(batchSize: Long): List<String> {
 return waitingQueueRepository.popNext(batchSize)
 .mapNotNull { memberId ->
 val token = generateToken()
 entryTokenRepository.issue(memberId, token, properties.entryTokenTtl)
 entryTokenRepository.find(memberId)
 }
}

Each token is a URL-safe Base64 encoding of 32 bytes generated by SecureRandom.

key : queue:entry-token:{memberId}
value : generated token
TTL : 300 seconds

The application doesn’t return the generated token directly. It stores it in Redis and reads it back, so a token that wasn’t stored isn’t treated as a valid admission credential.

The TTL serves two purposes. It prevents a token from granting indefinite access to the order API, and it eventually cleans up tokens even if deletion after order completion fails.

A very short TTL could expire while a user is preparing an order. A very long TTL leaves users eligible to enter long after they have stopped trying. The current 300-second value is the assignment’s default policy; a production value should be based on measured user behavior and target throughput.

4. Requiring an entry token at the order API

Order requests include an X-Entry-Token header.

After authentication, OrderFacade.placeOrder() compares the request token with the one stored in Redis. A missing, mismatched, or expired token results in 401 Unauthorized before order processing begins.

I put this validation in the application layer because eligibility to place an order is a precondition of the use case, beyond simply validating an HTTP header’s format.

This is a fail-closed design: when Redis doesn’t respond, orders are blocked. I chose to stop accepting orders instead of letting traffic bypass the queue and overwhelm downstream systems. That protects the server, but makes a Redis outage an order outage as well.

5. Deleting tokens outside the order transaction

I initially considered deleting the token directly inside the order creation method.

That would mix an external Redis operation into the database transaction flow. Deleting the token before commit is also problematic: if the order rolls back, the user loses admission even though the order failed.

The order flow already publishes OrderEvent.Created on success, so I moved token deletion into a listener that receives this local event at AFTER_COMMIT.

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
fun handle(event: OrderEvent.Created) {
 waitingQueueService.deleteEntryToken(event.memberId)
}

This gives us two useful properties:

A rolled-back order leaves the token available for another attempt.
A token cleanup failure cannot roll back an already committed order.

A local event is not a durable message, however. If the process exits just after commit, or Redis deletion fails, the listener has no automatic recovery. The TTL provides eventual cleanup for now. Immediate cleanup would require a retryable event record or a separate cleanup job.

AFTER_COMMIT also does not automatically mean asynchronous execution or exception isolation. The current listener runs in the same call flow as the order request. If a Redis deletion exception propagates, the HTTP response can fail even though the order has committed. Production handling needs an explicit policy for logging and alerting on those exceptions, alongside retryable cleanup work.

Technical decisions

Design area	Choice	Reason
Waiting order	Redis Sorted Set	Unique members, score ordering, rank, and total count in one structure
ZSET member	`memberId`	One waiting entry per user
ZSET score	Entry timestamp in milliseconds	Give earlier arrivals priority
Admission control	Fixed-delay scheduler + batch size	Limit the rate at which users reach downstream processing
Admission credential	Per-user Redis String token + TTL	Separate waiting from readiness and expire old credentials automatically
Status updates	Client polling	Expose positions through a simple HTTP API without a separate push channel
Order validation	Start of `OrderFacade`	Check admission before expensive order processing
Token cleanup	`AFTER_COMMIT` listener for `OrderEvent.Created`	Clean up only successful orders and separate deletion from order rollback

Trade-offs

Admission rate is controlled, but concurrent orders are not strictly bounded

Issuing 50 tokens per second doesn’t guarantee that no more than 50 orders run at once.

Tokens remain valid for 300 seconds. Users admitted across several seconds can wait and then submit orders at the same moment. This design controls the token issuance rate, not actual in-flight order concurrency.

A strict downstream concurrency limit would need active slots, token claims, a semaphore, or another control. Another option is to admit users based on actual order completion rate.

Polling is simple, but creates read traffic

HTTP polling is easy to implement on both sides and doesn’t require long-lived connections. But more waiting users mean more repeated GET token, ZRANK, and ZCARD calls. Varying the polling interval by rank reduces that load.

At larger scale, I would consider client-side jitter to spread requests out, longer polling intervals, Redis read replicas rather than CDN caching for these reads, or SSE-based push.

Separate cleanup does not guarantee immediate cleanup

An AFTER_COMMIT listener reduces the responsibilities inside the order transaction. Its failures happen after the order succeeds, though, so the order cannot be rolled back. A local event also leaves no retry record.

The TTL eventually resolves the leftover-token state, but the token can remain valid until it expires.

A Redis outage stops orders

Fail-closed behavior protects the database from requests bypassing the queue, while making Redis a required dependency of the entire order flow. Production design needs replication, Sentinel or Cluster, persistence, and failover policies as well.

Remaining limitations and work beyond the assignment

1. Concurrent entry by the same user must be atomic

ZSCORE followed by ZADD is a check-then-act sequence. I verified concurrent entry by eight distinct users and sequential repeated entry by the same user. That does not establish atomicity for simultaneous first-entry requests from one user.

This should use the single ZADD NX command.

2. Users can be lost between ZPOPMIN and token storage

The scheduler removes a user from the ZSET before saving the token. If the process exits or the Redis write fails between those operations, the user has neither a queue entry nor a token and becomes NOT_ENTERED.

Reading the token back after storage cannot recover a user who has already been popped.

A production design could atomically move users into a processing ZSET, then acknowledge them after token issuance succeeds. A recovery job could return users without an acknowledgment to the waiting ZSET after a timeout.

3. Batch size is not a global limit across application instances

If every instance runs the scheduler, each can pop 50 users per second. ZPOPMIN prevents duplicate removal of the same user, but four instances can issue up to 200 tokens per second in total.

Using batch size as a global throughput limit requires scheduler leader election, a distributed lock, a dedicated worker, or a Redis-based global rate limiter.

4. The token grants temporary admission, not exactly one order

Token deletion happens after order commit. Two concurrent requests from the same user with the same token can both pass validation.

If one token must authorize only one order, validation and claiming it must be atomic. A simple GETDEL at order start also removes the token when the order later rolls back. A more complete design needs states such as READY → CLAIMED → CONSUMED, plus a release policy on rollback. Order-level idempotency keys deserve separate consideration, too.

5. Estimated wait time doesn’t reflect real throughput

The current formula is rank / 50. It matches the scheduler setting but ignores database latency, order success rate, users who receive tokens without ordering, and outages.

A moving average of recent token issuance and order completion rates, together with batch-size adjustments based on operational metrics, would provide a more realistic estimate.

6. Arrivals within the same millisecond are not strictly FIFO

Scores use application timestamps in milliseconds. Multiple users can arrive in the same millisecond, and clock differences across application servers can change score order relative to actual arrival order.

For equal scores, Redis ZSET orders members lexicographically, which can also differ from arrival order. Strict FIFO would require a design using Redis TIME with a sequence, or a separate incrementing value in the score.

What I verified

Using Testcontainers Redis and API E2E tests, I checked:

First entry returns rank 0 and the total waiting count.
Sequential repeated entry preserves the user’s rank.
Concurrent entry by distinct users assigns unique ranks.
Responses represent WAITING, READY, and NOT_ENTERED.
Tokens are unavailable after their TTL expires.
One scheduler run issues no more than the batch size, even with more users waiting.
Orders without an entry token are rejected.
A successful order commit deletes the entry token.

These tests verify functional contracts. They don’t establish maximum capacity or the right batch size. To choose production settings, I would use a tool such as k6 to generate entry bursts and position polling together, while observing application latency, Redis command throughput, CPU, memory, and connection counts.

Alternatives considered

Option	Benefits	Costs
Delete the token inside the order transaction	The full flow is visible in the order code	Redis cleanup becomes part of the transaction’s responsibilities, and rollback handling becomes more complicated
Selected: delete through an `AFTER_COMMIT` local event	Clean up successful orders and separate post-processing from the transaction	Listener failures aren’t automatically recovered; tokens can remain until TTL expiry

The central decision was that token deletion should not determine whether an order succeeds.

Once an order has committed, preserving that success and cleaning up the token separately makes more sense than presenting a failure because cleanup failed.

The local event alone doesn’t provide that reliability, though. It separates responsibilities, while failure recovery still relies on the TTL. A cleaner structure and a more reliable production system are separate outcomes.

Closing thoughts

At first, I thought adding users to a Redis ZSET and returning their rank would complete the queue implementation.

Most of the difficult questions turned out to concern when a user becomes eligible to order, when that eligibility ends, and which state they should return to after a failure.

In this design, the ZSET represents waiting and the TTL token represents readiness. The order API checks the token, and an event after order commit triggers cleanup. This made the boundary between queue responsibilities and the order transaction clearer.

It also exposed gaps: atomic registration, recovery after pop, global throughput across instances, one-time token use, and wait estimates based on actual throughput. The assignment didn’t force all of these issues into view, but production use would require addressing them.

A waiting queue is an admission control system. It needs to move users at a pace the system can handle and preserve their state transitions even when something fails.

Separating Domain Models from JPA Entities

Fri, 29 May 2026 12:43:19 +0900

TL;DR

I separated domain models from database entities to keep business rules in the domain and isolate JPA mappings and persistence concerns in the infrastructure layer.

Core models such as User, Product, and Order can now express domain rules without JPA annotations. Repository implementations use Mappers to convert between those models and database entities.

The separation also raised questions: where DTO-like objects should live, what Mappers should own, how to reload entities for updates, and where read query projections belong.

Overview

Goals:
- Separate the domain rules and persistence mappings previously handled by a single JPA entity.
- Let domain models express business rules and database entities handle table mappings and persistence.
- Let the Application Layer coordinate domain objects while the Infrastructure Layer stores and retrieves data through JPA.
Main design priorities:
- Remove direct JPA dependencies from the Domain Layer.
- Keep Repository interfaces in the Domain Layer and implementations in the Infrastructure Layer.
- Use Mappers to convert between database entities and domain models.
- Express domain rules through methods and constructor validation rather than entity annotations.

Why separate them?

The original Member implementation had a service layer that called repositories directly and also handled business logic. That is quick to build for small features, but several problems emerge as the domain grows.

First, the JPA entity takes on too many responsibilities. It already uses annotations such as Column, Entity, Table, and OneToMany to describe table mappings. Adding business rules means the same object must understand both the database structure and the domain.

Second, testing becomes harder. When domain logic is built around JPA entities, even simple rule checks can make us think about the persistence context and JPA behavior. A plain Kotlin domain object lets us test rules through its constructor and methods without a repository.

Third, names and responsibilities become mixed. This project called the user domain User, but used a database table named member. Calling the JPA class UserEntity made imports and concepts feel inconsistent. I kept User in the domain and used database-oriented names such as MemberEntity, MemberMapper, and MemberRepositoryImpl in infrastructure.

Technical decisions

Design area	Choice	Rationale
Domain models and database entities	Separate them	Separate domain rules from JPA mapping responsibilities
Repository placement	Interface in Domain, implementation in Infrastructure	Avoid coupling the application to a concrete JPA implementation
Conversion	Separate Mapper	Keep both conversion directions together instead of adding methods such as `toDomain` to entities
Entity names	`MemberEntity`, `ProductEntity`, `OrderEntity`	Make their role as table-mapped persistence models explicit
Domain names	`User`, `Product`, `Order`	Express the business concepts directly
Query optimization	Projections for some list queries	Converting every result to a domain object can hurt sorting and pagination performance

How I applied it

1. Separating User from MemberEntity

The domain model has no JPA annotations. User expresses the business rules for a member.

class User(
 val id: Long = 0L,
 loginId: String,
 password: String,
 name: String,
 birthDate: LocalDate,
 email: String,
) {
 var loginId: String = loginId
 private set

 var password: String = password
 private set

 var name: String = name
 private set

 var birthDate: LocalDate = birthDate
 private set

 var email: String = email
 private set

 init {
 if (!loginId.matches(LOGIN_ID_REGEX)) {
 throw CoreException(ErrorType.BAD_REQUEST, "LoginId must contain only letters and numbers.")
 }
 if (!name.matches(NAME_REGEX)) {
 throw CoreException(ErrorType.BAD_REQUEST, "Name cannot contain special characters or numbers.")
 }
 if (!email.matches(EMAIL_REGEX)) {
 throw CoreException(ErrorType.BAD_REQUEST, "Email cannot contain special characters or numbers.")
 }
 if (birthDate.isAfter(LocalDate.now())) {
 throw CoreException(ErrorType.BAD_REQUEST, "Birthdate must be before now.")
 }
 }

 fun updatePassword(encodedPassword: String) {
 this.password = encodedPassword
 }
}

The database entity lives in infrastructure and maps to the member table.

@Entity
@Table(name = "member")
class MemberEntity(
 @Column(nullable = false, unique = true)
 var loginId: String,

 @Column(nullable = false)
 var password: String,

 @Column(nullable = false)
 var name: String,

 @Column(nullable = false)
 var birthDate: LocalDate,

 @Column(nullable = false)
 var email: String,
) : BaseEntity() {
 fun update(user: User) {
 loginId = user.loginId
 password = user.password
 name = user.name
 birthDate = user.birthDate
 email = user.email
 }
}

Although User and MemberEntity hold the same data, they have different responsibilities. User represents the business concept of a member. MemberEntity is the persistence model used to store that information in the member table.

2. Moving conversion into a Mapper

Separate models need conversion code. I introduced a dedicated Mapper instead of putting toDomain inside the entity.

object MemberMapper {
 fun toDomain(member: MemberEntity): User {
 return User(
 id = member.id,
 loginId = member.loginId,
 password = member.password,
 name = member.name,
 birthDate = member.birthDate,
 email = member.email,
 )
 }

 fun toEntity(user: User): MemberEntity {
 return MemberEntity(
 loginId = user.loginId,
 password = user.password,
 name = user.name,
 birthDate = user.birthDate,
 email = user.email,
 )
 }
}

The goal was to reduce how much the entity needed to know about the domain.

Some dependencies remain. For example, MemberEntity.update(user: User) still accepts a domain object. During an update, I load a JPA managed entity and copy the domain values onto it.

A stricter separation could make update accept primitive values or a command instead. But that can add duplication as the number of fields grows. I chose a practical separation rather than complete isolation.

3. Separating Product from ProductEntity

Product owns product rules. A product name cannot be empty, its price cannot be negative, and deletion is expressed as a change to its state.

class Product(
 val id: Long = 0L,
 val brandId: Long,
 name: String,
 price: Long,
 description: String,
 imageUrl: String,
 isDeleted: Boolean = false,
) {
 var name: String = name
 private set

 var price: Long = price
 private set

 var description: String = description
 private set

 var imageUrl: String = imageUrl
 private set

 var isDeleted: Boolean = isDeleted
 private set

 init {
 validate(
 brandId = brandId,
 name = name,
 price = price,
 description = description,
 imageUrl = imageUrl,
 )
 }

 fun update(
 name: String,
 price: Long,
 description: String,
 imageUrl: String,
 ) {
 validate(
 brandId = brandId,
 name = name,
 price = price,
 description = description,
 imageUrl = imageUrl,
 )

 this.name = name
 this.price = price
 this.description = description
 this.imageUrl = imageUrl
 }

 fun delete() {
 isDeleted = true
 }
}

ProductEntity maps to the product table and contains the JPA annotations and database constraints.

@Entity
@SQLRestriction("is_deleted = false")
@Table(
 name = "product",
 uniqueConstraints = [
 UniqueConstraint(
 name = "uk_product_brand_id_name",
 columnNames = ["brand_id", "name"],
 ),
 ],
)
class ProductEntity(
 @Column(name = "brand_id", nullable = false)
 var brandId: Long,

 @Column(nullable = false)
 var name: String,

 @Column(nullable = false)
 var price: Long,

 @Column(nullable = false)
 var description: String,

 @Column(nullable = false)
 var imageUrl: String,

 @Column(nullable = false)
 var isDeleted: Boolean = false,
) : BaseEntity() {
 fun update(domain: Product) {
 brandId = domain.brandId
 name = domain.name
 price = domain.price
 description = domain.description
 imageUrl = domain.imageUrl
 isDeleted = domain.isDeleted
 }
}

This separation lets infrastructure handle the soft delete query policy while Product expresses the domain action of deleting a product.

There is a trade-off, though. SQLRestriction automatically excludes deleted data from ordinary queries, so the application layer doesn’t need to check isDeleted every time. Features such as administrative auditing or restoration need a separate query path that can include deleted records.

4. Separating the Repository interface from its implementation

The Domain Layer contains only the Repository interface.

interface ProductRepository {
 fun findById(productId: Long): Product?

 fun findAllByIds(productIds: Collection<Long>): List<Product>

 fun save(product: Product): Product

 fun update(product: Product): Product
}

The Infrastructure Layer contains the implementation that uses the JPA repository.

@Component
class ProductRepositoryImpl(
 private val productJpaRepository: ProductJpaRepository,
) : ProductRepository {
 override fun findById(productId: Long): Product? {
 return productJpaRepository.findByIdOrNull(productId)
 ?.let(ProductMapper::toDomain)
 }

 override fun save(product: Product): Product {
 return productJpaRepository.save(ProductMapper.toEntity(product))
 .let(ProductMapper::toDomain)
 }

 override fun update(product: Product): Product {
 val entity = productJpaRepository.findByIdOrNull(product.id)
 ?.also { it.update(product) }
 ?: throw CoreException(ErrorType.NOT_FOUND, "Product not found.")

 return productJpaRepository.save(entity)
 .let(ProductMapper::toDomain)
 }
}

The Application Service depends only on ProductRepository. Tests can supply a fake repository to check domain behavior, while production uses the JPA implementation.

Troubleshooting

Where the complexity appeared

There were moments when separating the models actually made the code more complicated. I spent time thinking about:

Naming a User domain backed by a member table.
The apparent duplication of fields between domain objects and entities.
Where Mappers should live.
Whether an update should reload the JPA entity.
Whether list queries should always return domain models.
Whether DTO-like objects such as ProductSummary belong in the domain.

Why these questions arose

One source of confusion is that “Entity” has two meanings. In DDD, an Entity is a domain object with an identity. A JPA entity is a persistence object mapped to a database row. Because both are called entities, it is easy to assume they must be the same object.

For this project, I saw different reasons for them to change:

A domain model changes when business rules change.
A database entity changes when the table structure or JPA mapping changes.

Another source of complexity is the difference between queries and commands. For flows such as creating an order or updating a product, converting to a domain model makes sense because domain rules matter. For read queries where sorting, pagination, and projections matter most, that conversion can be unnecessary overhead.

The product list needed data from Product, Brand, and ProductStat, along with likes_desc sorting. Fetching each domain separately and merging the results in memory could break pagination accuracy. I used a QueryDSL projection for that query.

What I changed

1. Make responsibilities visible in names

I kept business names such as User, Product, and Order in the domain. Infrastructure uses MemberEntity, ProductEntity, and OrderEntity to make the persistence role explicit.

For User, the table name member informed the infrastructure name Member. This made the imports easier to understand:

domain.user.User
infrastructure.member.MemberEntity
infrastructure.member.MemberMapper
infrastructure.member.MemberRepositoryImpl

2. Keep Mappers in Infrastructure

A Mapper needs to know about the database entity, so it belongs in infrastructure. Making the Domain Layer aware of JPA entities would weaken the separation.

The structure currently looks like this:

domain/user/User
domain/user/UserRepository

infrastructure/member/MemberEntity
infrastructure/member/MemberMapper
infrastructure/member/MemberRepositoryImpl

3. Load a managed entity before applying updates

Creating a new JPA entity from a modified domain object and calling save can lead to an insert instead of an update, or make ID handling awkward.

For updates, I load the existing entity and apply the domain values to it.

override fun update(product: Product): Product {
 val entity = productJpaRepository.findByIdOrNull(product.id)
 ?.also { it.update(product) }
 ?: throw CoreException(ErrorType.NOT_FOUND, "Product not found.")

 return productJpaRepository.save(entity)
 .let(ProductMapper::toDomain)
}

Initially, I wondered why update called findById when I had already loaded the Product.

With separate models, however, the Product held by the application layer is not a managed entity. To use JPA dirty checking, infrastructure needs to obtain the managed entity and apply the changes there.

This introduces another lookup, but preserves both the JPA persistence context behavior and the separation of the domain model.

4. Don’t force every query through a domain model

I decided that separating the models didn’t mean every query had to return a domain object.

Sorting and pagination were central to the product list. Once like counts were moved into ProductStat, likes_desc also needed to sort using that data. ProductQueryRepository therefore returns ProductSummary through a QueryDSL projection.

The placement of ProductSummary is still an open question. It currently lives under a domain DTO package, but an application read model or infrastructure projection may be a better home.

What I would question about the earlier design

Three issues stood out during this work.

First, services were doing too much. When repository calls, business validation, and coordination across domains all live together, the service grows with every feature. This time, I separated the Facade, Application Service, and Domain Service responsibilities.

Second, entity names mixed domain and database concepts awkwardly. A class named UserEntity mapped to a table named member. Now the domain uses User and infrastructure uses MemberEntity.

Third, separation itself could become the goal. Separate models mean more files and conversion code; they don’t automatically improve every feature. A small CRUD project may be simpler if its JPA entities also serve as domain models.

In this project, product, like, order, and inventory rules were likely to grow, so the separation felt worthwhile.

Retrospective

Keep:
- Express business rules in domain models.
- Keep Repository interfaces in the domain and implementations in infrastructure; this helped testability and dependency direction.
- Use clear persistence model names such as MemberEntity to make imports and responsibilities easier to follow.
Problem:
- Mapper code is repetitive.
- Reloading a managed entity during updates made the flow initially unintuitive.
- DTO-like objects such as ProductSummary and ProductCatalog still live under the domain, leaving the boundary between domain models and read models unclear.
- Methods such as Entity.update(domain) mean the separation isn’t completely clean.
Try:
- Consider moving query-only models into application read models or infrastructure projections.
- Check for unnecessary update lookups, and revisit command-based update queries or the dirty checking strategy if performance becomes a problem.
- Add Mapper tests if entity-to-domain conversion rules become more complex.
- Start with domains that have business rules rather than separating every simple CRUD model by default.

Deep dive

The underlying idea

Creating two copies of an object isn’t the point. The point is separating reasons for change.

A domain model expresses business rules. For example, Inventory.quantity must not be negative. A database check constraint can enforce that too, but the domain should enforce it as well. That allows order creation tests to verify insufficient inventory without a database.

class Inventory(
 val id: Long = 0L,
 val productId: Long,
 quantity: Long,
) {
 var quantity: Long = quantity
 private set

 init {
 if (quantity < 0L) {
 throw CoreException(ErrorType.BAD_REQUEST, "Inventory quantity must not be negative.")
 }
 }

 fun deduct(quantity: Long) {
 if (quantity <= 0L) {
 throw CoreException(ErrorType.BAD_REQUEST, "Deduct quantity must be positive.")
 }
 if (this.quantity < quantity) {
 throw CoreException(ErrorType.CONFLICT, "Inventory quantity is insufficient.")
 }

 this.quantity -= quantity
 }
}

A database entity expresses the storage structure. For example, OrderEntity describes the relationship between the orders and order_item tables.

@Entity
@Table(name = "orders")
class OrderEntity(
 @Column(name = "order_number", nullable = false)
 var orderNumber: String,

 @Column(name = "member_id", nullable = false)
 var memberId: Long,

 @Enumerated(EnumType.STRING)
 @Column(nullable = false)
 var status: OrderStatus,

 @Column(name = "total_amount", nullable = false)
 var totalAmount: Long,

 @Column(name = "ordered_at", nullable = false)
 var orderedAt: ZonedDateTime,
) : BaseEntity() {
 @OneToMany(mappedBy = "order", cascade = [CascadeType.ALL], orphanRemoval = true)
 @BatchSize(size = 50)
 val items: MutableList<OrderItemEntity> = mutableListOf()

 fun addItem(item: OrderItemEntity) {
 items.add(item)
 item.order = this
 }
}

The Order domain model expresses the business result of an order.

class Order(
 val id: Long = 0L,
 val orderNumber: String,
 val memberId: Long,
 val status: OrderStatus,
 val items: List<OrderItem>,
 val totalAmount: Long,
 val orderedAt: ZonedDateTime,
) {
 init {
 if (items.isEmpty()) {
 throw CoreException(ErrorType.BAD_REQUEST, "Order items must not be empty.")
 }
 if (totalAmount != items.sumOf { it.totalAmount }) {
 throw CoreException(ErrorType.BAD_REQUEST, "Order total amount is invalid.")
 }
 }
}

The objects look similar, but their responsibilities differ. OrderEntity knows about JPA cascade, batch fetching, and table mappings. Order knows that an order must contain items and that totalAmount must equal the sum of the item amounts.

How this worked in my project

Creating an order required Product, Brand, Inventory, and Order to cooperate.

OrderFacade in the Application Layer retrieves the required data and establishes the transaction boundary. The Domain Service, OrderPlacementService, checks that products, brands, and inventory exist, deducts stock, and creates order snapshots.

class OrderPlacementService {
 fun place(
 memberId: Long,
 items: List<OrderPlacementItem>,
 products: List<Product>,
 brands: List<Brand>,
 inventories: List<Inventory>,
 ): OrderPlacementResult {
 val productById = products.associateBy { it.id }
 val brandById = brands.associateBy { it.id }
 val inventoryByProductId = inventories.associateBy { it.productId }

 val orderItems = items.map { item ->
 val product = productById[item.productId]
 ?: throw CoreException(ErrorType.NOT_FOUND, "Product not found.")
 val brand = brandById[product.brandId]
 ?: throw CoreException(ErrorType.NOT_FOUND, "Brand not found.")
 val inventory = inventoryByProductId[product.id]
 ?: throw CoreException(ErrorType.NOT_FOUND, "Inventory not found.")

 inventory.deduct(item.quantity)
 OrderItem.snapshot(
 productId = product.id,
 productName = product.name,
 brandName = brand.name,
 unitPrice = product.price,
 quantity = item.quantity,
 )
 }

 return OrderPlacementResult(
 order = Order.createCompleted(memberId = memberId, items = orderItems),
 inventories = inventories,
 )
 }
}

OrderPlacementService knows nothing about JPA or ProductEntity, InventoryEntity, and OrderEntity. It accepts domain objects and applies the rules.

That was the biggest benefit I gained from the separation.

When might separation be unnecessary?

Separating domain models from database entities isn’t always the best choice. Using JPA entities as domain models may be reasonable when:

The project mostly consists of simple CRUD.
There are few business rules.
The table structure closely matches the API requirements.
Database dependencies aren’t a significant problem in tests.
The team is unfamiliar with separate models and productivity matters more.

Separation is worth considering when:

Domain rules are growing.
Multiple Aggregates or domains cooperate.
Database structures and business models may change independently.
JPA annotations or associations intrude on domain code.
Unit tests need to verify rules without a database.
Read queries and command models have different requirements.

Here, products, brands, likes, inventory, and orders worked together, with core rules such as deducting inventory during order creation. That made separation a better fit.

What Exactly Is a Test Double?

Fri, 15 May 2026 12:28:45 +0900

While studying testing, I came across the term Test Double. I knew what a test was, but what was the “double” doing there?

Think of a stunt double: someone who stands in for an actor, usually without showing their face. A Test Double plays a similar role. It stands in for a real object when using that object in a test would be difficult or undesirable.

In this post, I’ll go through what Test Doubles do, when they are useful, and when we should be careful with them.

What is a Test Double?

The Wikipedia article on Test Doubles describes the idea roughly as follows:

Software used in testing to satisfy a dependency without making the code under test depend directly on the real production implementation.

Satisfying a dependency without using the real implementation means replacing an external object with a test-specific one while keeping the interface the code needs.

Suppose an order service calls a payment API.

class OrderService(
 private val paymentGateway: PaymentGateway
) {
 fun pay(orderId: String, amount: Int): PaymentResult {
 return paymentGateway.pay(orderId, amount)
 }
}

interface PaymentGateway {
 fun pay(orderId: String, amount: Int): PaymentResult
}

data class PaymentResult(
 val transactionId: String,
 val success: Boolean
)

We want to test OrderService, but calling a real payment API on every test run would be a problem. If running a test charges someone’s card, that’s an incident.

So we provide a test implementation of PaymentGateway in place of the real one.

class StubPaymentGateway : PaymentGateway {
 override fun pay(orderId: String, amount: Int): PaymentResult {
 return PaymentResult("test-transaction", true)
 }
}

OrderService has no idea whether it is talking to the real payment API or a test implementation. It simply makes requests through the PaymentGateway interface.

Here, StubPaymentGateway is the Test Double.

Why use a stand-in?

My first reaction was: couldn’t we just test with the real object?

Often, that’s a good choice. Real objects give us behavior closest to production. But tests that connect every real dependency can become slow, unreliable, and difficult to control.

Test Doubles are commonly useful when:

The code calls an external API.
It depends on slow resources such as a database or file system.
Its results depend on changing values such as the current time or random numbers.
We need to reproduce a failure deliberately.
We want to test one component in isolation.

For example, suppose we want to test a failed payment. We can’t wait for the real payment server to fail at just the right moment. That tends to happen right after a deployment, anyway.

In a test, we can create a stand-in that always fails.

class FailingPaymentGateway : PaymentGateway {
 override fun pay(orderId: String, amount: Int): PaymentResult {
 return PaymentResult("failed-transaction", false)
 }
}

Now we can reproduce a payment failure whenever we need to. This is the main benefit of Test Doubles: they put us in control of the test environment.

Types of Test Doubles

Test Double is an umbrella term. The names can be confusing at first, but their purposes make them easier to distinguish.

The five commonly discussed types are:

Dummy
Stub
Fake
Spy
Mock

Dummy: required, but never used

A Dummy is passed into the code so the test can run, but it is never used in the execution path being tested.

Suppose a user registration service requires a notification sender in its constructor. Our test only cares about validating user names, so sending notifications is outside its scope.

interface NotificationSender {
 fun send(message: String)
}

class UserService(
 private val notificationSender: NotificationSender
) {
 fun validateName(name: String): Boolean {
 return name.isNotBlank()
 }
}

The constructor requires NotificationSender, but validateName() never uses it. We can supply a Dummy that does nothing.

class DummyNotificationSender : NotificationSender {
 override fun send(message: String) {
 // Not used in this test.
 }
}

A Dummy simply fills a required slot. Its behavior is irrelevant to the test.

Stub: a stand-in with a prepared answer

A Stub returns values we have prepared for the test. Think of an interview candidate who has memorized the expected questions and immediately delivers a rehearsed answer.

Suppose a service calculates a discount based on a user’s membership grade.

interface UserRepository {
 fun findGrade(userId: Long): String
}

class DiscountService(
 private val userRepository: UserRepository
) {
 fun discountRate(userId: Long): Int {
 val grade = userRepository.findGrade(userId)

 return when (grade) {
 "VIP" -> 20
 "BASIC" -> 5
 else -> 0
 }
 }
}

We want to test the discount calculation, not the database query. A Stub can return a specific grade.

class VipUserRepositoryStub : UserRepository {
 override fun findGrade(userId: Long): String {
 return "VIP"
 }
}

The test then looks like this:


class DiscountServiceTest {
 @Test
 fun `VIP users receive a 20 percent discount`() {
 val service = DiscountService(VipUserRepositoryStub())

 val result = service.discountRate(1L)

 assertEquals(20, result)
 }
}

Fake: a simplified working implementation

A Fake behaves like a real implementation but takes shortcuts that make it unsuitable for production.

An in-memory store is a common example. The real service uses a database, while the test uses an in-memory collection to support similar operations.

data class User(
 val id: Long,
 val name: String
)

interface UserStore {
 fun save(user: User)
 fun findById(id: Long): User?
}

class FakeUserStore : UserStore {
 private val users = mutableMapOf<Long, User>()

 override fun save(user: User) {
 users[user.id] = user
 }

 override fun findById(id: Long): User? {
 return users[id]
 }
}

This Fake can save and retrieve users, just as a database can. It doesn’t provide transactions, concurrency handling, or query optimization. It implements only as much behavior as the test needs.


class FakeUserStoreTest {
 @Test
 fun `retrieves a previously saved user`() {
 val store = FakeUserStore()
 val user = User(1L, "wild")

 store.save(user)

 assertEquals(user, store.findById(1L))
 }
}

Fakes are useful, but there is a catch: if the Fake behaves too differently from the real implementation, tests can pass while production fails.

Spy: a stand-in that records what happened

A Spy records information such as whether a method was called and how many times it was called.

Suppose completing an order should send a notification.

interface OrderNotifier {
 fun notify(orderId: String)
}

class OrderCompleteService(
 private val notifier: OrderNotifier
) {
 fun complete(orderId: String) {
 notifier.notify(orderId)
 }
}

We may want to check that the notification was requested without actually delivering it. Mockito’s spy can help with that.


class OrderCompleteServiceTest {
 @Test
 fun `sends a notification when an order is completed`() {
 val notifier = Mockito.spy(object : OrderNotifier {
 override fun notify(orderId: String) {
 // Do not send a real notification.
 }
 })
 val service = OrderCompleteService(notifier)

 service.complete("order-1")

 Mockito.verify(notifier).notify("order-1")
 }
}

A Spy lets us look back after execution and check what happened.

Mock: verifying expected interactions

A Mock is commonly used to verify which methods were called and which arguments they received. Libraries such as Mockito provide this functionality.


class OrderServiceMockTest {
 @Test
 fun `forwards the payment request to the payment gateway`() {
 val gateway = Mockito.mock(PaymentGateway::class.java)
 val service = OrderService(gateway)

 Mockito.`when`(
 gateway.pay("order-1", 10_000)
 ).thenReturn(PaymentResult("tx-1", true))

 val result = service.pay("order-1", 10_000)

 assertTrue(result.success)
 Mockito.verify(gateway).pay("order-1", 10_000)
 }
}

Mocks are powerful, but using them indiscriminately can tie tests too closely to implementation details.

Overly strict checks on internal call counts or call order make refactoring difficult. A small internal change can break a whole set of tests even though the feature still behaves exactly the same way.

Tests should protect the product’s behavior. They shouldn’t freeze the code in its current shape.

When are Test Doubles useful?

Test Doubles help make tests fast and reliable, especially when we want to separate the core logic under test from external dependencies.

These are the situations where I think they make the most sense.

When the code depends on external systems

Calling an external system directly from a test can be slow, cost money, and fail because of network conditions.

Stubs and Mocks let us reproduce success, failure, and timeout scenarios predictably.

When tests take too long

If every test connects to every external API, feedback becomes slow. Developers run slow tests less often. Eventually, the tests become like documentation that exists but rarely gets read.

We can use Test Doubles for fast unit tests and verify the real connections separately with integration tests.

When we need to reproduce failures

Failures are hard to arrange in a real environment, but they still need testing. Does the code retry a failed API call? Does it translate exceptions appropriately? What response reaches the user?

A Test Double lets us trigger exactly the failure we need at exactly the right point.

class TimeoutPaymentGateway : PaymentGateway {
 override fun pay(orderId: String, amount: Int): PaymentResult {
 throw RuntimeException("timeout")
 }
}

We can prepare for a failure instead of waiting for one.

When should we be cautious?

Convenience doesn’t mean every dependency needs a Test Double. The more real behavior we replace, the further our tests can drift from production.

Replacing Value Objects or simple domain objects

For simple objects, using the real thing is usually easier.

data class Money(
 val amount: Int
)

There is rarely a reason to Mock an object like this. Just create Money(10_000). If an object is cheap to construct and simple to use, a stand-in adds little value.

Tying tests too closely to the implementation

Mocks make it easy to verify which methods were called. From a user’s perspective, though, the result usually matters more.

In a discount test, verifying that a VIP user receives a 20% discount may be more valuable than verifying that findGrade() was called exactly once.

When an interaction is itself a requirement, we should verify it. If completing an order must trigger a notification, checking that call makes sense. Checking internal calls simply because the current implementation happens to make them produces brittle tests.

Letting a Fake diverge from the real implementation

An in-memory Fake is convenient, but it isn’t a real database. If the database enforces a unique constraint and the Fake doesn’t, tests may pass while production fails.

We need to understand which parts of the real implementation the Fake reproduces and which parts it leaves out.

Using only unit tests where integration tests are needed

Test Doubles remove dependencies from a test. We still need to check that the boundaries we removed actually work when connected.

Replacing every Repository with a Fake can give us fast feedback on service logic. It cannot tell us whether our SQL is correct, our mappings work, or our transactions behave as intended.

Unit tests with Test Doubles and integration tests with real dependencies serve different purposes. One doesn’t replace the other.

The rule of thumb I use

My current guideline is:

Use a Test Double when something outside the scope of the test makes it slow, unreliable, or difficult to set up.

And the habit to avoid is:

Replacing everything automatically, even when real objects would make the test fast and clear enough.

The key is to be explicit about what we want to test. Discount logic, database queries, and external API integration call for different choices about which objects should be real and which should be Test Doubles.