Skip to content

Document combining @Retryable with proxy-based features#37005

Open
jhan0121 wants to merge 1 commit into
spring-projects:mainfrom
jhan0121:gh-35584-document-retryable-proxy-semantics
Open

Document combining @Retryable with proxy-based features#37005
jhan0121 wants to merge 1 commit into
spring-projects:mainfrom
jhan0121:gh-35584-document-retryable-proxy-semantics

Conversation

@jhan0121

@jhan0121 jhan0121 commented Jul 5, 2026

Copy link
Copy Markdown
Contributor

Document the semantics of combining @Retryable with other proxy-based annotations (@Transactional, @Cacheable, and @Async), addressing the advice chain ordering that determines retry behavior.

Changes

Tests

  • Add withCacheableAnnotation() to RetryInterceptorTests verifying that retry is applied outside the cache interceptor (Retry OUTER -> Cache INNER).
  • Add RetryableTransactionTests in spring-tx verifying that each retry attempt starts a fresh transaction (Retry OUTER -> TX INNER). Placed in spring-tx to avoid a circular module dependency.

Javadoc

  • Add a paragraph to @Retryable documenting the proxy interaction semantics and pointing to EnableResilientMethods#order() and EnableAsync#order() for customizing the order relative to @Async (the order relative to @Transactional/@Cacheable is fixed).

Reference documentation

  • Add a "Combining @Retryable with Other Proxy-Based Features" section to resilience.adoc, covering the default advice chain order for each combination, and advice order customization between @Retryable and @Async via @EnableResilientMethods(order)/@EnableAsync(order) (this customization does not apply to @Transactional/@Cacheable,
    whose shared InfrastructureAdvisorAutoProxyCreator always runs first).
  • Add cross-reference TIP blocks to the @Transactional and @Async reference sections pointing to the new combining section.

Spring Boot compatibility

Verified with a dedicated validation repository (https://github.com/jhan0121/spring-resilience-boot-validation) that the advice chain order is consistent across all Spring Boot 4.x GA releases (4.0.0 through 4.1.0) under auto-configuration:

Scenario Order Result
@Retryable + @Transactional Retry OUTER → TX INNER PASS
@Retryable + @Cacheable Retry OUTER → Cache INNER PASS
@Retryable + @Async Async OUTER → Retry INNER PASS

Closes gh-35584

Add a "Combining @retryable with Other Proxy-Based Features" section
to the resilience reference documentation, covering interaction with
@transactional, @Cacheable, and @async, as well as advice order
customization between @retryable and @async via
@EnableResilientMethods(order) and @EnableAsync(order).

Also document the advice chain semantics in @retryable Javadoc, add
cross-reference TIP blocks in the @async and @transactional reference
sections, add a @Cacheable combination test to RetryInterceptorTests,
and add RetryableTransactionTests in spring-tx for the @transactional
combination.

Closes spring-projectsgh-35584

Signed-off-by: jhan0121 <jhan0121@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status: waiting-for-triage An issue we've not yet triaged or decided on

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document semantics for combining @Retryable with other proxy-based features

2 participants