Alanxtl opened a new issue, #3731: URL: https://github.com/apache/dubbo-go/issues/3731
## 背景 当前 Dubbo Website 的 Go SDK 文档中已有 [AOP 与可扩展机制](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/sourcecode/aop_and_extension.md)，主要介绍： - common/extension 注册中心； - extension.SetFilter / GetFilter； - init() 注册机制； - imports 包； - 自定义 filter、router、protocol、registry 的基本注册方式。 但目前缺少面向用户的 extension 使用文档，尤其没有覆盖 dubbo-go#3687 引入的统一 extension 配置和 option API。 相关实现： - [dubbo-go#3687](https://github.com/apache/dubbo-go/pull/3687) - [dubbo-go-extensions Hystrix](https://github.com/apache/dubbo-go-extensions/tree/main/filter/hystrix) - [dubbo-go-extensions Hystrix migration issue](https://github.com/apache/dubbo-go-extensions/issues/29) ## 需要补充的内容 ### 1. 统一 extension API 说明以下入口的职责和使用场景： ~~~go dubbo.WithExtension(...) client.WithExtension(...) server.WithExtension(...) ~~~ 需要明确： - dubbo.WithExtension 对应 InstanceScope； - client.WithExtension 对应 ClientScope / consumer； - server.WithExtension 对应 ServerScope / provider； - consumer/provider 不需要用户额外传 role； - extension option 由具体扩展包定义； - dubbo-go 核心只接收通用 extension.Option，不提供 WithHystrix 等具体扩展 API。 ### 2. 扩展包导入方式 说明用户应该如何导入 dubbo-go-extensions 中的扩展： ~~~go import "github.com/apache/dubbo-go-extensions/filter/hystrix" ~~~ 需要解释： - 使用 hystrix.WithConfig 等 API 时应使用普通导入； - 扩展包通过 init() 完成 Config 和 filter 注册； - 只依赖 side-effect import 的场景什么时候需要使用空白导入； - 扩展注册名、扩展包名和配置前缀之间的关系； - 用户不需要了解扩展内部的 filter name。 ### 3. Typed option 配置 以 Hystrix 为例，说明如何使用扩展自己的 typed option： ~~~go client.WithExtension( hystrix.WithConfig( hystrix.WithCommandName("greet.GreetService:::Greet"), hystrix.WithTimeout(1000), hystrix.WithMaxConcurrentRequests(10), ), ) ~~~ 需要说明： - option 由扩展包定义； - 多个 option 的应用顺序； - 默认配置、YAML 配置和 typed option 的优先级； - 不同 client/server/instance 之间的配置隔离； - 不支持的 scope 如何报错。 ### 4. YAML 配置 说明如何通过 dubbo.Load() 配置 extension： ~~~yaml dubbo: extensions: hystrix: consumer: "greet.GreetService:::Greet": timeout: 1000 max-concurrent-requests: 10 request-volume-threshold: 5 sleep-window: 5000 error-percent-threshold: 50 provider: "greet.GreetService:::Greet": timeout: 1000 max-concurrent-requests: 10 request-volume-threshold: 5 sleep-window: 5000 error-percent-threshold: 50 ~~~ 需要明确： - consumer 和 provider 配置的选择规则； - instance 级 extension 的配置方式； - command key 中包含 . 和 : 时的写法； - YAML 配置和 typed option 的优先级； - 未注册扩展配置时的错误行为； - 配置中心场景下的加载行为； - 当前 extension 配置修改需要重启的限制（如果该限制仍然存在）。 ### 5. 自定义 extension 在已有 AOP 与可扩展机制文档基础上，补充一个完整的自定义 extension 示例，至少包括： - 自定义 Config； - New() 创建独立配置； - Init(scope) 初始化； - FilterNames(scope) 返回需要加入的 filter； - extension.RegisterConfig / MustRegisterConfig； - extension.SetFilter； - client/server/instance 三种入口的适用范围； - 如何为扩展提供 typed option； - 如何让扩展支持 YAML 配置。 ### 6. Hystrix 示例和迁移说明 结合 [dubbo-go-samples/filter/hystrix](https://github.com/apache/dubbo-go-samples/tree/main/filter/hystrix) 和 [dubbo-go-extensions/filter/hystrix](https://github.com/apache/dubbo-go-extensions/tree/main/filter/hystrix)，补充完整的 Hystrix 使用示例。 需要移除或标记为旧版本的内容： - 直接调用 hystrix.ConfigureCommand； - 手动调用 client.WithFilter("hystrix_consumer")； - 手动调用 server.WithFilter("hystrix_provider")； - 使用 dubbo:consumer: / dubbo:provider: 前缀的 command name。 ## 文档位置 优先更新或扩展： - content/zh-cn/overview/mannual/golang-sdk/sourcecode/aop_and_extension.md - content/zh-cn/overview/mannual/golang-sdk/tutorial/configuration/ - 对应的英文 Go SDK 文档目录 如内容较多，可以新增独立的“Extension 配置与使用”页面，并从以下页面建立链接： - Go SDK 总览； - 配置文件； - AOP 与可扩展机制； - 相关 filter/observability 文档。 ## 验收标准 - [ ] Go SDK 文档包含统一 extension API 的说明； - [ ] 文档覆盖 dubbo/client/server 三种 extension 入口； - [ ] 文档说明扩展包导入方式和 init() 注册机制； - [ ] 文档包含 typed option 示例； - [ ] 文档包含 consumer/provider/instance YAML 示例； - [ ] 文档说明配置优先级和 scope 选择规则； - [ ] 文档包含 Hystrix 完整示例； - [ ] 中英文文档内容保持一致； - [ ] 文档中的代码和 YAML 可以与 dubbo-go#3687 合并后的实现对应； - [ ] 文档链接、示例路径和版本信息有效。 ## 非目标 本 issue 只负责文档，不修改 extension API、Hystrix 实现或 samples 代码。 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
