Skip to content

Commit 81a617e

Browse files
committed
docs: add HC4 to HC5 migration notes for resource naming
Document the default resource name format difference between HC4 and HC5 adapters so users understand that existing flow control rules will not match automatically after migration, and provide a snippet for preserving the legacy URI-only naming via a custom extractor. Change-Id: Iadacf3d3288acb4b23ce67441a88c0b8ad0f0b6e Co-developed-by: Claude <noreply@anthropic.com>
1 parent fe82273 commit 81a617e

1 file changed

Lines changed: 26 additions & 0 deletions

File tree

  • sentinel-adapter/sentinel-apache-httpclient5-adapter

sentinel-adapter/sentinel-apache-httpclient5-adapter/README.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,32 @@ public class MyResourceExtractor implements ApacheHttpClientResourceExtractor {
6262
}
6363
```
6464

65+
### Migration from Apache HttpClient 4.x Adapter
66+
67+
> **Note:** The default resource naming convention differs between the HC4 and HC5 adapters. If you are migrating from
68+
> `sentinel-apache-httpclient-adapter` to `sentinel-apache-httpclient5-adapter`, please review your existing flow control
69+
> rules carefully — they will **not** match automatically.
70+
71+
| Adapter | Default Resource Name Format | Example |
72+
| --- | --- | --- |
73+
| `sentinel-apache-httpclient-adapter` (HC4) | URI only (path, may include query) | `httpclient:/api/users` |
74+
| `sentinel-apache-httpclient5-adapter` (HC5) | `METHOD:full_url` (query/fragment stripped) | `httpclient:GET:http://example.com/api/users` |
75+
76+
Both adapters share the same default resource prefix (`httpclient:`), but the resource name suffix is incompatible.
77+
This means any flow control rules configured against HC4 resource names will no longer take effect after migration.
78+
79+
You have two options:
80+
81+
1. **Update your rules** to match the new HC5 resource name format (recommended — aligns with the OkHttp adapter and
82+
provides better granularity by including the HTTP method).
83+
2. **Preserve the old format** by supplying a custom `ApacheHttpClientResourceExtractor` that returns only the URI path,
84+
e.g.:
85+
86+
```java
87+
SentinelApacheHttpClientConfig config = new SentinelApacheHttpClientConfig();
88+
config.setExtractor(request -> request.getRequestUri());
89+
```
90+
6591
### Fallback
6692

6793
The default fallback throws `SentinelRpcException`. You can customize the behavior:

0 commit comments

Comments
 (0)