65 lines
2.7 KiB
Markdown
65 lines
2.7 KiB
Markdown
# Migrating from `RestTemplate`
|
|
|
|
`RestTemplate` is permitted only inside `…httpclient.migration`; `RestTemplateBoundaryTest` enforces
|
|
that. New retry, Dynamic Target, and HTTP/3 capabilities are deliberately unreachable from the
|
|
migration path — a caller that wants them moves to a Named Client Profile.
|
|
|
|
## 1. Audit before changing anything
|
|
|
|
```java
|
|
RestTemplateInventory inventory = new RestTemplateInventoryScanner().scan(existingTemplate);
|
|
```
|
|
|
|
The inventory reports the request factory, message converters, interceptors, error handler, and URI
|
|
template handler, plus findings:
|
|
|
|
| Code | Severity | Meaning |
|
|
|---|---|---|
|
|
| `SIMPLE_REQUEST_FACTORY` | blocking | no connection pool; unsupported in production |
|
|
| `NO_MESSAGE_CONVERTERS` | blocking | the template cannot encode or decode a body |
|
|
| `NO_INTERCEPTORS` | warning | confirm where correlation and timeouts are applied |
|
|
| `TIMEOUTS_NOT_INTROSPECTABLE` | informational | declare timeouts explicitly on the target profile |
|
|
|
|
## 2. Bridge without changing behaviour
|
|
|
|
```java
|
|
RestClient client = new RestTemplateToRestClientAdapter().adaptChecked(existingTemplate);
|
|
```
|
|
|
|
`adaptChecked` refuses to migrate a template with a blocking finding. The bridge carries the
|
|
existing converters, interceptors, error handler, and URI handler across, so this step changes the
|
|
API and nothing else.
|
|
|
|
## 3. Move to a Named Client Profile
|
|
|
|
Turn the platform on with `APP_HTTPCLIENT_ENABLED=true` — it ships off, and while it is off none of
|
|
the settings below are bound — then declare the upstream as `app.httpclient.clients[N]` with its
|
|
`name` and an explicit base URL, transport, timeouts, pool, body limits, authentication, retry
|
|
policy, redirect policy, and TLS profile. Startup validation will tell you exactly which of those is
|
|
missing. See `docs/httpclient/configuration-reference.md` for the environment form.
|
|
|
|
## 4. Move to a typed client
|
|
|
|
```java
|
|
@HttpClientProfile("payment")
|
|
@HttpExchange("/payments")
|
|
public interface PaymentClient {
|
|
|
|
@PostExchange
|
|
@HttpOperationPolicy(
|
|
name = "create-payment",
|
|
idempotency = OperationIdempotency.IDEMPOTENCY_KEY_REQUIRED,
|
|
retryPolicy = "payment-write")
|
|
PaymentResponse create(
|
|
@RequestHeader("Idempotency-Key") String idempotencyKey, @RequestBody PaymentRequest request);
|
|
}
|
|
```
|
|
|
|
The interface fails startup validation unless it declares a profile, gives every method a stable
|
|
operation name and an explicit idempotency, supplies a key parameter when the operation requires
|
|
one, keeps a single execution model, and does not enable retry on a non-idempotent write.
|
|
|
|
## 5. Retire the template
|
|
|
|
Once no production package references `RestTemplate`, `RestTemplateBoundaryTest` keeps it that way.
|