Go goquery 怎么把一组 HTML 节点映射成结构化数据

在 Go 中解析一组重复的 HTML 卡片时，最容易失控的写法是：先用 Each 遍历，再在外部维护多个切片，最后靠下标把标题、价格和链接拼起来。只要某个字段缺失，几个切片就可能错位。

更稳的做法是先得到一个 Selection，再用 goquery.Map 把每个单节点选择直接转换为一个结构体。这样输入顺序保持不变，字段读取集中在一个回调里，缺失属性也能保留为可判断的状态。

官方地址：https://github.com/PuerkitoBio/goquery

先把重复节点边界选准

这类任务的瓶颈通常不在“怎么填结构体”，而在选择器太宽。假设页面中的商品卡片统一使用 article.product-card，就应该先把这个边界固定下来，再让回调只处理一张卡片。

package main

import (
    "strings"

    "github.com/PuerkitoBio/goquery"
)

func selectCards(html string) (*goquery.Selection, error) {
    // Reader 适合把已经拿到的 HTML 交给 goquery；真实抓取时还应先检查响应状态。
    doc, err := goquery.NewDocumentFromReader(strings.NewReader(html))
    if err != nil {
        return nil, err
    }

    // 只选择重复卡片，避免把页面上的导航、推荐区误算进业务数据。
    return doc.Find("article.product-card"), nil
}

goquery 基于 Go 的 HTML 解析器，官方说明要求调用方保证输入是 UTF-8。选择器也不是完整 jQuery 选择器的替代品，遇到复杂条件时应回到 Cascadia 的实际支持范围确认写法。

让输出结构同时保存值和边界

如果只定义 Link string，调用方无法区分“没有 href 属性”和“href 存在但值为空”。对于后续去重、补链或错误上报，这两个状态往往不是一回事。

type Product struct {
    // Position 用于保留源 HTML 中的顺序，便于定位异常节点。
    Position int
    Title    string
    Price    string
    Link     string
    HasLink  bool
    Valid    bool
}

HasLink 是属性是否存在，Valid 是这张卡片是否满足业务最低要求。把两者分开后，解析层不必假装所有页面都完整，校验层也能决定是跳过、补偿还是记录错误。

用 goquery.Map 一次生成结构体切片

Selection.Map 只能返回字符串切片；当前 goquery 还提供泛型的 goquery.Map，可把每个元素转换成任意类型。回调收到当前索引和只包含当前元素的 *Selection，因此不需要再用索引回头访问整个集合。

package main

import (
    "strings"

    "github.com/PuerkitoBio/goquery"
)

type Product struct {
    // Position 保留源顺序；HasLink 防止把缺失属性误当成空链接。
    Position int
    Title    string
    Price    string
    Link     string
    HasLink  bool
    Valid    bool
}

func mapProducts(cards *goquery.Selection) []Product {
    // 泛型 Map 按 Selection 顺序生成 []Product，不需要并行维护多个切片。
    return goquery.Map(cards, func(index int, card *goquery.Selection) Product {
        title := strings.TrimSpace(card.Find(".product-title").First().Text())
        price := strings.TrimSpace(card.Find(".product-price").First().Text())
        link, hasLink := card.Find("a.product-link").First().Attr("href")

        // Valid 只表达最低业务条件；缺失链接仍保留在结果中供上层处理。
        return Product{
            Position: index,
            Title:    title,
            Price:    price,
            Link:     strings.TrimSpace(link),
            HasLink:  hasLink,
            Valid:    title != "" && price != "",
        }
    })
}

这个映射函数的职责很窄：从单个节点读值并组装记录。它不负责请求网络、不写数据库，也不在回调里抛出无法返回的错误。这样解析与后续决策可以独立演进。

Attr 的布尔值要和空字符串分开

goquery 的 Attr 返回值和布尔值。对链接来说，hasLink == false 表示属性不存在；hasLink == true 但值为空，则表示 HTML 明确写了一个空属性。两种情况都不适合直接拼接成完整 URL。

func keepUsableProducts(products []Product) ([]Product, []int) {
    usable := make([]Product, 0, len(products))
    invalidPositions := make([]int, 0)

    for _, product := range products {
        // 显式区分字段缺失与业务字段不完整，避免静默生成错误链接。
        if !product.Valid || !product.HasLink || product.Link == "" {
            invalidPositions = append(invalidPositions, product.Position)
            continue
        }
        usable = append(usable, product)
    }
    return usable, invalidPositions
}

规模变大后，瓶颈从回调转向选择范围

对少量节点，映射回调的写法已经足够。进入大页面或批量任务后，更值得关注的是四个取舍。

• 把选择器限制在业务容器内，避免对整棵文档树重复匹配。
• 在映射前知道大致数量时预分配结果容量，减少切片扩容。
• 回调里只做读取和轻量清洗，不执行数据库写入或远程请求。
• 错误位置先收集，统一决定重试、丢弃或进入人工处理队列。

如果页面极大，还可以比较 EachIter 与 Map 的可读性和内存策略。EachIter 在 goquery v1.10.0 引入，适合需要边遍历边处理的场景；但要输出完整的结构体切片时，泛型 Map 更直接。

把映射函数放在可复用的数据管道里

在实际工程中，建议把流程拆成“获取 HTML、选择节点、映射结构、业务校验、持久化”五段。映射阶段只依赖 *goquery.Selection，因此可以用固定 HTML 片段覆盖正常卡片、缺少 href、空价格和多余嵌套等输入。

常见问题

Selection.Map 和 goquery.Map 有什么区别？

前者是方法，回调返回 string，结果是 []string；后者是泛型函数，可以返回自定义结构体、数字或其他类型，适合本文的结构化映射。

回调里能不能直接修改原始 HTML？

可以调用 goquery 的操作方法，但如果目标是提取数据，不建议把节点修改和映射混在一起。先读取成值对象，能让结果更容易测试和重放。

没有命中节点时应该报错吗？

这取决于页面契约。对“允许为空”的列表，空切片是正常结果；对“必须存在”的业务页面，应在选择阶段记录缺失，而不是让后续把空切片误当成成功。

核心原则只有一句：让一个输入节点对应一个输出结构体，把顺序、缺失属性和业务有效性都显式保存。这样 goquery 的映射就从一次性的 DOM 遍历，变成了可维护的数据转换边界。