Golang从Go源码生成环境变量文档插件库envdoc的使用

简介

envdoc是一个用于从Go结构体生成环境变量文档的工具。它会提取结构体中与env标签相关联的注释，并创建包含详细文档的Markdown、纯文本或HTML文件。

安装

Go >= 1.24

添加envdoc工具并安装：

go get -tool github.com/g4s8/envdoc@latest
go install tool

在代码中添加go:generate指令：

//go:generate envdoc -output config.md
type Config struct {
    // ...
}

生成文档：

go generate ./...

Go < 1.24

使用go run运行：

//go:generate go run github.com/g4s8/envdoc@latest -output environments.md
type Config struct {
    // ...
}

或者先安装二进制文件：

go install github.com/g4s8/envdoc@latest

然后在代码中使用：

//go:generate envdoc -output environments.md
type Config struct {
    // ...
}

使用

基本用法：

//go:generate envdoc -output <output_file_name>

可用参数：

• -dir (path string, 可选) - 指定搜索文件的目录
• -files (glob string, 可选) - 指定要处理的文件名的glob模式
• -types (glob string, 可选) - 指定要处理的类型名称的glob模式
• -target (enum(caarlos0, cleanenv) string, 可选, 默认caarlos0) - 设置环境库目标
• -output (path string, 必填) - 生成的文档的输出文件名
• -format (enum(markdown, plaintext, html, dotenv, json) string, 可选) - 文档的输出格式
• -no-styles (bool, 可选) - 如果为true，html格式将不包含CSS样式
• -env-prefix (string, 可选) - 为所有环境变量设置额外的全局前缀
• -tag-name (string, 可选, 默认: env) - 使用自定义标签名代替env
• -tag-default (string, 可选, 默认: envDefault) - 使用"default"标签名代替envDefault
• -required-if-no-def (bool, 可选, 默认: false) - 如果没有设置默认值，则将属性设置为必需
• -field-names (bool, 可选) - 如果未指定env:标签，则使用字段名作为环境变量名
• -debug (bool, 可选) - 启用调试输出

示例

假设有以下Go文件config.go：

package foo

//go:generate envdoc --output env-doc.md
type Config struct {
  // Port to listen for incoming connections
  Port int `env:"PORT,required"`
  // Address to serve
  Address string `env:"ADDRESS" envDefault:"localhost"`
}

执行go generate后，会在env-doc.md文件中生成以下文档：

Environment Variables

• PORT (required) - Port to listen for incoming connections
• ADDRESS (default: localhost) - Address to serve

## 兼容性

envdoc与以下库兼容：
- 完全兼容: caarlos0/env
- 完全兼容: ilyakaznacheev/cleanenv
- 部分兼容: sethvargo/go-envconfig
- 部分兼容: joeshaw/envdecode

## 贡献

如果您发现任何问题或有改进建议，欢迎提交issue或pull request。

## 许可证

本项目采用MIT许可证。