Go Goldmark 多次转换时为什么不能复用可变解析上下文

如果一个 Go 服务长期复用 Goldmark 实例，却在自定义解析时把同一个 parser.Context 传给多次转换，第二次请求出现引用、自动 ID 或扩展状态异常，根因通常不是 Markdown 实例本身，而是把“单次解析状态”提升成了跨请求共享状态。

官方地址：https://github.com/yuin/goldmark

可以复用稳定的 goldmark.Markdown 配置和 Parser/Renderer；不要复用可变的 parser.Context。直接调用 parser.Parse 时，每次转换创建新的 Context，或省略 parser.WithContext 让 Goldmark 为本次解析自动创建。

• Goldmark 的 Markdown 对象保存解析器、渲染器和扩展配置，适合长期持有。
• parser.Context 由解析过程读写，官方文档把它定义为单次 parse invocation 的状态容器。
• Context 里不只有自定义 key/value，还包括引用、ID、分隔符和打开中的块等状态。
• 简单 Markdown 可能暂时看不出问题，但自定义扩展、引用定义、自动 ID 和并发请求会放大状态串线。

第二次转换为什么开始出现异常

这类问题通常从一个看似合理的优化开始：服务启动时创建一个 Context，之后每次请求都把它传给 parser.WithContext。第一次文档转换正常，第二次转换却可能出现引用命中旧文档、标题 ID 继续递增，或者扩展从 Context 读到上一轮留下的对象。

影响面不一定是每篇文章都立刻错。没有引用、没有自动 ID、扩展也不向 Context 写入状态时，复用后的输出可能看起来正常。这种“偶尔正常”反而容易让问题被误判成渲染器或输入文本问题。

先把 Markdown 配置和 Context 分开

Goldmark 的官方源码把两类对象放在不同层次：goldmark.Markdown 持有 Parser、Renderer 和扩展配置；parser.Parse 接收可选的 ParseOption，其中 parser.WithContext 才会覆盖默认上下文。如果没有传入 Context，解析器会在这次 Parse 中创建新的 parser.NewContext()。

因此，正确的复用边界是“配置可复用，解析状态按次创建”。如果业务只需要把 Markdown 转成 HTML，优先复用一个已经配置好的 goldmark.Markdown，不要为了缓存而自行维护 Context。

可变 Context 里到底保存了什么

官方 parser.Context 接口包含 key/value 存储、引用表、ID 集合、当前块偏移、分隔符链和打开中的块。它不是只读配置，也不是一个可以清空几个字段就安全复用的轻量参数对象。

自定义 BlockParser、InlineParser、ParagraphTransformer 或 ASTTransformer 都可以通过 Context 在同一次解析的不同阶段传递数据。若把它跨请求保存，扩展无法再区分“本次解析写入的值”和“上一份文档留下的值”。

错误写法：把 Context 当成全局缓存

下面的写法把解析上下文放进服务对象，第二次调用会继续使用第一次调用修改过的状态。注释只说明关键风险，不把每一行都机械标注。

package main

import (
    "bytes"

    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/parser"
    "github.com/yuin/goldmark/text"
)

type Converter struct {
    md  goldmark.Markdown
    ctx parser.Context // 错误：Context 会被多次 Parse 共享
}

func (c *Converter) Convert(source []byte) ([]byte, error) {
    var out bytes.Buffer
    reader := text.NewReader(source)
    doc := c.md.Parser().Parse(reader, parser.WithContext(c.ctx))
    if err := c.md.Renderer().Render(&out, source, doc); err != nil {
        return nil, err // 保留渲染错误，避免返回半成品
    }
    return out.Bytes(), nil
}

func newBadConverter() *Converter {
    md := goldmark.New()
    return &Converter{
        md:  md,
        ctx: parser.NewContext(), // 这个实例会跨请求存活
    }
}

问题在于 ctx 的生命周期超过了一次 Parse。即便某次输入没有触发明显差异，Context 仍可能已经被扩展、引用解析或 ID 生成逻辑修改。

修复写法：每次解析创建新的 Context

修复不需要每次重建全部 Goldmark 配置，只需要把 Context 的创建放进一次转换的边界内。这样可以继续复用 Parser 和 Renderer 的稳定配置，同时让每次解析拥有独立状态。

package main

import (
    "bytes"

    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/parser"
    "github.com/yuin/goldmark/text"
)

type SafeConverter struct {
    md goldmark.Markdown // 稳定配置可复用，Context 不放在这里
}

func (c *SafeConverter) Convert(source []byte) ([]byte, error) {
    var out bytes.Buffer
    reader := text.NewReader(source)
    ctx := parser.NewContext() // 每次 Parse 都创建单独的可变状态
    doc := c.md.Parser().Parse(reader, parser.WithContext(ctx))
    if err := c.md.Renderer().Render(&out, source, doc); err != nil {
        return nil, err // 渲染失败时不返回不完整 HTML
    }
    return out.Bytes(), nil
}

如果没有自定义解析器需要读写 Context，还可以直接使用 md.Convert(source, writer)。Goldmark 在没有收到 WithContext 时，会让 Parser 为本次 Parse 创建默认 Context。

并发场景要检查的三个边界

第一，不能把同一个 Context 交给并发请求。Context 内部有 map、切片和当前解析栈，多个 Parse 同时读写会把状态隔离问题进一步变成数据竞争。

第二，不能只清空自定义 key 就认为已经重置。引用表、ID 集合、分隔符链和扩展私有状态可能仍然属于上一轮生命周期；“清理后复用”比每次新建更难证明。

第三，要区分 Parser/Renderer 配置是否被动态修改。稳定配置可以在启动时完成并长期使用；如果请求期间调用 AddOptions 或改变扩展配置，也应把它视为共享可变状态另行加锁或改成不可变配置。

复查时看哪些信号

排查时可以先记录同一 Context 是否出现在两次 Parse 调用中，再分别使用包含引用定义、重复标题和自定义扩展状态的输入做回归。目标不是证明每个输入都会失败，而是确认每次解析是否拥有独立 Context。

常见问题

Goldmark 的 Markdown 实例能不能复用？

可以复用稳定配置好的 Markdown 实例；本文限制的是可变 parser.Context 的跨解析复用，不是要求每次都重建 Markdown。

省略 WithContext 就一定线程安全吗？

省略它能避免显式共享 Context，因为 Parser 会为本次 Parse 创建默认 Context；但请求期间仍不要动态修改共享 Parser/Renderer 配置，扩展自身的全局可变状态也要单独处理。

为什么我的简单示例复用 Context 也没出错？

简单输入可能没有触发引用、自动 ID 或扩展状态，所以问题暂时不可见。应使用能覆盖这些状态的独立输入做回归，而不是把一次正常输出当作复用安全的证明。

可以通过清空 Context 来继续用吗？

不建议。Context 的字段和扩展写入点较多，清空策略容易遗漏；每次创建新的 parser.NewContext() 更容易建立和维护生命周期边界。