Generated by Answer me with HTML 0.5.10 · 2026-11-05 22:19 · ★ Star on GitHub
视觉搜索后端改动:从前端视角逐步读懂
以 f4140a04f 为准,逐步解释取数、保存、导出、错误和测试。
1. 先看目标,再跟着一道题走
这次没有重写整个抓取服务。 业务变化集中在两件事:补齐历史来源,以及导出来源。 原有图片、Query 和 ROI 继续用于本次视觉搜索。
| 原来的能力 | 这次补充 |
|---|---|
| 485 查询会话,得到图搜输入 | 用消息 ID 再查 817,补三个来源字段 |
| 任务已有 penetrate 扩展信息 | 在其中增加 visual_search_source |
| 导出引擎可以按路径读取字段 | TCC 配置三个新导出列 |
| 飞书把普通字符串写进单元格 | history_5_rounds 统一转存 JSON,单元格放链接 |
| 实时同步会更新处理游标 | 转存失败时返回错误,保留游标 |
先用一道示例题贯穿阅读。 消息 ID 为 m-demo,Query 为“这是什么猫?”。 图片 URL 为 https://example.invalid/cat.jpg,ROI 是用户选框。 这些值只用于讲解,不是真实用户数据。
三个字段分别装什么
| 字段 | 可以先这样理解 | 本次后端保证的顶层类型 |
|---|---|---|
| image_prompt_info | 历史 Prompt 与图片来源信息 | JSON 对象或 null |
| search_query_list | 历史拆 Query 信息 | JSON 数组或 null |
| history_5_rounds | 历史消息列表 | JSON 数组或 null |
后端在这里校验顶层对象和数组。 它没有逐项验证数组元素的业务结构。 历史消息里的 message_content 仍可保留为 JSON 字符串。
先分清三类东西
“抓取输入”用于调用目标工具。 “历史来源”用于解释这道题从哪里来。 “环境结果”是本次调用目标工具后得到的结果。 这次增加的三个字段属于历史来源。
2. 用 TypeScript 经验读 Go
先掌握下面这些写法,就能开始阅读此次代码。 表中的 TypeScript 是概念类比,不是逐字翻译。
| Go 写法 | 含义 | 前端类比 |
|---|---|---|
| package service | 当前文件所属的包 | 所属模块 |
| import (...) | 引入标准库或依赖包 | import 依赖 |
| type X struct {...} | 定义有固定字段的数据结构 | 先类比 interface 描述字段 |
| []X | X 类型的切片 | 可以先类比 X[] |
| map[string]interface{} | 字符串键、不同类型的值 | Record<string, unknown> |
| x := value | 声明变量并推断类型,之后可以重新赋值 | let x = value |
| var x X | 先声明一个 X,初始是零值 | 明确类型后等待赋值 |
| nil | 指针、切片、map 等的空值 | 先类比 null |
| &value | 取得 value 的地址 | 把可被写入的目标交给函数 |
| *p | 读取指针指向的值 | 读取引用中的实际对象 |
| if err != nil | 检查函数返回的错误 | 检查失败结果,而不是依赖 catch |
| value, err := fn() | 接收函数的两个返回值 | 接收 result 和 error |
| return value, nil | 返回结果,表示没有错误 | 返回成功结果 |
| defer fn() | 当前函数退出前执行 | 类似 finally 的收尾职责 |
Go 的普通函数可以返回多个值。 JSON 解码、RPC 和存储请求通常都显式返回 error。 调用方需要处理或继续传递这个错误。
struct 类型在 Go 运行时仍有意义。 X{} 才是在创建一个 X 类型的值。 TypeScript 的 interface 在编译后会被移除。
for index, item := range list 用来遍历切片。 continue 跳到下一轮,append 则向切片追加元素。 看到这些写法时,可以先联系前端的循环和数组操作。
方法声明怎么读
func (handler *DouBaoSessionHandler) fetchVisualSearchSourceInfo(c *context.Context, sessionIndex int, messageID string) *visualSearchSourceInfo { info := &visualSearchSourceInfo{} status := "ok" imageState, searchState, historyState := "unavailable", "unavailable", "unavailable"| 这一段 | 含义 |
|---|---|
| handler *DouBaoSessionHandler | 这是 DouBaoSessionHandler 的实例方法 |
| handler | 在函数内访问当前实例,作用接近 this |
| c *context.Context | 沿用现有代码的 Context 指针参数 |
| sessionIndex int | 这条会话在本批数据中的位置,用于日志 |
| messageID string | 向 817 查询的消息标识 |
| *visualSearchSourceInfo | 返回来源结构的指针 |
Context 可以先类比携带 AbortSignal 的请求上下文。 它还可以携带链路标识、截止时间和其他请求信息。 这里的 *context.Context 是旧调用约定,本次没有重构它。
info := &visualSearchSourceInfo{} 创建结构并取得指针。 这个 info 从函数开始就存在。 失败时也能返回它,三个字段随后序列化为 null。
两个 JSON 函数
json.Marshal 把 Go 值编码成 JSON 字节。 它的职责接近 JSON.stringify。 json.Unmarshal 把 JSON 字节填入 Go 变量。 它的职责接近 JSON.parse,再加上目标类型约束。
Unmarshal 需要 &details,是因为它要写入 details。 字段后的 json 标签规定 JSON 名称。 Go 字段名 ImagePromptInfo 对应 JSON 名 image_prompt_info。
3. 第一处接入:什么时候去查 817
阅读入口是 formatVisualSearchData。 它所在的文件原来就有视觉搜索输入构造逻辑。 来源配置命中 doubao_visual_search 前缀时,使用这条路径。
| 步骤 | 原有还是新增 | 作用 |
|---|---|---|
| 检查会话只有一条消息 | 原有 | 沿用当前图搜样本限制 |
| 解码会话中的消息 JSON | 原有 | 得到 Query、图片和消息 ID |
| 没有图片就跳过 | 原有 | 不构造无图输入 |
| miniSizeUrl 处理图片 | 原有 | 生成现有执行链需要的图片 URL |
| fetchVisualSearchSourceInfo | 新增 | 查询三个历史来源字段 |
| 构造 GQuery | 原有 | 继续使用会话消息里的图搜输入 |
| 把来源放进 penetrateMap | 新增 | 随题目保存,而不是混进执行 Prompt |
新增调用的位置
tmpUrl, miniSizeErr := miniSizeUrl(*c, messageTmp.ImageUrl) if miniSizeErr != nil { logs.CtxError(*c, "method[formatData] miniSizeUrl fail, err: %v", miniSizeErr) continue } // 图片有效后再查询展示信息,避免无效图片产生额外请求。 sourceInfo := handler.fetchVisualSearchSourceInfo(c, sessionIndex, messageTmp.EncMessageID)图片处理失败时,continue 跳过当前记录。 这条记录本来就无法形成有效图搜输入。 因此先处理图片,再查询展示信息。
参数 messageTmp.EncMessageID 来自 485 返回的那条消息。 它不是项目 ID,也不是根据 Query 文本猜出来的 ID。 sessionIndex 只用于定位批内位置。 调用参数 []string{messageID} 是一个只装着当前 ID 的切片。
485 与 817 是已有的 RPC 方法
RPC 可以先理解为后端调用另一个后端服务。 这里通过 dp.invoker.engine.QueryWithParams 调用数据平台。 API ID 用来标识数据平台的某个接口。
| 方法 | API ID | 本次的用途 |
|---|---|---|
| getDouBaoSessionRPC | 7389155172762600485 | 继续取得会话及原图搜输入 |
| getDouBaoMessageInfoRPC | 7387617535350391817 | 复用已有方法,按消息 ID 补来源 |
这两个 RPC 方法不是此次新写的。 新增的是图搜格式化过程中的 817 调用点。 每个有效图搜输入会串行查询一次明细。
保留原输入的具体含义
即使 817 里的 Prompt 或图片与 485 不同, GQuery 仍使用原会话的 Query、图片和 ROI。 817 返回的数据单独放到来源信息里。 本次没有把历史五轮对话追加到工具请求。
另一个删除项是 messageIdList。 旧代码只向它追加 ID,后面没有读取或使用它。 删除这段不会改变用户消息过滤规则。
4. 新文件:怎样解析明细、校验身份和处理失败
这个文件主要包含一个结构和两个函数。 按下面的顺序读即可。
D.1 定义要保留的三个字段
const visualSearchSourcePenetrateKey = "visual_search_source"// 历史来源信息由所有抓取环境共享,字段异常返回 null,不阻断抓取。type visualSearchSourceInfo struct { ImagePromptInfo json.RawMessage `json:"image_prompt_info"` SearchQueryList json.RawMessage `json:"search_query_list"` History5Rounds json.RawMessage `json:"history_5_rounds"`}json.RawMessage 是一段保留着 JSON 格式的字节。 这里暂时不把图片信息和历史消息拆成更多 Go 类型。 这样可以保留内层业务字符串和未知子字段。
它不是把数组变成字符串的特殊开关。 合法数组的 RawMessage 序列化后仍是 JSON 数组。 nil 的 RawMessage 序列化后是 null。
D.2 查询明细,然后核对“是不是这道题”
if messageID == "" { status = "missing_message_id" return info } resp, err := handler.getDouBaoMessageInfoRPC(c, []string{messageID}) if err != nil || resp == nil { status = "rpc_failed" return info } var details []struct { EncMessageID string `json:"enc_message_id"` visualSearchSourceInfo } if err := json.Unmarshal([]byte(resp.Data), &details); err != nil { status = "invalid_response_json" return info } // 只接收当前消息的明细,避免串题。 if len(details) != 1 { status = "detail_count_mismatch" return info } if details[0].EncMessageID != messageID { status = "message_id_mismatch" return info } info.ImagePromptInfo, imageState = normalizeVisualSearchSourceField(details[0].ImagePromptInfo, '{') info.SearchQueryList, searchState = normalizeVisualSearchSourceField(details[0].SearchQueryList, '[') info.History5Rounds, historyState = normalizeVisualSearchSourceField(details[0].History5Rounds, '[') if imageState == "invalid" || searchState == "invalid" || historyState == "invalid" { status = "partial" } return info| 代码分支 | 为什么需要 | 结果 |
|---|---|---|
| messageID 为空 | 没有可靠查询条件 | 不请求 817,返回空来源结构 |
| RPC 失败或响应为空 | 下游没有可用结果 | 保留原图搜输入,来源为 null |
| resp.Data 不能解码 | 外部响应不是预期 JSON | 不把坏数据挂到任务上 |
| details 数量不是 1 | 这次只请求了一条消息 | 不随意选第一条 |
| 返回 ID 与请求不同 | 避免把别的消息挂到这道题 | 返回空来源结构 |
| 三字段归一化 | 每个字段有自己的类型约束 | 独立保留有效字段 |
var details []struct 表示临时定义一种数组元素结构。 其中 EncMessageID 与匿名嵌入的 visualSearchSourceInfo 并列。 JSON 解码时,三个来源字段与 enc_message_id 位于同一层。 这里没有增加 sourceInfo 之类的响应包装层。
D.3 为什么有时要解两次 JSON
先看示例中的 history_5_rounds。 817 的 Data 本身是 JSON 字符串。 其中的某个字段还可能是“装着数组 JSON 的字符串”。
{ "enc_message_id": "m-demo", "image_prompt_info": "{\"query\":\"这是什么猫?\"}", "search_query_list": ["橘猫"], "history_5_rounds": "[{\"message_content\":\"历史问题\"}]"}第一次解码处理 Data,得到记录数组。 字段归一化再解开 image_prompt_info 和 history_5_rounds 的外层引号。 已经是原生对象或数组的字段不需要再解一次字符串。
func normalizeVisualSearchSourceField(value json.RawMessage, kind byte) (json.RawMessage, string) { value = bytes.TrimSpace(value) if len(value) == 0 { return nil, "missing" } if value[0] == '"' { var encoded string if err := json.Unmarshal(value, &encoded); err != nil { return nil, "invalid" } value = bytes.TrimSpace([]byte(encoded)) } if len(value) == 0 || bytes.Equal(value, []byte("null")) { return nil, "null" } if !json.Valid(value) || value[0] != kind { return nil, "invalid" } if kind == '{' { return value, "object" } return value, "array"}| 顺序 | 操作 | 可以理解为 |
|---|---|---|
| 1 | TrimSpace | 去掉 JSON 片段前后的空白 |
| 2 | 检查长度 | 缺失字段直接记为 missing |
| 3 | 首字符是双引号时解码字符串 | 去掉外层 JSON 字符串编码 |
| 4 | 处理空值和 null | 统一为不可用字段 |
| 5 | json.Valid | 校验解码后的片段仍是合法 JSON |
| 6 | 检查首字符是对象还是数组 | image 要求对象,其余两项要求数组 |
| 7 | 返回片段和状态 | 调用方同时拿到值与诊断信息 |
kind 参数中的 '{' 和 '[' 是字节字面量。 它们分别代表预期的对象和数组开头。 代码先确认非空,再读取 value[0]。 这里的顺序避免了空切片访问越界。
这个函数只解开字段的外层编码。 历史消息里的 message_content 如果仍是字符串,就继续保留。 它没有递归解析 block,也没有检查数组每一项的角色字段。
D.4 失败为什么不会把整个抓取任务停掉
原有图片、Query 和 ROI 已经形成有效执行输入。 这三个新增字段用于来源展示与导出。 因此此次约定允许来源不可用,同时继续创建原输入。
| 故障范围 | 最终来源 |
|---|---|
| 817 整体失败或消息身份不符 | 三字段都是 null |
| 仅 search_query_list 类型错误 | 这一项为 null,其余有效字段保留 |
| history_5_rounds 返回 [] | 保留 [],不当作缺失 |
这里是明确约定的降级,不是把抓取执行错误都忽略。 原有取数、图片和工具执行仍有各自的失败处理。
D.5 defer 日志在哪里执行
defer func() { log := logs.CtxInfo if status != "ok" { log = logs.CtxWarn } log(*c, "[visual_search_fetch] stage=source_info project_id=%d session_pos=%d status=%s image_prompt_info=%s image_prompt_info_bytes=%d search_query_list=%s search_query_list_bytes=%d history_5_rounds=%s history_5_rounds_bytes=%d", handler.ProjectID, sessionIndex, status, imageState, len(info.ImagePromptInfo), searchState, len(info.SearchQueryList), historyState, len(info.History5Rounds)) }()defer 的闭包在函数退出前执行。 即使前面已经 return,也会打印这一次摘要。 闭包读取退出时最终的 status 和字段状态。 func() { ... } 定义匿名函数,末尾的 () 表示调用。 加上 defer 后,这次调用被安排在当前函数退出前执行。
例如 search_query_list 无效时,status 变为 partial。 日志使用 Warn,并记录三个字段的状态和字节数。 没有把完整历史正文放进这条日志。 len(RawMessage) 统计字节数,这里只是日志,不是导出长度限制。
5. 数据怎样保存,前端和导出又怎样读到
理解这一节时,先把 Query 与 Penetrate 分开。 它们都在 QueryInfo 中,但职责不同。
| 位置 | 内容 | 用途 |
|---|---|---|
| QueryInfo.Query | 原有 QueryFile 编码后的字符串 | 继续构造执行输入 |
| QueryInfo.Penetrate | bbox 与 visual_search_source 编码后的字符串 | 保存来源扩展信息 |
E.1 将来源挂到现有扩展信息
penetrateMap := map[string]interface{}{ consts.BBox: fmt.Sprintf("%.2f,%.2f,%.2f,%.2f", cast.ToFloat64(messageTmp.XMin), cast.ToFloat64(messageTmp.YMin), cast.ToFloat64(messageTmp.XMax), cast.ToFloat64(messageTmp.YMax)), visualSearchSourcePenetrateKey: sourceInfo, } queryTmp, _ := json.Marshal(models.QueryFile{ Query: gQuery.QueryCh, GQuery: gQuery, }) sessionInfoList = append(sessionInfoList, models.QueryInfo{ Query: string(queryTmp), Penetrate: tools.JSONMarshal(penetrateMap), })map[string]interface{} 在这里用于拼装一个 JSON 对象。 原来的 b_box 继续保留。 visual_search_source 是新增键,值是刚才取得的来源结构。 tools.JSONMarshal 把这个 map 编码为字符串。
把 Penetrate 解析一次后,可以看到这样的结构。
{ "b_box": "0.10,0.20,0.80,0.90", "visual_search_source": { "image_prompt_info": {"query": "这是什么猫?"}, "search_query_list": ["橘猫"], "history_5_rounds": [{"message_content": "历史问题"}] }}E.2 本次复用的保存链路
CustomizeQueryList 原来就会重建 QueryInfo。 它把传入的 Penetrate 合并到最终扩展信息。 任务构造再把它放进 EvaluateTaskExtra.Penetrate。 本次没有新建一张来源表,也没有增加数据库字段。
// 人工指定透传的,比代码指定的优先级高 if queryInfo.Penetrate != "" { json.Unmarshal([]byte(queryInfo.Penetrate), &peTmp) } peByte, _ := json.Marshal(peTmp) res.Penetrate = string(peByte)上面这段是复用的旧逻辑。 新增测试会确认:重建 QueryInfo 后,三个字段仍在。 Legacy 任务保存到 Extra,Biz 任务沿用现有 PenetrateJSON 适配。 来源能否产生,仍取决于项目实际命中的来源 Handler。
E.3 详情接口与导出看到的是不同包装层
| 使用方 | 读取路径 | 包装层来自哪里 |
|---|---|---|
| 结果页 | JSON.parse(data.task.penetrate).visual_search_source | 任务详情接口 |
| 导出引擎 | task_info_penetrate.visual_search_source | 导出器组装的内部数据 |
task_info_penetrate 不是数仓原始字段名。 它是导出器解析任务 Penetrate 后放入的内部根节点。 因此 TCC 的 data_idx 必须写完整路径。
| ename | data_idx |
|---|---|
| image_prompt_info | task_info_penetrate.visual_search_source.image_prompt_info |
| history_5_rounds | task_info_penetrate.visual_search_source.history_5_rounds |
| search_query_list | task_info_penetrate.visual_search_source.search_query_list |
三个配置项都使用已有 BaseExportEngine。 它用 gjson 按路径取值,形成导出用的字符串。 TCC 配置不是这九个 Git 文件中的 Go 代码。 配置让现有导出框架知道要读哪一列。
active_app_list 控制生成导出列时是否命中项目应用。 现有字段配置接口没有据此过滤前端选项。 所以其他项目的弹窗也能看到这些字段。
E.4 另外几处日志改动
视觉来源被加入 rawDouBaoRPCLoggingEnabled 的关闭条件。 相关 RPC 日志改为记录概要,不主动打印完整请求响应。 部分错误分支按同一策略输出错误类型。 这项策略不代表所有 SDK 或通用业务日志都会被关闭。
formatVisualSearchData 结束时新增 visual_input_ready 摘要。 它记录来源数、有效产出数和跳过数。 消息 JSON 无法解码时,也有对应的跳过原因。 这些改动用于定位取数阶段,不改变 Query 和图片。
6. 飞书为什么是链接,CSV 为什么仍是 JSON
这次导出改动的入口是 bitableCellValue。 它只负责把某个单元格转换成飞书需要的值。
func (e *ExporterHandlerV2) bitableCellValue(ctx context.Context, appToken string, headerKeys []string, idx int, rawValue string, uploadAttachments bool) (interface{}, error) { headerKey := safeHeaderKey(headerKeys, idx) if uploadAttachments && headerKey == visualSearchHistoryDataIdx && strings.TrimSpace(rawValue) != "" { return e.uploadBitableHistoryJSON(ctx, rawValue) } if isBitableAttachmentOverflowHeaderKey(headerKey) { return rawValue, nil } if !uploadAttachments || !isBitableAttachmentHeaderKey(headerKey) { return rawValue, nil } if appToken == "" { return nil, errors.New("app token is empty") } return uploadBitableAttachmentCell(ctx, appToken, headerKey, rawValue)F.1 只有三个条件同时成立才转存
| 条件 | 作用 |
|---|---|
| uploadAttachments 为 true | 当前在准备真实远端写入;预览路径不做上传 |
| headerKey 精确等于 history 的完整路径 | 只处理这一列,不靠列标题猜字段 |
| TrimSpace 后不为空 | 缺失或空白历史不上传 |
uploadAttachments 是原有参数名。 当前真实飞书写入入口会传 true。 它并不表示 history 已变成附件列。 历史列仍是文本列,里面放下载 URL。
这里已经没有长度判断。 短历史、长历史和 [] 都进入同一个转存方法。 image_prompt_info 与 search_query_list 保留原有 JSON 文本。
F.2 一个函数完成原文校验、上传与链接缓存
func (e *ExporterHandlerV2) uploadBitableHistoryJSON(ctx context.Context, rawValue string) (string, error) { if err := ctx.Err(); err != nil { return "", err } if !json.Valid([]byte(rawValue)) { return "", fmt.Errorf("history_5_rounds is not valid JSON") } digest := sha256.Sum256([]byte(rawValue)) if url, ok := e.bitableHistoryJSONURLs[digest]; ok { return url, nil } // 按内容哈希生成稳定路径,重复历史复用同一文件,不改写格式或解析内层业务字符串。 key := fmt.Sprintf("crawl_exports/%d/history_5_rounds/%x.json", e.Project.Id, digest) if err := dal.PutObject(ctx, "", key, int64(len(rawValue)), strings.NewReader(rawValue), tos.ContentType("application/json; charset=utf-8"), tos.ContentDisposition(`attachment; filename="history_5_rounds.json"`)); err != nil { return "", fmt.Errorf("upload history_5_rounds JSON (%d bytes): %w", len(rawValue), err) } url := consts.GetTosDomain(dal.IsExistInTosClient(ctx, key)) + key if e.bitableHistoryJSONURLs == nil { e.bitableHistoryJSONURLs = make(map[[32]byte]string) } e.bitableHistoryJSONURLs[digest] = url return url, nil按代码顺序,一次只理解一个动作。
| 代码 | 做什么 | 为什么 |
|---|---|---|
| ctx.Err() | 检查任务是否已取消 | 已取消就不继续上传 |
| json.Valid | 校验单元格字符串是合法 JSON | 导出读取数据库数据,不能生成无效 JSON 文件 |
| sha256.Sum256 | 计算完整内容的摘要 | 给这段内容生成稳定标识 |
| 读取 bitableHistoryJSONURLs | 查当前导出是否已上传该内容 | 重复出现时复用链接 |
| fmt.Sprintf 生成 key | 确定对象存储中的文件路径 | 同项目、同内容使用同一路径 |
| dal.PutObject | 把完整字符串写入 TOS | 不截断历史,不改写内层字符串 |
| 拼接下载地址 | 取得可放入飞书的 URL | 单元格保持很短 |
| 初始化并写入缓存 | 记住已成功上传的链接 | 失败时不会缓存假链接 |
SHA-256 是摘要,不是内容加密。 相同字节内容会得到相同摘要。 如果空格或内容变了,摘要也会变化。
crawl_exports/2768479/history_5_rounds/<内容摘要>.jsonmap[[32]byte]string 可以先类比 Map<内容摘要, 下载URL>。 SHA-256 的结果是 32 个字节。 map 初始可以为 nil,读取时可以正常得到“没有命中”。 写入前必须 make,因此这里有一次懒初始化。 url, ok := cache[digest] 同时读取值和是否存在。 ok 为 true 时,直接返回已有链接,不再上传。
缓存属于当前 ExporterHandlerV2。 它不是 Redis,也不是跨进程的全局缓存。 同次导出中重复的历史可以复用链接。 下一次导出仍可使用同一路径保存相同内容。
F.3 两个文件元信息有什么作用
Content-Type 指定 application/json; charset=utf-8。 Content-Disposition 指定下载文件名 history_5_rounds.json。 strings.NewReader(rawValue) 直接读取原始字符串。 这里没有再执行 JSON.stringify,把整个历史包成字符串。
文件保存的是导出器交给它的完整 JSON。 它不会下载 JSON 里面提到的图片和附件。 下载后仍可看到这些资源原来的地址。
F.4 CSV 不变的原因在于没有修改共享数据
bitableRecordsForRows 为飞书新建 recordFields。 链接写入这个新 map,没有覆盖原来的 e.data。 CSV 的 format2Csv 则直接读取 e.data。 它还会处理 JSON 中的逗号、双引号和换行转义。
| 输出位置 | 同一段历史的最终形式 |
|---|---|
| 任务详情接口 | 完整历史数组,位于 penetrate 字符串内 |
| CSV | 完整 JSON 文本 |
| 飞书表格 | 完整 JSON 文件的下载 URL |
| TOS 文件 | 转存前的完整导出 JSON |
7. 错误怎样向上传递,为什么不能跳过一批题
G.1 Go 通常把错误当作返回值
在上传函数中,成功返回 URL 和 nil。 失败返回空字符串和 error。 调用方检查 error 后,决定继续还是退出。
fmt.Errorf 中的 %w 会包装原始错误。 外层补充“上传历史 JSON”和内容字节数。 底层原因仍然保留,可用 errors.Is 继续判断。 它的职责接近给 JavaScript Error 添加 cause。
存储上传复用了 dal.PutObject。 现有 DAL 会对同一对象路径重试,并重建读取器。 新函数没有再增加一套重试循环。
G.2 普通导出与实时同步都要拿到这个错误
单元格构造失败时,bitableRecordsForRows 继续向上返回错误。 它会补充行号、字段名和字段路径。 普通导出记录最终会进入失败状态。
实时同步原来的方法只返回 fields、records 两个值。 构建失败时返回 nil、nil,调用方无法区分原因。 这次把方法改成三个返回值。
func (e *ExporterHandlerV2) ExportBitableFieldsAndRecordsForRealtime(ctx context.Context, appToken string) ([]lark_bitable.BitableField, []lark_bitable.BitableRecord, error) { _, _, fields, records, err := e.exportBitableFieldsAndRecords(ctx, appToken, true) return fields, records, err第三个值就是 error。 这是包内部方法的签名变化,不是新增 HTTP 接口。 唯一的生产调用方也同步修改了接收方式。
writtenRecordCount := 0 fields, records, err := handler.ExportBitableFieldsAndRecordsForRealtime(ctx, job.SpreadsheetToken) if err != nil { _ = jobDAL.RecordTemporaryError(ctx, job.ID, err.Error()) return err }这里的 := 一次接收三个值。 如果 err 非空,先记录临时错误,然后返回。 不会继续执行后面的写表和游标更新。
G.3 用五道题理解 cursor
cursor 表示实时同步已经成功处理到哪里。 假设这批准备导出第 101 至 105 题。 第 105 题的 JSON 上传失败时,这一批没有完整成功。 如果此时把 cursor 推到 105,下次就会跳过未成功的数据。
保留游标是为了下次仍能选到这批数据。 这不代表所有外部写入都有数据库事务回滚。 一批写入中发生部分成功时,仍依赖现有导出机制处理。
代码中的 _ = jobDAL.RecordTemporaryError 采用原有做法。 它忽略的是“记录临时状态”的返回值。 真正导致本批失败的 err 仍然返回给上层。
8. 全部九个文件、测试目的与阅读顺序
业务代码共有五个 Go 文件发生变化。 另外三个测试文件负责说明和验证约束。 还有一个 Markdown 文件记录数据契约。
| 文件 | 这次负责什么 |
|---|---|
| service/gpt_douyin_session.go | 在现有视觉输入流程中接入 817,附加来源并调整日志 |
| service/visual_search_session_detail.go | 定义来源结构,查询明细,核对身份,归一化三个字段 |
| helpers/exporter/handler_v2.go | 增加链接缓存,接入历史单元格转存,透传实时构建错误 |
| helpers/exporter/bitable_history_json.go | 完整 JSON 上传、内容哈希与下载链接 |
| views/download_realtime_timer.go | 接收构建错误,失败时停止推进游标 |
| service/visual_search_session_detail_test.go | 7 个测试,覆盖两阶段取数、字段边界和来源不串题 |
| service/gpt_douyin_session_test.go | 调整日志策略测试,加入视觉来源场景 |
| helpers/exporter/bitable_history_json_test.go | 7 个测试,覆盖统一链接、CSV、缓存、失败和分批写入 |
| service/visual_search_session_detail.md | 记录来源结构、降级规则和导出行为 |
测试不是另一套业务实现
Go 用 TestXxx(t *testing.T) 约定标识测试函数。 mockey.Mock 把外部调用换成可控的测试返回值。 例如模拟 817 返回错 ID,确认代码不会把它挂到任务上。 测试中的 example.invalid 图片和假 TOS 地址不用于生产。
| 测试问题 | 防止什么回归 |
|---|---|
| 两阶段取数后,图片、Query、ROI 是否相同 | 来源补齐意外改变执行输入 |
| 无效图片会不会仍查询 817 | 无用请求增加与来源错配 |
| 一题明细失败会不会丢掉其他有效题 | 局部故障拖垮整批 |
| 单字段异常是否只影响该字段 | 错误地清空其他有效来源 |
| 过滤第一张图片后,来源是否仍对应第二题 | 来源串题 |
| 短历史、长历史、[] 是否统一得到链接 | 长度分支残留 |
| 写过飞书记录后,CSV 是否仍是原文 | 共享数据被 URL 覆盖 |
| 相同历史是否只上传一次 | 重复存储请求 |
| 上传失败是否仍可重试 | 失败链接被误缓存 |
| 实时错误是否返回给调用方 | 失败被当成空结果 |
| 分批写入是否也使用链接 | 只改到旧导出路径 |
这些测试隔离了 RPC、存储和飞书接口。 它们能验证代码分支,不等于真实服务已经验收。 本会话只执行了格式和静态检查,没有运行 Go 测试。 仓库限制本地 Go 验证,不能把未执行的用例说成已通过。
回到编辑器时,按这个顺序点开
| 次序 | 从哪里开始 | 要看懂的事情 |
|---|---|---|
| 1 | gpt_douyin_session.go:1010 | 在哪里增加了 817 调用 |
| 2 | visual_search_session_detail.go:20 | ID、响应数量和三个字段如何处理 |
| 3 | visual_search_session_detail.go:70 | 对象、数组和编码字符串如何统一 |
| 4 | gpt_douyin_session.go:1033 | 来源如何进入 Penetrate |
| 5 | handler_v2.go:1732 | 飞书哪一列需要转存 |
| 6 | bitable_history_json.go:18 | 完整 JSON 怎样变成下载链接 |
| 7 | download_realtime_timer.go:254 | 错误为什么必须在游标前返回 |
| 8 | 对应测试文件 | 用输入和预期检查自己的理解 |
页面代码片段来自当前分支的真实文件。 讲解中的 m-demo 和猫图片地址是示例数据。 代码以 f4140a04f 为准;未来修改后应重新核对行号。