AlexStocks commented on issue #3008:
URL: https://github.com/apache/dubbo-go/issues/3008#issuecomment-3263438483
结合 `dubbo-go1/README.md` 现有内容与提供的代码片段，可进一步挖掘出
**文档与代码衔接断层、核心特性实操缺失、功能状态不明确、边缘场景覆盖不足** 等问题，这些问题可能导致用户在实际开发/生产落地中遇到阻碍：
### 一、核心配置缺失「实操示例」：用户知特性但不会配
#### 1. 动态配置中心（Nacos/ZK）无具体配置示例
#### 问题描述
README 在「Features」中提及“动态配置(Nacos, Zookeeper, etc.)”，但未给出 **任何配置代码或 yaml
片段**。结合代码片段 `config/config_center_config.go` 可知，动态配置需通过 `RootConfig` 初始化
`ConfigCenter` 并绑定监听器，但用户无法从文档中知晓：
- 如何编写 yaml 配置（如 `config-center` 节点的 `protocol`/`data-id`/`group` 字段）；
- 如何在代码中启用动态配置（如调用 `startConfigCenter` 的时机）；
- 配置变更后如何触发服务参数更新（如监听器回调逻辑）。
#### 示例缺失场景
用户想通过 Nacos 动态调整服务超时时间，却不知道 yaml 需配置：
```yaml
config-center:
protocol: nacos
address: 127.0.0.1:8848
data-id: dubbo-go-greet-service
group: DEFAULT_GROUP
file-extension: yaml
```
也不知道代码中需在服务启动前初始化配置中心：
```go
// 文档未提及的关键初始化步骤
rootConfig := config.NewRootConfigBuilder().
SetConfigCenter(/* 配置中心参数 */).
Build()
if err := config.startConfigCenter(rootConfig); err != nil {
// 错误处理
}
```
#### 2. 优雅关闭（Graceful Shutdown）无配置与启用说明
#### 问题描述
代码片段 `graceful_shutdown/shutdown.go` 和 `config/graceful_shutdown.go`
显示，Dubbo-go 支持“等待请求处理完成后关闭服务”，但 README 完全未提及该特性：
- 如何启用优雅关闭（是否需在 yaml 或代码中配置）；
- 关键参数含义（如 `shutdown.timeout` 控制等待多久，`reject-request` 何时触发）；
- 不同角色（服务端/客户端）的优雅关闭差异（如客户端是否需等待未完成调用）。
用户若直接暴力关闭服务，可能导致正在处理的请求失败，而文档未提供规避方案。
### 二、特性与代码「断层」：用户看不到特性的落地方式
#### 1. 流量控制（限流/熔断）无代码示例
#### 问题描述
README 在「Features」中列出“rate limiting（限流）”，但未关联代码中
`filter/exec_limit/filter.go` 的实现：
- 如何配置接口级/方法级限流阈值（如通过 URL 参数 `execute.limit` 或 yaml 配置）；
- 限流触发后的降级策略（如 `rejectedExecutionHandler` 如何自定义）；
- 示例场景（如“限制 `Greet` 方法每秒最大并发 100 次”的具体配置）。
代码中已实现基于并发数的限流逻辑，但用户无法从文档中知晓如何启用，导致特性“看得见用不上”。
#### 2. 服务实例自定义（ServiceInstanceCustomizer）无扩展指南
#### 问题描述
代码片段 `common/extension/service_instance_customizer.go` 和
`registry/service_instance.go` 定义了 `ServiceInstanceCustomizer`
接口，支持自定义服务实例的元数据、权重等，但 README 未提及：
- 该接口的用途（如“给实例添加环境标签 `env: prod`”）；
- 如何实现并注册自定义 `ServiceInstanceCustomizer`（如通过
`extension.SetServiceInstanceCustomizer`）；
- 优先级控制（`gxsort.Prioritizer` 接口如何影响自定义逻辑的执行顺序）。
用户若需根据业务场景调整实例信息（如动态修改权重），无法从文档中获取扩展路径。
### 三、功能状态「不透明」：TODO 与未实现功能无说明
#### 1. 文档未标注「未完成/待优化」功能
#### 问题描述
代码中存在大量 `TODO` 或未实现逻辑，但 README 未说明这些功能的现状，可能误导用户：
- `config/config_loader.go` 的 `GetMetricConfig`：函数体注释 `// todo`，实际返回
`rootConfig.Metrics`（可能未处理空指针），但文档“Observability”章节未提及 Metrics 配置存在待完善点；
- `config/service.go` 的 `SetClientInfoService`：注释 `// todo(DMWangnima):
refactor and implement this function`，但文档未说明该函数暂不可用，用户调用可能无效果；
- `protocol/triple/triple_protocol/codec.go` 的 `protoWrapperCodec`：注释 `//
todo(DMwangnima): add unit tests`，文档未提示该 codec 可能存在稳定性风险。
用户若依赖这些未完善的功能，可能遇到空指针、逻辑异常等问题，而文档未提前预警。
#### 2. Triple 协议「非 IDL 模式」无解释
#### 问题描述
代码片段 `server/options.go` 的 `ServiceOptions` 中有 `IDLMode` 字段（注释“for triple
non-IDL mode”），但 README 完全未提及：
- 什么是“非 IDL 模式”（是否支持不通过 Protobuf 定义接口）；
- 非 IDL 模式的使用场景（如快速原型开发）；
- 如何启用该模式（代码中 `IDLMode` 字段如何赋值，是否有配置参数）。
用户若想尝试无 IDL 开发，无法从文档中获取任何指引。
### 四、跨协议/跨框架互操作「细节缺失」
#### 1. Go 与 gRPC 服务互操作无示例
#### 问题描述
README 提到“支持 gRPC”，代码中也有 `protocol/grpc` 目录（如
`grpc/config.go`、`grpc/internal/helloworld/client.go`），但未给出：
- Go 作为 gRPC 客户端调用 Java gRPC 服务的配置（如如何指定 gRPC 协议、序列化方式）；
- Go 作为 gRPC 服务端被其他语言（如 Python）调用的示例（如 `GrpcGreeterImpl` 如何注册）；
- gRPC 与 Triple 协议的差异（如是否支持流式调用、超时配置是否兼容）。
用户若需与现有 gRPC 生态集成，可能因配置细节缺失导致互调失败。
#### 2. Dubbo 协议序列化配置无说明
#### 问题描述
代码片段 `protocol/dubbo/hessian2/hessian_dubbo.go` 显示 Dubbo 协议默认使用 Hessian2
序列化，但 README 仅提及“Triple 用 Protobuf”，未说明：
- 如何切换 Dubbo 协议的序列化方式（如改为 JSON）；
- 不同序列化方式的兼容性（如 Hessian2 与 Java Dubbo 的版本匹配）；
- 自定义序列化器的扩展路径（如如何实现并注册 `Serializer` 接口）。
用户若需在 Dubbo 协议下使用非默认序列化，无法从文档中获取配置方法。
### 五、工具链「高级用法」覆盖不足
#### 1. dubbogo-cli-v2 缺失「服务代码生成」示例
#### 问题描述
README 提到 `dubbogo-cli-v2` 支持“项目脚手架”，但未给出：
- 如何基于现有 `.proto` 文件生成服务端/客户端代码（如 `dubbogo-cli-v2 generate --proto
greet.proto`）；
- 生成代码的目录结构（如 `api/` 下的 `.pb.go` 和 `.triple.go` 对应什么功能）；
- 如何通过 CLI 启动/停止服务（如 `dubbogo-cli-v2 run server`）。
代码片段 `tools/dubbogo-cli/cmd/testGenCode/template` 显示 CLI 能生成流式服务代码（如
`SayHelloStream`），但文档未关联该能力，用户无法高效使用 CLI 提升开发效率。
#### 2. protoc-gen-go-triple 流式调用生成无示例
#### 问题描述
README 提到 `protoc-gen-go-triple` 生成 Triple 协议代码，但未给出 **流式调用（如双向流、服务端流）** 的示例：
- 如何编写支持流式的 `.proto`（如 `rpc SayHelloStream (stream HelloRequest) returns
(stream HelloReply)`）；
- 生成的流式接口（如 `Greeter_SayHelloStreamServer`）如何实现服务端逻辑；
- 客户端如何调用流式接口（代码示例）。
代码片段
`tools/dubbogo-cli/cmd/testGenCode/template/newDemo/api/samples_api_triple.pb.go`
包含 `SayHelloStream` 接口，但文档未结合该示例说明流式调用的开发流程，用户无法落地流式场景。
### 六、文档与代码「一致性问题」
#### 1. 客户端直连 vs 注册中心发现的混淆
#### 问题描述
README 的客户端示例使用 `client.WithClientURL("127.0.0.1:20000")`（直连模式），但未说明：
- 如何切换到“注册中心发现”模式（如通过 `WithClientRegistryIDs` 配置 Nacos 注册中心）；
- URL 格式是否支持注册中心地址（如 `nacos://127.0.0.1:8848?service=greet.GreetService`）；
- 两种模式的适用场景（开发环境 vs 生产环境）。
代码片段 `client/options.go` 的 `WithClientRegistryIDs`
支持注册中心配置，但文档未关联该函数，用户可能误以为只能直连服务。
#### 2. 服务健康检查无配置说明
#### 问题描述
代码片段 `registry/nacos/service_discovery.go` 显示 Nacos 服务发现支持 `Healthy` 状态判断，但
README 未提及：
- 如何启用服务健康检查（Nacos/ZK 注册中心的配置参数）；
- 健康检查失败后的处理逻辑（如实例是否从服务列表中剔除）；
- 自定义健康检查逻辑的扩展方式（如实现 `HealthChecker` 接口）。
用户在生产环境若需保障服务可用性，无法从文档中获取健康检查的配置方案。
### 总结：需优先补充的关键内容
1. **配置实操示例**：动态配置中心、优雅关闭、限流的 yaml/代码配置；
2. **特性落地指南**：服务实例自定义、非 IDL 模式、健康检查的使用步骤；
3. **功能状态标注**：明确 TODO 功能的可用性（如 `SetClientInfoService` 暂不可用）；
4. **跨生态互操作**：Go 与 gRPC/Java Dubbo 的详细集成示例；
5. **工具高级用法**：dubbogo-cli-v2 代码生成、protoc-gen-go-triple 流式调用示例。
这些补充能解决“特性看得见不会用”“配置无参考”“功能状态不明确”等核心痛点，让文档更贴近生产落地需求。
--
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]
