Go go-pretty 怎样把同一组行导出成 Markdown 表格

Go 使用 github.com/jedib0t/go-pretty/v6/table 时，可以先把表头、同一组数据行和可选页脚追加到一个 table.Writer，再调用 RenderMarkdown() 得到 Markdown 表格。最小路径就是“创建 Writer → AppendHeader → AppendRows → RenderMarkdown”；如果希望 Markdown 源码中的列更整齐，再设置 Style().Markdown.PadContent。

官方地址：https://pkg.go.dev/github.com/jedib0t/go-pretty/v6/table

下面的示例固定使用 v6 模块路径，重点是“同一组行”的列结构保持一致：每行都按“服务、状态、耗时、备注”四列提供数据。

先固定 v6 模块路径和 Writer

go-pretty 的当前主版本是 v6，导入路径中的 /v6 不能省略。命令行初始化依赖时，可以把版本约束交给 Go Modules；正文里的表格构造则只依赖 table 子包。

# 在已有 Go module 中添加 v6 依赖
go get github.com/jedib0t/go-pretty/v6

# 查看当前 module 记录的依赖版本
go list -m github.com/jedib0t/go-pretty/v6

table.NewWriter() 返回一个 Writer 接口。后续的追加操作都写入同一个对象，最后由它统一渲染；不要为表头、数据行和页脚分别创建 Writer，否则它们不会自然组成一张表。

用 AppendHeader 和 AppendRows 保持同组列结构

表头通过 AppendHeader 写入，数据行可以一次性传入 AppendRows。每个 table.Row 本质上是一组单元格，单元格可以混合整数、字符串等值，但业务上最好让每一行的列数和列含义固定。

package main

import (
    "fmt"

    "github.com/jedib0t/go-pretty/v6/table"
)

func main() {
    tw := table.NewWriter()

    // 表头定义列的顺序，后面的数据行按同一顺序提供值。
    tw.AppendHeader(table.Row{"服务", "状态", "耗时(ms)", "备注"})

    // 一次追加同一组数据行，避免每一行拥有不同的业务列含义。
    tw.AppendRows([]table.Row{
        {"api", "ready", 38, "主节点"},
        {"worker", "busy", 126, "处理中"},
        {"cache", "ready", 9, "命中"},
    })

    // Markdown 只需要数据表时直接渲染，不会输出终端边框字符。
    markdown := tw.RenderMarkdown()
    fmt.Print(markdown)
}

这里的关键不是先拼接 | 字符，而是让 Writer 统一掌握列顺序。AppendRows 接收一组 Row，适合把已经整理好的切片一次放进去；如果数据是流式到达，也可以改用 AppendRow 逐条追加，最后仍然调用同一个 RenderMarkdown。

如果某条记录缺少字段，不要靠改变 Row 长度来表达业务状态。更稳妥的方式是填入空字符串、unknown 或业务约定的占位值，保持 Markdown 表格的列数稳定。

需要汇总时再追加页脚

页脚不是必须项，但当表格需要展示总数、平均值或汇总说明时，可以通过 AppendFooter 加入。页脚也应遵守同一列布局，空缺列显式放空字符串。

// 在前面追加完数据行后加入汇总行。
tw.AppendFooter(table.Row{"", "", "总计", 173})

// 只渲染 Markdown，不改变 Writer 中已有的表头、数据行和页脚。
fmt.Print(tw.RenderMarkdown())

页脚的作用是输出汇总信息，不是让库替你计算业务指标。示例中的 173 应由调用方根据真实数据计算后传入；如果还需要平均耗时、失败数等指标，应先在 Go 代码中完成计算，再把结果作为一个完整的 Row 追加。

用 PadContent 改善 Markdown 源码的可读性

RenderMarkdown() 默认已经生成可渲染的 Markdown。若要让原始文本中的列宽更整齐，可以打开 MarkdownOptions.PadContent。这个选项只是在源码中补齐空格并延长分隔线，不会改变 Markdown 渲染出来的表格语义。

// PadContent 只改善 Markdown 源码的视觉对齐，不改变表格数据。
tw.Style().Markdown.PadContent = true

// 输出适合写入 README、工单或文档文件的 Markdown 文本。
markdown := tw.RenderMarkdown()
fmt.Println(markdown)

当表格单元格长度差异很大时，开启这个选项会让源码更宽，提交记录也可能出现更多空格变化。机器消费时通常不需要开启；人工维护的 README、设计记录或生成后还要被审阅的文档，则可以开启。

处理空数据、列数和特殊字符边界

实际接入时，表格能否稳定使用，往往取决于输入约定，而不是渲染调用本身。

• 空数据：可以只保留表头，也可以在业务层先判断并输出“暂无数据”的普通段落；不要把空 Row 当成一条真实记录。
• 列数不一致：尽量在组装 Row 时补齐列，避免同一张表出现错位的业务含义。
• 换行内容：单元格中有换行时，要先确定目标 Markdown 渲染器如何处理；不要仅凭源码中的一行判断最终展示。
• 竖线字符：如果业务字段可能包含 |，应在进入表格前按目标 Markdown 方言设计转义或替换策略，并用固定样例检查输出。
• 大批量数据：Markdown 本身是文本，Writer 需要保留待渲染的数据结构；特别大的结果应考虑分页、截断或改用 CSV 等更适合机器处理的格式。

因此，推荐把“数据整理”和“表格渲染”分开：前者负责列数、空值、汇总和特殊字符约定，后者只负责把已整理的 Row 集合输出成 Markdown。这样更容易在接口返回、README 生成和日志摘要之间复用。

几个容易混淆的问题

为什么已经有 Render() 还要用 RenderMarkdown()？Render() 面向终端的 ASCII/Unicode 表格，RenderMarkdown() 面向 Markdown 文本；两者的输出格式不同，不能用终端边框字符串替代 Markdown。

AppendRows 会自动把不同长度的行变成业务上正确的列吗？它负责追加 Row 集合，不知道你的业务列含义。调用方仍应保证列数和字段顺序，缺失值要在组装数据时明确处理。

PadContent 会改变网页里显示的表格宽度吗？它主要改变 Markdown 源码的空格和分隔线长度，渲染器是否显示这些空格取决于 Markdown 解析和页面样式，不能把它当作像素级排版配置。

同一个 Writer 可以先输出终端表格再输出 Markdown 吗？可以针对同一个 Writer 分别调用不同的渲染方法；但要注意所有渲染方法都读取当前 Writer 的状态，若要输出不同数据集，应先重置或新建 Writer，避免把上一组行混入结果。

归纳起来，Go go-pretty 导出 Markdown 的最小可靠做法是：固定 v6 导入路径，用一个 Writer 组织表头和同组 Row，按需加入页脚，最后调用 RenderMarkdown()；只有在需要人工阅读源码时再打开 Style().Markdown.PadContent。列数、空值和字段转义仍然属于业务层的输入契约。