Google 搜索 API TypeScript：设计一个值得信赖的契约

Emily Chen

Advanced Data Extraction Specialist

30-Oct-2026

摘要：

TypeScript 声明描述的是对搜索数据的期望。 它并不能保证接收到的值就满足这种期望。
搜索应用既需要“结构契约”，也需要“含义契约”。 一个有效链接、一个相关候选项和一个被接受的来源代表的是不同状态。
缺失的观测应当与空结果集保持可区分。 把所有不确定性都转换为空数组，会让仪表盘更容易渲染、却更难以信任。
规范化的应用模型应当保留每个决策的来源。 记录候选项是如何被解释的，而不是把应用中的标签伪装成提供方字段。
契约变更需要消费方审核。 一个方便的映射调整就可能改变历史指标的含义，即使 UI 依然能够正常加载。

引言：有类型的结果依然需要解释

TypeScript 能够描述一个搜索结果对象，却不能确定该对象对某个研究任务是否有意义。编译器对一个值的理解，与分析人员对一份证据的理解，回答的是不同问题。

一个 Google Search API 的 TypeScript 集成需要有意识地把这两个问题关联起来。开发者希望得到可预测的应用对象。产品团队希望实现有用的来源发现。分析人员希望知道某个观测是否支持一个结论。一个宽泛的通用 “result” 类型会掩盖这些差异，直到某个仪表盘开始把不确定当成确定来处理时才暴露出问题。

Scrapeless Google Search API 提供结构化的 Google 搜索数据，可以进入这个处理流程。你的应用应当围绕自己真正使用到的数据，定义一个狭义的解释契约。Google Search 解决方案家族提供了多种工作流，而 AI 与 RAG 场景则尤其清楚地体现了“发现候选项”和“接受为证据”之间的区别。

本文围绕这一应用契约展开。这里提出的字段与审核状态，是设计概念，而不是 Scrapeless 响应模式的声明。下面的任何示例都不代表真实执行的 API 响应，也不需要任何未经验证的端点或包来理解这些推理。

将未知输入隔离在可信模型之外

未知的外部输入，只有在经过明确检查之后，才能被纳入可信的应用对象。类型声明可以文档化这一过程的终点，但声明本身不是那个过程。

在输入边界上，先检查接收到的内容在“结构”上是否符合应用的预期。然后再检查这些值是否满足该功能所要求的规则。同样是字符串，它可能在原始类型上毫无问题，却不适合作为目标链接、展示标签或搜索上下文标识符。

TypeScript 对类型注解擦除的解释 说明了为什么注解不会改变运行时行为。其实际含义是：需要设计一个验证边界，而不是假定某个断言类型就能让外部数据在解释时变得安全。

让这个边界保持狭窄。一个研究面板可能需要一个目标地址、一个展示标题和一个观测上下文。它没必要向每个消费方暴露提供方的全部细节。一个更小的可信模型更容易解释，也更容易在产品对用户有更多了解之后进行调整。

不要悄悄丢弃不熟悉的输入然后宣称剩下的对象是“完整的”。要记录下映射过程做了一个“刻意选择”。当后续某个功能需要当初模型并未保留的信息时，这一差异就会变得很有价值。

将结构有效性与证据采纳相分离

结构有效性（shape validity）说明应用可以处理某个候选项；证据采纳（evidence admission）则说明某个候选项可以支撑特定用途。这两类检查应当产生彼此独立的决策。

一个具备可识别目标地址和标题的候选项，可能适合出现在“发现列表”中。但同一个候选项，却可能并不适合作为事实性论断的依据，因为它的来源不清晰、范围无关、或者内容尚未经过审核。把这两类检查合并成一个成功标志，会丢失有用的信息。
为消费特性定义准入策略。研究工作区可以允许用户在保存候选项之前对其进行检查。生成的答案在呈现某个论断之前，可能需要更严格的证据审查。监控报告可以接受某个观测结果，同时排除缺乏可比基线的解读。

对于每一次拒绝，都要保留一个简明的原因，方便责任人据此采取行动。“不支持的目标形式”暗示映射或输入问题。“对此论断的支持不足”则暗示来源审查的问题。这类解释有助于团队改进工作流中的正确环节。

准入决策应当标明其适用范围。被接受用于识别某个组织官方网站的来源，并不会自动被接受用于评估该组织的财务状况。证据质量属于正在回答的问题本身。

模型在不虚构确定性的前提下表达缺失

对于“缺失”，需要一套能够区分“被请求的内容、被观测到的内容以及应用可以解读的内容”的词汇。单靠一个空白展示，是无法承载这些区分的。

设想一个期望得到候选目标的研究类应用。一次完成的观测却没有合适候选，与一次应用无法评估的观测是不同的。这两种情况都可能让结果面板保持空白，但它们应产生不同的解释以及不同的指标处理方式。

先用日常语言描述这些状态，再把它们转化为应用标签。产品可以区分“可用观测结果”、“无可接受候选项”和“观测结果不可用”。这些是拟议中的应用状态，而不是 Scrapeless 响应属性的名称。

不要仅仅因为图表需要一个数值，就用一个看似合理的默认值填充未知量。缺失的位置并不等于较低的位置。不可用的计数并不等于零计数。规范化的模型应当保留不确定性，直到消费特性具备可辩护的解释策略。

W3C 数据质量评估词汇在描述某个数值为何被排除在度量之外时非常有用。该词汇提供概念结构；应用仍需自行定义与其决策相关的质量规则。

在观测结果旁保留查询上下文

查询上下文应与观测结果并置，因为搜索数据一旦与生成它的问题分离，就可能丧失意义。应将上下文视为应用契约的一部分，而不是可选注释。

将经过批准的研究问题与为调查该问题而使用的搜索表述分开存储。用户可以提出一个宽泛的问题，然后将其转化为更窄的搜索任务。保留这两者可以解释这种转化，而不会假装是服务提供方替应用选择了研究策略。

在工作流使用市场和语言选择时，记录被请求的市场和语言。除非应用另行确定了实际观测到的内容，否则应将这些标记为“被请求的上下文”。这种区分可以防止“期望的配置”看起来像是“已验证的结果属性”。

时间也需要明确的含义。任务被请求的时刻、观测被存储的时刻、以及来源中提到的日期，描述的是不同的事件。互联网时间戳规范解决的是时间戳表示问题；它并不替产品决定哪个事件应被视为“最新”。

因此，契约审查应询问界面中每一个时间戳的含义。历史视图可以展示应用观测到某个候选项的时间，而不暗示该目标内容是在同一时刻被创建或发生变更的。

使用 Scrapeless 开始抓取

使用 Scrapeless 为你的网页抓取与自动化工作流加速！
立即注册即可获得 $5 免费额度 —— 无需信用卡。

现在就在 Scrapeless 控制台领取你的免费额度。

在规范化目标的同时保留有用差异

目标规范化应服务于一套明确的身份策略。一个方便的字符串转换，可能会把本应保持区分的观测合并在一起，或把本应放在一起比较的观测拆开。

从应用目的出发。来源发现功能可以按目标身份对候选项分组，同时保留每一次原始观测。监控功能可能需要精确到被观测到的链接来作为证据。审查工作区则可能既关心发布组织，又关心具体页面。
URI 语法和规范化框架解释了标识符的结构以及比较时的上下文。它应该为规范化决策提供参考，而不是被当作删除有意义查询信息或重写每一个地址的一揽子理由。

在应用特定于应用程序的身份规则时，保留原始目标地址。将推导出的身份单独存储，以便审阅者可以检查分组是如何发生的。如果之后规则发生变化，团队就能在不重建已被丢弃观测的前提下，重新评估分组。

一个链接在被观测之后也可能更改目标地址。这就是为什么要把存储的值描述为“被观测到的地址”，而不是对未来内容做出的永久性保证。契约应保证在网络环境不断变化的情况下，历史证据仍然可理解。

从可审阅总体中定义度量

一个可信的度量始于明确的总体和排除策略。仅统计映射之后剩下的内容，可能产生看似惊人的数字，却含义不清。

对于候选覆盖率，要明确哪些已批准任务属于报告期。对于准入质量，要区分经审阅者检查过的候选与仅被展示过的候选。对于处理质量，要识别那些无法进入可信应用模型的值。这些总体回答的是不同问题，不应共享一个未加说明的分母。

还要描述计量单位本身。在多个任务中被反复观测到的目标地址，与唯一一次被纳入项目的目标地址并不相同。一个被接受的候选，与一个由已审阅材料支持的主张也不相同。应用不应把这些单位折叠成一个笼统的“找到的来源”标签。

使用 W3C 溯源关系模型来思考从输入活动到解释后输出的路径。实践中，审阅者应能把一个已报告的度量，与其中包含的观测和决策关联起来。

当契约发生变化时，要记录历史度量是否仍具可比性。新的准入策略可能会改进应用，同时让趋势出现不连续。展示这种不连续，要比悄悄重写序列含义更诚实，也更有用。

与消费者一起审阅契约变更

当契约变更改变了下游用户可推断出的信息时，它就是一次产品变更。对有类型的消费者来说，编译器兼容性是必要条件，但对解释层面的兼容性却远远不够。

假设应用开始把来自相关查询的候选合并为一个展示分组。UI 也许仍然会收到一个属性熟悉的对象列表。但此时计数代表的是分组后的目标，而不是被观测到的候选。技术迁移可以很顺利，而报表解读却可能变得错误。

要与使用派生数据的人一起审阅这项变更。询问分析师是否仍然能解释一份历史报告，客服是否能描述一个空状态，以及模型辅助功能是否还能识别支撑其答案的来源。这些都是消费者接受度问题。

对外部映射和应用解释策略分别使用单独的版本说明。它们可能因不同原因发生变化。提供方表示层的更新，可能需要调整映射而不改变准入规则；产品策略更新，则可能改变准入而不改变传输方式。

搜索参与者架构为如何将数据获取与消费该数据的应用分离提供了有用背景。在你的契约中保持这种分离，这样未来数据源的变更就不会自动重写产品的证据标准。

在扩展模型前先写一份证据词典

证据词典能让没有参与实现的人也能理解应用模型。每个条目都应解释其含义、来源、不确定性以及允许的使用方式。

对于目标地址，要描述该值是被观测到的、规范化的，还是人工选取的。对于上下文，要说明该值来自用户、应用策略，还是一次已确认的观测。对于准入状态，要描述谁可以赋予该状态，以及它适用于什么问题。

在每个具有重大影响的概念旁边附上一例误用示例。候选计数不应暗示对全网的穷尽覆盖。被接受的来源不应被理解为对目标地址上每句话的背书。观测时间戳不应被理解为内容的发布时间。这些警示足够具体，能为仪表盘设计者提供指导。
该字典可以保持紧凑。它的价值在于消除歧义，而不是记录每一个内部实现细节。将其与发布评审关联起来，这样新功能就无法悄然为现有字段附加更强的含义。

在评估当前的 Scrapeless 方案选项时，将维护此证据字典及其映射所需的工作量计算在内。结构化采集为应用程序提供支持，而应用程序仍然掌控呈现给用户的含义。