告别手写文档：用grpcurl+protoc-gen-doc打造自动化gRPC接口文档

【免费下载链接】grpcurl Like cURL, but for gRPC: Command-line tool for interacting with gRPC servers 项目地址: https://gitcode.com/gh_mirrors/gr/grpcurl

你是否还在为gRPC服务编写枯燥的接口文档？手动维护 protobuf 文件与文档的同步是否让你苦不堪言？本文将带你掌握一套自动化方案，通过 grpcurl 与 protoc-gen-doc 工具链，实现从 protobuf 定义到交互式文档的全流程自动化，让团队协作效率提升10倍。

读完本文你将学会：

• 使用 grpcurl 快速探索和测试 gRPC 服务接口
• 通过 protoc-gen-doc 从 proto 文件生成美观的 HTML 文档
• 构建完整的文档自动化流程，确保文档与代码同步更新
• 解决文档维护中的常见痛点，如版本不一致、格式混乱等问题

为什么需要自动化gRPC文档

在微服务架构中，gRPC 凭借其高效的二进制传输和强类型契约成为服务间通信的首选方案。然而，接口文档的维护却常常成为开发团队的痛点：

• 手动编写低效易错：每次接口变更都需要同步更新文档，耗时且容易遗漏
• 格式不统一：不同开发者编写的文档风格各异，降低团队协作效率
• 缺乏交互能力：静态文档无法直接测试接口，开发者需要额外工具验证功能

grpcurl 作为 gRPC 生态中的 "curl" 工具，不仅可以便捷地测试 gRPC 服务，还能配合 protoc-gen-doc 实现文档的自动化生成，完美解决上述问题。

grpcurl：gRPC接口的功能工具

grpcurl 是一个命令行工具，允许你与 gRPC 服务器进行交互，就像使用 curl 与 REST API 交互一样简单。它支持服务发现、消息发送和响应处理等核心功能，是 gRPC 开发调试的必备工具。

安装grpcurl

grpcurl 提供多种安装方式，选择适合你的环境：

通过源码安装（需要Go环境）：

go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

Docker方式：

docker pull fullstorydev/grpcurl:latest
docker run fullstorydev/grpcurl api.grpc.me:443 list

完整安装指南可参考项目 README.md。

核心功能速览

grpcurl 最常用的功能包括服务列表查询、方法描述和接口调用：

列出服务：

grpcurl localhost:8787 list

查看服务方法：

grpcurl localhost:8787 list my.custom.server.Service

调用gRPC方法：

grpcurl -d '{"id": 1234, "tags": ["foo","bar"]}' \
    grpc.server.com:443 my.custom.server.Service/Method

这些功能不仅简化了 gRPC 接口的测试流程，还为文档生成提供了数据基础。

protoc-gen-doc：从protobuf到精美文档

protoc-gen-doc 是一个 Protobuf 插件，能够从 .proto 文件中提取注释和接口定义，生成多种格式的文档，包括 HTML、Markdown 和 JSON 等。结合 grpcurl，我们可以构建完整的 gRPC 文档解决方案。

工作原理

protoc-gen-doc 的工作流程如下：

安装与使用

首先安装 protoc-gen-doc 插件：

go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest

然后使用以下命令从 proto 文件生成文档：

protoc --doc_out=. --doc_opt=html,index.html internal/testing/test.proto

这条命令会读取 internal/testing/test.proto 文件，生成一个名为 index.html 的文档。

实战：构建完整的文档自动化流程

现在，让我们通过一个实际案例，展示如何结合 grpcurl 和 protoc-gen-doc 构建自动化文档系统。

1. 准备带注释的proto文件

首先，确保你的 proto 文件包含清晰的注释。以 internal/testing/test.proto 为例，其中定义了 TestService 服务：

// A simple service to test the various types of RPCs and experiment with
// performance with various types of payload.
service TestService {
  // One empty request followed by one empty response.
  rpc EmptyCall(Empty) returns (Empty);

  // One request followed by one response.
  // The server returns the client payload as-is.
  rpc UnaryCall(SimpleRequest) returns (SimpleResponse);
}

这些注释将被 protoc-gen-doc 提取并显示在生成的文档中。

2. 生成HTML文档

使用 protoc-gen-doc 从 proto 文件生成 HTML 文档：

protoc --doc_out=docs --doc_opt=html,grpc-docs.html \
  -Iinternal/testing internal/testing/test.proto

这将在项目根目录下创建 docs 文件夹，并生成 grpc-docs.html 文件。

3. 使用grpcurl验证接口

在文档生成后，使用 grpcurl 验证接口是否与文档一致：

# 启动测试服务器
go run internal/testing/cmd/testserver/testserver.go

# 查看服务列表
grpcurl -plaintext localhost:8787 list

# 调用UnaryCall方法
grpcurl -plaintext -d '{"response_type": 0, "response_size": 1024}' \
  localhost:8787 testing.TestService/UnaryCall

4. 集成到CI/CD流程

为确保文档与代码同步更新，将文档生成步骤添加到 CI/CD 流程。创建一个简单的 Makefile 目标：

generate-docs:
    mkdir -p docs
    protoc --doc_out=docs --doc_opt=html,grpc-docs.html \
      -Iinternal/testing internal/testing/test.proto

现在只需运行 make generate-docs 即可更新文档。将此命令添加到你的 CI/CD 配置中，如 GitHub Actions 或 GitLab CI，实现文档的自动更新和部署。

常见问题与解决方案

服务不支持反射怎么办？

如果 gRPC 服务未启用反射，grpcurl 需要 proto 文件或 protoset 文件才能工作：

# 使用proto文件
grpcurl -import-path internal/testing -proto test.proto list

# 使用protoset文件
protoc --descriptor_set_out=test.protoset --include_imports test.proto
grpcurl -protoset test.protoset list

如何处理复杂的导入路径？

对于包含多个导入路径的项目，使用 -I 标志指定所有必要的导入路径：

protoc --doc_out=docs --doc_opt=html,grpc-docs.html \
  -I. -Ithird_party/googleapis \
  internal/testing/test.proto

生成的文档如何添加自定义样式？

protoc-gen-doc 支持自定义模板，创建一个 HTML 模板文件并使用 --doc_opt 指定：

protoc --doc_out=docs --doc_opt=html,grpc-docs.html,template.tmpl \
  internal/testing/test.proto

总结与展望

通过 grpcurl 和 protoc-gen-doc 的组合，我们实现了 gRPC 接口文档的自动化生成和验证，解决了手动文档维护的诸多痛点。这一方案不仅提高了开发效率，还确保了文档的准确性和时效性。

未来，你可以进一步扩展此方案：

• 添加权限控制，保护敏感接口文档
• 集成Swagger UI，提供更丰富的交互体验
• 实现文档版本控制，支持多版本接口文档管理

希望本文介绍的方法能帮助你构建更高效的 gRPC 开发流程。如果你有任何问题或改进建议，欢迎在项目 GitHub 仓库 提交 issue 或 PR。

别忘了点赞收藏本文，关注作者获取更多 gRPC 开发技巧！下一篇我们将探讨 gRPC 性能优化实战，敬请期待。

【免费下载链接】grpcurl Like cURL, but for gRPC: Command-line tool for interacting with gRPC servers 项目地址: https://gitcode.com/gh_mirrors/gr/grpcurl