Alanxtl opened a new issue, #3598: URL: https://github.com/apache/dubbo-go/issues/3598
## 背景 Dubbo-Go SDK 中文文档已经覆盖了核心功能，但部分页面还缺少“从文档到可运行 sample”的完整闭环。 本 issue 面向 OSPP 新人，整理一批适合作为入门贡献的文档补强与轻量工具链任务。 整体目标： - 每篇文档都能明确指向对应 sample。 - 文档中包含可复制运行的命令。 - 文档中包含预期输出或验证方式。 - 代码类任务需要补充测试。 ## 任务列表 ### 1. 完善 RPC 快速开始文档 更新文档： - [quickstart/rpc.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/quickstart/rpc.md) 参考示例： - [dubbo-go-samples/helloworld](https://github.com/apache/dubbo-go-samples/tree/main/helloworld) 任务内容： - 校对 server/client 示例代码。 - 统一 `GreetTripleServer`、`GreetService` 等命名。 - 补充如何进入 sample 目录、如何启动 server/client。 - 补充 `curl` 验证方式和预期输出。 - 补充 `protoc-gen-go-triple` 生成代码说明。 ### 2. 完善微服务快速开始文档 更新文档： - [quickstart/microservices.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/quickstart/microservices.md) 参考示例： - [dubbo-go-samples/registry/nacos](https://github.com/apache/dubbo-go-samples/tree/main/registry/nacos) 任务内容： - 说明为什么从 `server.NewServer` 切换到 `dubbo.NewInstance`。 - 补充 Nacos 启动方式。 - 补充 server/client 启动命令。 - 补充如何在 Nacos 控制台验证服务注册。 - 修正文档中的 `dubbo.newInstance`、`dubbo.Insance` 等拼写问题。 ### 3. 完善 Nacos 注册中心文档 更新文档： - [service-discovery/nacos.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/nacos.md) 参考示例： - [dubbo-go-samples/registry/nacos](https://github.com/apache/dubbo-go-samples/tree/main/registry/nacos) 任务内容： - 将现有中英文混杂内容统一为中文。 - 补充 Nacos 本地启动方式。 - 补充 provider 注册配置说明。 - 补充 consumer 发现服务配置说明。 - 补充运行 server/client 的完整命令。 - 补充注册成功后的验证方式。 ### 4. 完善 Zookeeper 注册中心文档 更新文档： - [service-discovery/zookeeper.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/zookeeper.md) 参考示例： - [dubbo-go-samples/registry/zookeeper](https://github.com/apache/dubbo-go-samples/tree/main/registry/zookeeper) 任务内容： - 将现有中英文混杂内容统一为中文。 - 修正示例应用名中误写的 `nacos`。 - 补充 Zookeeper 本地启动方式。 - 补充 provider/consumer 配置说明。 - 补充 `zkCli.sh` 查看注册数据的方式。 - 补充运行 server/client 的完整命令和预期输出。 ### 5. 完善多注册中心文档 更新文档： - [service-discovery/multi_registry.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md) 参考示例： - [dubbo-go-samples/registry/nacos](https://github.com/apache/dubbo-go-samples/tree/main/registry/nacos) - [dubbo-go-samples/registry/zookeeper](https://github.com/apache/dubbo-go-samples/tree/main/registry/zookeeper) 任务内容： - 补充多注册中心适用场景，例如迁移、灰度、集群隔离。 - 补充 API 配置方式。 - 补充 YAML 配置方式。 - 说明 server 级别、service 级别、client 级别如何选择注册中心。 - 说明同时注册到 Nacos 和 Zookeeper 时的验证方式。 ### 6. 完善 Condition Router 文档 更新文档： - [traffic/condition_router.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/traffic/condition_router.md) 参考示例： - [dubbo-go-samples/router/condition](https://github.com/apache/dubbo-go-samples/tree/main/router/condition) - [dubbo-go-samples/router/static_config/condition](https://github.com/apache/dubbo-go-samples/tree/main/router/static_config/condition) 任务内容： - 补充动态 condition router 的完整运行流程。 - 补充 Nacos 配置项说明，包括 Data ID、Group、配置格式。 - 补充静态 condition router 的 API 使用方式。 - 说明动态配置和静态配置同时存在时的优先级。 - 补充路由生效前后的验证方式。 ### 7. 完善 Script Router 文档 更新文档： - [traffic/script_router.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/traffic/script_router.md) 参考示例： - [dubbo-go-samples/router/script](https://github.com/apache/dubbo-go-samples/tree/main/router/script) 任务内容： - 补充 Script Router 的适用场景。 - 说明 `invokers`、`invocation`、`context` 三个脚本入参。 - 补充 Nacos 配置方式，包括 Data ID、Group、YAML 示例。 - 补充 server/client 启动命令。 - 补充路由命中后的验证方式。 - 说明 Script Router 与 Condition Router 的区别。 ### 8. 完善 Tag Router 文档 更新文档： - [traffic/tag_router.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/traffic/tag_router.md) 参考示例： - [dubbo-go-samples/router/tag](https://github.com/apache/dubbo-go-samples/tree/main/router/tag) 任务内容： - 补充 Tag Router 的适用场景，例如灰度发布、环境隔离。 - 补充 provider 如何打 tag。 - 补充 consumer 如何指定 tag。 - 补充动态规则配置方式。 - 补充完整运行命令和验证方式。 ### 9. 完善 Tracing 文档 更新文档： - [observability/tracing.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/observability/tracing.md) 参考示例： - [dubbo-go-samples/otel/tracing](https://github.com/apache/dubbo-go-samples/tree/main/otel/tracing) - [dubbo-go-samples/otel/tracing/stdout](https://github.com/apache/dubbo-go-samples/tree/main/otel/tracing/stdout) - [dubbo-go-samples/otel/tracing/jaeger](https://github.com/apache/dubbo-go-samples/tree/main/otel/tracing/jaeger) - [dubbo-go-samples/otel/tracing/otlp_http_exporter](https://github.com/apache/dubbo-go-samples/tree/main/otel/tracing/otlp_http_exporter) 任务内容： - 补充 stdout exporter 运行方式。 - 补充 Jaeger exporter 运行方式。 - 补充 OTLP HTTP exporter 运行方式。 - 说明 `dubbo.WithTracing` 常用参数。 - 补充如何查看 trace 结果。 - 补充常见问题，例如 endpoint 配错、采样率未开启等。 ### 10. 完善 Logger 文档 更新文档： - [observability/logger.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/observability/logger.md) 参考示例： - [dubbo-go-samples/logger/level](https://github.com/apache/dubbo-go-samples/tree/main/logger/level) - [dubbo-go-samples/logger/trace-integration](https://github.com/apache/dubbo-go-samples/tree/main/logger/trace-integration) 任务内容： - 补充 zap/logrus 配置说明。 - 补充日志级别配置示例。 - 补充访问日志配置示例。 - 补充 logger 与 tracing 集成示例。 - 说明 `CtxLogger` 的使用场景。 - 说明日志 API 不建议在 init 阶段使用的原因。 ### 11. 完善 Metrics 文档 更新文档： - [observability/rpc_metrics.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/observability/rpc_metrics.md) 参考示例： - [dubbo-go-samples/metrics/prometheus_grafana](https://github.com/apache/dubbo-go-samples/tree/main/metrics/prometheus_grafana) 任务内容： - 补充 Pull 模式运行流程。 - 补充 Pushgateway 模式运行流程。 - 补充 Prometheus 配置说明。 - 补充 Grafana dashboard 导入方式。 - 补充如何访问 `/metrics` 或 `/prometheus`。 - 补充常见问题，例如端口冲突、Docker 网络访问问题。 ### 12. 完善 Kubernetes Probe 文档 更新文档： - [observability/probe.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/observability/probe.md) 参考示例： - [dubbo-go-samples/metrics/probe](https://github.com/apache/dubbo-go-samples/tree/main/metrics/probe) 任务内容： - 补充 liveness/readiness/startup 三类 probe 的语义。 - 补充 Dubbo-Go probe API 配置方式。 - 补充 YAML 配置方式。 - 补充自定义健康检查注册方式。 - 补充 Kubernetes deployment 示例。 - 补充 `curl /live`、`curl /ready`、`curl /startup` 的验证方式。 ### 13. 完善 Streaming 文档 更新文档： - [rpc/streaming.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/rpc/streaming.md) 参考示例： - [dubbo-go-samples/streaming](https://github.com/apache/dubbo-go-samples/tree/main/streaming) 任务内容： - 补充 server streaming、client streaming、bidirectional streaming 的区别。 - 补充 `.proto` 定义说明。 - 补充 server/client 端代码说明。 - 补充 `CloseRequest`、`CloseResponse`、`CloseAndRecv` 的使用场景。 - 补充 stream metadata、header、trailer 的示例。 - 补充运行命令和预期输出。 ### 14. 完善 OpenAPI 文档 更新文档： - [rpc/openapi.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/rpc/openapi.md) 参考示例： - [dubbo-go-samples/rpc/triple/openapi](https://github.com/apache/dubbo-go-samples/tree/main/rpc/triple/openapi) 任务内容： - 补充 Triple OpenAPI 的启用方式。 - 补充 OpenAPI endpoint 访问方式。 - 补充 Swagger UI / Redoc 访问方式。 - 补充 IDL 服务和非 IDL 服务的差异。 - 补充生成 OpenAPI 文档后的验证方式。 ### 15. 完善 Graceful Shutdown 文档 更新文档： - [deployment/graceful_shutdown.md](https://github.com/apache/dubbo-website/blob/master/content/zh-cn/overview/mannual/golang-sdk/tutorial/deployment/graceful_shutdown.md) 参考示例： - [dubbo-go-samples/graceful_shutdown](https://github.com/apache/dubbo-go-samples/tree/main/graceful_shutdown) 任务内容： - 补充 Dubbo-Go 优雅停机的整体流程。 - 补充 provider 侧优雅停机说明。 - 补充 consumer 侧连接摘除说明。 - 补充本地运行与验证方式。 - 补充 Kubernetes 场景下的 `preStop`、`terminationGracePeriodSeconds` 建议。 ### 16. 为 OpenAPI 生成器补充测试 更新代码： - [tools/protoc-gen-triple-openapi](https://github.com/apache/dubbo-go/tree/main/tools/protoc-gen-triple-openapi) 参考文件： - [example/greet.proto](https://github.com/apache/dubbo-go/blob/main/tools/protoc-gen-triple-openapi/example/greet.proto) - [example/greet.triple.openapi.yaml](https://github.com/apache/dubbo-go/blob/main/tools/protoc-gen-triple-openapi/example/greet.triple.openapi.yaml) - [example/greet.triple.openapi.json](https://github.com/apache/dubbo-go/blob/main/tools/protoc-gen-triple-openapi/example/greet.triple.openapi.json) 任务内容： - 增加 `*_test.go`。 - 构造 proto fixture。 - 覆盖 scalar、list、map、enum、message、service method。 - 对 YAML 和 JSON 输出做 golden test。 - 保证测试可通过： ```bash go test ./tools/protoc-gen-triple-openapi/... ``` ### 17. 支持 proto 注释生成 OpenAPI description 更新代码： - [convert.go](https://github.com/apache/dubbo-go/blob/main/tools/protoc-gen-triple-openapi/internal/converter/convert.go) - [schema/util.go](https://github.com/apache/dubbo-go/blob/main/tools/protoc-gen-triple-openapi/internal/converter/schema/util.go) 参考文件： - [example/greet.proto](https://github.com/apache/dubbo-go/blob/main/tools/protoc-gen-triple-openapi/example/greet.proto) 任务内容： - 读取 proto 中 message、field、service、rpc 的注释。 - 将注释写入 OpenAPI 的 `description` 或 `summary`。 - 为该功能补充测试。 - 更新 example 输出文件。 ### 18. 支持 oneof 生成 OpenAPI schema 更新代码： - [schema/util.go](https://github.com/apache/dubbo-go/blob/main/tools/protoc-gen-triple-openapi/internal/converter/schema/util.go) 参考文件： - [example/greet.proto](https://github.com/apache/dubbo-go/blob/main/tools/protoc-gen-triple-openapi/example/greet.proto) 任务内容： - 在 proto fixture 中增加 `oneof` 字段。 - 为 `oneof` 生成合理的 OpenAPI schema。 - 补充 YAML/JSON golden test。 - 更新 example 输出文件。 ## 验收标准 - 每个子任务可以单独提交 PR。 - 文档类任务必须同时引用对应 sample 路径。 - 文档中需要包含可复制运行的命令。 - 文档中需要包含预期输出或验证方式。 - 代码类任务必须包含测试。 - 新增或修改的 Markdown 文档需要保持中文表达一致、术语统一。 - 示例链接不能指向不存在的路径。 ## PR 标题建议 - `docs: improve golang sdk quickstart documentation` - `docs: improve golang sdk service discovery documentation` - `docs: improve golang sdk traffic router documentation` - `docs: improve golang sdk observability documentation` - `test: add tests for triple openapi generator` - `feat: support proto comments in triple openapi generator` - `feat: support oneof schema in triple openapi generator` -- 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]
