moul/protoc-gen-gotemplate

protoc-gen-gotemplate

镜像概述和主要用途

protoc-gen-gotemplate 是一个基于 https://developers.google.com/protocol-buffers/ 的通用代码/脚本/数据生成器。作为 Google Protocol Buffers 编译器（protoc）的生成器插件，它解析 protobuf 文件生成抽象语法树（AST），并遍历本地模板目录，使用 https://golang.org/pkg/text/template/ 生成文件。

核心功能和特性

设计理念

• Protobuf 优先：以 Protobuf 定义为基础生成内容
• 无内置模板：仅使用用户定义的模板，灵活性高
• KISS 原则：保持简单直观，易于使用和扩展

底层原理

1. 用户的 protobuf 文件由 https://github.com/google/protobuf/releases 解析
2. 通过 https://github.com/golang/protobuf/tree/master/protoc-gen-go 生成 AST
3. 将 AST 传递给 https://golang.org/pkg/text/template/ 处理每个用户模板文件
4. 模板引擎的函数映射基于 https://github.com/Masterminds/sprig%EF%BC%8C%E5%8C%85%E5%90%AB%E7%B1%BB%E5%9E%8B%E6%93%8D%E4%BD%9C%E3%80%81%E8%BF%AD%E4%BB%A3%E5%92%8C%E7%89%B9%E5%AE%9A%E8%AF%AD%E8%A8%80%E8%BE%85%E5%8A%A9%E5%87%BD%E6%95%B0

使用场景和适用范围

• 需要根据 Protobuf 定义生成代码、配置文件、文档等的项目
• 支持多语言模板生成，适用于各种开发场景
• 适合在 Git 项目中随代码一起管理模板，或维护通用模板库供多个项目使用

详细使用方法和配置说明

基本用法

protoc-gen-gotemplate 需要一个 template_dir 目录（默认 ./templates）。所有以 .tmpl 结尾的文件都会被处理，并按照 template_dir 的目录结构写入目标文件夹，同时移除 .tmpl 扩展名。

示例：

console
$> ls -R
input.proto     templates/doc.txt.tmpl      templates/config.json.tmpl
$> protoc --gotemplate_out=. input.proto
$> ls -R
input.proto     templates/doc.txt.tmpl      templates/config.json.tmpl
doc.txt         config.json

配置选项

可通过以下方式指定自定义选项：

console
$> protoc --gotemplate_out=debug=true,template_dir=/path/to/template/directory:. input.proto

使用提示

• 将模板与项目一起管理，便于在 Git 项目中协作
• 可将通用模板维护在独立仓库，通过版本控制（如 npm 包、Golang vendor 包）供多个项目使用

函数映射（Funcmap）

该项目使用 https://github.com/Masterminds/sprig 库，并扩展了 https://golang.org/pkg/text/template 的内置辅助函数。以下是部分新增函数（非完整列表）：

• https://github.com/Masterminds/sprig 的所有函数
• add、boolFieldExtension、camelCase、contains、divide、fieldMapKeyType、fieldMapValueType
• first、getEnumValue、getMessageType、getProtoFile、goNormalize、goTypeWithPackage
• goType、goZeroValue、haskellType、httpBody、httpPath、httpPathsAdditionalBindings
• httpVerb、index、int64FieldExtension、isFieldMap、isFieldMessageTimeStamp、isFieldMessage
• isFieldRepeated、jsSuffixReserved、jsType、json、kebabCase、last、leadingComment
• leadingDetachedComments、lowerCamelCase、lowerFirst、lowerGoNormalize、multiply
• namespacedFlowType、prettyjson、replaceDict、shortType、snakeCase、splitArray
• stringFieldExtension、stringMethodOptionsExtension、string、subtract、trailingComment
• trimstr、upperFirst、urlHasVarsFromMessage

完整函数列表请参见项目帮助文档。

Docker 部署示例

镜像信息

• 自动构建镜像：https://hub.docker.com/r/moul/protoc-gen-gotemplate/
• 基于 http://github.com/znly/protoc

使用命令

console
$> docker run --rm -v "$(pwd):$(pwd)" -w "$(pwd)" moul/protoc-gen-gotemplate -I. --gotemplate_out=./output/ ./*.proto

相关资源

使用该工具的项目

• https://github.com/moul/kafka-gateway/%EF%BC%9A%E5%9F%BA%E4%BA%8E Go-Kit 的 Kafka 网关/代理（gRPC + http）
• https://github.com/moul/translator%EF%BC%9A%E4%BD%BF%E7%94%A8 Gettext 和 Go-Kit 的翻译微服务
• https://github.com/moul/acl%EF%BC%9AACL 微服务（gRPC/protobuf + http/json）

相关工具

• https://github.com/gponsinet/pbhbs%EF%BC%9A%E5%9F%BA%E4%BA%8E Handlebars 模板的 Protobuf 生成器

许可证

MIT