This is an automated email from the ASF dual-hosted git repository.
AlexStocks pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/dubbo-go.git
The following commit(s) were added to refs/heads/develop by this push:
new e0e291cd5 docs: update filter README (#3447)
e0e291cd5 is described below
commit e0e291cd53f7eded6319b265e96362263969e382
Author: Xuetao Li <[email protected]>
AuthorDate: Mon Jun 22 01:22:47 2026 +0000
docs: update filter README (#3447)
---
filter/README.md | 118 ++++++++++++++++++++++++++++---------------------------
1 file changed, 61 insertions(+), 57 deletions(-)
diff --git a/filter/README.md b/filter/README.md
index 000c8234c..85f3516ec 100644
--- a/filter/README.md
+++ b/filter/README.md
@@ -1,18 +1,22 @@
# Filter
+Dubbo-go filters are interceptor-style extensions around RPC invocation.
+They are typically used to add cross-cutting behavior such as authentication,
+rate limiting, logging, tracing, metrics, generic invocation adaptation, and
+graceful shutdown handling.
+
## Getting Started
-Recommended Way: import only the filters you need. See also
[dubbo-go/imports](https://github.com/dubbogo/imports).
+The recommended approach is to import only the filters your application needs.
```go
package demo
-// use echo and generic filters
import _ "dubbo.apache.org/dubbo-go/v3/filter/echo"
import _ "dubbo.apache.org/dubbo-go/v3/filter/generic"
```
-Legacy way: import all filters by one line.
+If you prefer the legacy all-in-one import, you can still use:
```go
package demo
@@ -20,65 +24,65 @@ package demo
import _ "dubbo.apache.org/dubbo-go/v3/filter/filter_impl"
```
-## Contents
-
-- accesslog: Access Log Filter(https://github.com/apache/dubbo-go/pull/214)
-- active
-- adaptivesvc: Adaptive Service Filter
-- auth: Auth/Sign Filter(https://github.com/apache/dubbo-go/pull/323)
-- echo: Echo Health Check Filter
-- exec_limit: Execute Limit Filter(https://github.com/apache/dubbo-go/pull/246)
-- generic: Generic Filter(https://github.com/apache/dubbo-go/pull/291)
-- graceful_shutdown: Graceful Shutdown Filter
-- hystrix: Moved to
[dubbo-go-extensions](https://github.com/apache/dubbo-go-extensions/tree/main/filter/hystrix)
-- metrics: Metrics Filter(https://github.com/apache/dubbo-go/pull/342)
-- otel/trace: OpenTelemetry Tracing Filter
-- polaris/limit: Polaris Rate Limit Filter
-- seata: Seata Filter
-- sentinel: Sentinel Filter
-- token: Token Filter(https://github.com/apache/dubbo-go/pull/202)
-- tps: Tps Limit Filter(https://github.com/apache/dubbo-go/pull/237)
-- tracing: Tracing Filter(https://github.com/apache/dubbo-go/pull/335)
-
-## Generic response attachments
-
-In dubbo-go 3.x, `GenericService2` is no longer the response attachment access
-point used by older 1.5.x applications. For Triple generic calls, provider-side
-result attachments are written back as response trailers and can be read from
-the call context after the generic invocation returns.
-
-Initialize the context with Triple outgoing metadata before the call. This also
-enables the client-side Triple transport to copy response trailers back into
-the context.
+## Where Filters Apply
-```go
-package demo
+Dubbo-go distinguishes between two filter chains:
-import (
- "context"
- "net/http"
+- `service.filter`: provider-side filters
+- `reference.filter`: consumer-side filters
- hessian "github.com/apache/dubbo-go-hessian2"
+The built-in defaults are defined in `common/constant/default.go`.
- "dubbo.apache.org/dubbo-go/v3/filter/generic"
- triple "dubbo.apache.org/dubbo-go/v3/protocol/triple/triple_protocol"
-)
+## Built-in Filters
-func invokeWithResponseAttachments(genericService *generic.GenericService)
(http.Header, error) {
- ctx := triple.NewOutgoingContext(context.Background(), http.Header{})
+### Core
- _, err := genericService.Invoke(ctx, "echo",
[]string{"java.lang.String"}, []hessian.Object{"hello"})
- if err != nil {
- return nil, err
- }
+- `echo`: echo health check support
+- `generic`: consumer-side generic invocation filter
+- `generic_service`: provider-side generic service filter
+- `graceful_shutdown`: graceful shutdown behavior for provider and consumer
paths
- trailers, ok := triple.FromIncomingContext(ctx)
- if !ok {
- return nil, nil
- }
- return trailers, nil
-}
-```
+### Traffic Control
+
+- `active`: active request counting
+- `exec_limit`: provider-side execute concurrency limiting
+- `tps`: TPS limiting
+- `adaptivesvc`: adaptive service filter
+- `polaris/limit`: Polaris rate limiting
+- `sentinel`: Sentinel integration for provider and consumer traffic protection
+
+### Security
+
+- `token`: token-based request validation
+- `auth`: request signing and authentication
+- `seata`: Seata distributed transaction propagation
+
+### Observability
+
+- `accesslog`: invocation access logging
+- `metrics`: metrics collection
+- `tracing`: tracing integration
+- `otel/trace`: OpenTelemetry tracing integration
+
+### Extension Note
+
+- `hystrix`: moved to
[dubbo-go-extensions](https://github.com/apache/dubbo-go-extensions/tree/main/filter/hystrix)
+
+## Common Usage
+
+In practice, filters are usually enabled through application config instead of
+being called directly from business code. Typical examples:
+
+- enable a provider filter through `service.filter`
+- enable a consumer filter through `reference.filter`
+- import the filter package so it registers itself via
`extension.SetFilter(...)`
+
+## Notes
-On the provider side, attachments set on the invocation result are propagated
to
-the Triple response trailers for unary calls.
+- Importing a filter package registers it; the filter still needs to be enabled
+ by the corresponding consumer/provider configuration path when applicable.
+- Some filter names differ slightly from their package directory because the
+ runtime key is defined in `common/constant/key.go`.
+- Filters under subdirectories such as `otel/trace` and `polaris/limit` are
+ still ordinary Dubbo-go filters; the subdirectory just reflects feature
+ grouping.
