llm-wiki/raw/official-docs/retry-spring-retry-readme-backoff-defaults.md

---
title: Spring Retry README — maxAttempts default & exponential backoff 설정 조건
source_type: official-doc
url: https://github.com/spring-projects/spring-retry/blob/main/README.md
archive_url:
related_branches: [feature-background-job-async-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, application, spring-boot, circuit-breaker]
created: 2026-06-11
---

# Spring Retry README — maxAttempts default & exponential backoff 설정 조건

> Layer: `raw/` — Spring Retry 공식 저장소 README 원문 발췌·출처 기록.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch (필수, 최소 1개+)

> 이 자료는 혼자 존재하지 않는다. 어느 branch(또는 project)의 구현 결정의 근거로서 보관됨.

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-background-job-async-contract]] | D4 — `@Retryable` 의 maxAttempts default = 3 verbatim 확인; exponential+jitter 는 라이브러리 default 가 아니라 `multiplier > 1.0` + `random=true` 명시 설정 필요 (`@Backoff` default 는 명시 없음) |

## 출처 / Source

- 원본 URL: https://github.com/spring-projects/spring-retry/blob/main/README.md
- 아카이브 URL: (미설정)
- 저자 / 조직: Spring Projects (Pivotal / VMware / Broadcom)
- 발행일: (README — 지속 갱신, main 브랜치 HEAD)
- 마지막 확인일: 2026-06-11

## 왜 저장했는지 / Why archived

`feature-background-job-async-contract` D4 결정 ("기본 backoff = exp+jitter, max=3") 이 `UNSUPPORTED_DECISION` 으로 표시되어 있어, Spring Retry 공식 README 에서 (1) maxAttempts default 값 verbatim 과 (2) exponential+jitter 가 명시 설정 없이는 활성화되지 않음을 근거로 확보하기 위해 보관.

## 핵심 인용 / Key quotes (verbatim, 3~5문장)

> [§ Declarative Retry] "This example calls the `service` method and, if it fails with a `RemoteAccessException`, retries (by default, up to three times), and then tries the `recover` method if unsuccessful."

> [§ Exponential Backoff Rationale] "A common use case is to back off with an exponentially increasing wait period, to avoid two retries getting into lock step and both failing (a lesson learned from Ethernet)."

> [§ @Backoff delay+maxDelay example] "The preceding example creates a random backoff between 100 and 500 milliseconds and up to 12 attempts."

> [§ RetryTemplate Builder API] `.exponentialBackoff(100, 2, 10000)` — initial delay 100 ms, multiplier 2, max delay 10000 ms. Requires explicit builder call; not the default.

> [§ Project Status] "⚠️ Project Status: Maintenance Only This project has been superseded by Spring Framework 7 and is no longer accepting enhancements."

## Claims Extracted / 추출된 주장

> 이 자료가 직접 말하는 것만 claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SPRING-RETRY-C1 | `@Retryable` 의 default maxAttempts = 3 | [§ Declarative Retry] "retries (by default, up to three times)" | `official-vendor-doc` | Spring Retry `@Retryable` annotation 사용 시 | Spring Framework 7 native retry 또는 Resilience4j 의 default 값이 동일하다는 것을 증명하지 않음 |
| SPRING-RETRY-C2 | Exponential backoff with jitter 는 라이브러리 default 가 아니라 명시 설정 필요 (`multiplier` 와 `random` 파라미터를 명시해야 함) | [§ Exponential Backoff Rationale] "avoid two retries getting into lock step and both failing" + builder API `.exponentialBackoff(100, 2, 10000)` 는 explicit call 임 | `official-vendor-doc` | Spring Retry `@Backoff` / `RetryTemplate.builder()` 를 통한 retry 설정 | `@Backoff` 의 기본 `delay`, `multiplier`, `random` 수치를 명시하지 않음 (README 에서 default 값 표 미제공) |
| SPRING-RETRY-C3 | `@Backoff(delay=100, maxDelay=500)` 조합은 100~500 ms 사이의 random backoff 를 생성 | [§ @Backoff example] "creates a random backoff between 100 and 500 milliseconds" | `official-vendor-doc` | `delay` 와 `maxDelay` 를 모두 지정하고 둘 사이에 범위가 있을 때 | multiplier 를 명시하지 않은 경우의 정확한 분포(균등/지수)를 증명하지 않음 |
| SPRING-RETRY-C4 | Spring Retry 는 현재 maintenance 모드이며 Spring Framework 7 로 대체됨 | [§ Project Status] "superseded by Spring Framework 7 and is no longer accepting enhancements" | `official-vendor-doc` | Spring Retry 라이브러리 사용 여부 평가 시 | Spring Framework 7 의 retry 기능이 Spring Retry 와 기능 동등(feature parity) 함을 증명하지 않음 |

### Strength 허용값

- 본 문서 claims 는 모두 `official-vendor-doc` — Spring Projects 공식 저장소 README.

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `SPRING-RETRY-C1`: `@Retryable` 사용 시 별도 `maxAttempts` 지정 없으면 3회 시도 (2회 재시도)
  - `SPRING-RETRY-C2`: exponential backoff 와 jitter 는 명시 설정 없이는 활성화되지 않음 — `.exponentialBackoff()` 또는 `@Backoff(multiplier=..., random=true)` 를 코드에서 직접 명시해야 함
  - `SPRING-RETRY-C3`: `delay` 와 `maxDelay` 를 함께 쓰면 그 사이 random backoff 생성
  - `SPRING-RETRY-C4`: 신규 기능 추가는 없고 유지보수 모드
- 이 자료가 증명하지 않는 것:
  - `@Backoff` 의 기본 `delay` 수치 (README 에서 명시하지 않음)
  - `@Backoff` 의 기본 `multiplier` 수치 (README 에서 명시하지 않음)
  - `@Backoff` 의 기본 `random` 값 (`false`/`true` — README 에서 명시하지 않음)
  - Resilience4j 와의 기능 비교 (별도 raw 자료 필요)
  - Spring Framework 7 의 retry API 가 Spring Retry 의 모든 기능을 대체하는지 여부
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl 에서 실제 `@Retryable(maxAttempts=3, backoff=@Backoff(multiplier=2, random=true))` 또는 동등 설정을 코드에서 명시하고, `locally-verified` 등급으로 승급
  - `@Backoff` 파라미터 실제 default 값 확인 필요 시 Spring Retry source (`@Backoff.java`) 직접 조회 권고

## 메모 / Notes

- D4 의 `UNSUPPORTED_DECISION` 은 본 자료로 부분 해소: maxAttempts=3 은 default 임이 SPRING-RETRY-C1 으로 확인됨. exp+jitter 는 default 가 아니라 "명시 설정 필요" 임이 SPRING-RETRY-C2 로 확인됨.
- D4 의 "DLQ after exhausted" 부분은 본 README 에서 다루지 않음 — DLQ 패턴은 별도 raw 자료 (예: Spring Retry `RecoveryCallback` 공식 doc 또는 messaging 플랫폼 DLQ doc) 로 보완 필요.
- `@Backoff` 의 정확한 default 수치 (delay=1000?, multiplier=1.0?) 는 README 미명시 — source 코드 또는 Javadoc 으로만 확인 가능. 확인 전 `needs-confirmation`.
- Spring Retry 가 maintenance 모드 (SPRING-RETRY-C4) 이므로 신규 프로젝트에서는 Spring Framework 7 dependency 확인 권고.

## Related / 관련

- 같은 주제 다른 official-doc: [[raw/official-docs/outbound-resilience4j-vs-spring-retry]] (Resilience4j vs Spring Retry 비교)
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/retry-backoff-contract]]` (생성 시)