一次短链背后藏着的跳转链短链已经成为内容分发链路里的常见中间层。一个短链从点击到最终落地往往不止一次 302而是一串连续的跳转短链服务先返回重定向到统计网关统计网关再转发到渠道中间页最后才落到真实页面。对开发者来说很多调试场景需要把这串链路完整拉出来看安全审计时确认某一个短链最终指向的域名是否在黑名单内排查链接失效时判断是哪一个环节返回了 404 或 500二维码内容核验时还原扫码后实际打开的地址做域名封禁或合规检查时需要看到中间跳转的所有站点。只拿到最终 URL 是不够的。中间跳转里可能藏着额外的参数拼接、同一个域名下的内部路由切换甚至是 Meta-Refresh 这种无状态码跳转。短链还原接口正好提供逐跳还原能力把每一跳的方式和耗时都暴露出来。接口能力边界先明确这个接口能做什么、不能做什么避免接入后产生误判。能做的根据传入的短链地址发起 HTTP 链路追踪输出每一跳的 URL、状态码、跳转方式和耗时还原最终落地 URL汇总总耗时支持用 max_hops 控制最大跳转深度防止链路过深导致请求挂起。不能做的不解析页面内容只做 HTTP 层追踪不保留历史追踪记录接口是无状态的不保证能追平所有类型的反爬重定向部分站点会对非浏览器 UA 返回不同链路不执行 JavaScript 渲染SPA 路由跳转不在还原范围内。这里特别提醒一点max_hops 的上限是 30但实际使用中建议控制在 10 以内。跳转层级过深通常意味着追踪链路里有循环或异常配置超出接口限制后请求会失败而不是继续追下去。请求参数与鉴权接口采用 GET 方法请求地址固定所有参数通过 query string 传递。参数名类型必填说明urlstring是要展开的短链地址需做 URL 编码max_hopsnumber否最大跳转次数取值范围 1-30默认 10鉴权通过请求头X-API-Key完成。需要在请求头中携带 API Key而不是放在 query 参数里。X-API-Key: 你的密钥QPS 上限为 5 次/秒。这是一个共享限额不适合在代码里对单链路做大量并发扫描批量任务需要自行控制速率。curl 快速接入先从一个可直接改用的 curl 示例开始。将$APIZERO_API_KEY替换为实际密钥即可curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/unshort?urlhttps://t.cn/A6xxxx如果需要限制最大跳转深度追加max_hops参数curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/unshort?urlhttps%3A%2F%2Ft.cn%2FA6xxxxmax_hops5注意url参数值里包含://和/在 query string 中建议做 URL 编码避免某些网关在解析时截断参数值。用 Python 接入并输出链路摘要curl 用于验证参数没问题实际工程里通常会用脚本语言封装。下面是一段 Python 示例把响应数据整理成逐跳表格import os import requests API_URL https://v1.apizero.cn/api/unshort API_KEY os.environ.get(APIZERO_API_KEY, ) def unshort(url: str, max_hops: int 10) - dict: resp requests.get( API_URL, params{url: url, max_hops: max_hops}, headers{X-API-Key: API_KEY}, timeout10, ) resp.raise_for_status() payload resp.json() if payload.get(code) ! 0: raise RuntimeError(f接口返回错误: {payload.get(msg)}) return payload[data] if __name__ __main__: target_url https://t.cn/A6xxxx data unshort(target_url) print(f原始 URL: {data[original_url]}) print(f最终 URL: {data[final_url]}) print(f总跳数: {data[hops]} | 总耗时: {data[total_time_ms]}ms) print(- * 60) for item in data[chain]: method item.get(method, final) status item.get(status) duration item.get(duration_ms) target item.get(next, ) print(f#{item[hop]} [{method}] {status} {duration}ms - {target})这段代码的核心价值在于把chain数组里的每一跳展开成一行方便在日志系统里做后续处理。实际接入时建议把timeout设置得比接口总耗时长一些因为逐跳追踪本身需要时间。响应字段逐段解读接口返回的是一个标准 JSON 对象最外层包含code和msg两个字段。code为 0 表示成功非零值表示业务异常。data对象里主要有以下几组字段1. 基础信息original_url请求时传入的原始短链地址final_url最终落地地址即最后一跳的 URLhops实际跳转次数不包含原始地址本身is_redirect布尔值是否存在重定向行为。如果短链直接返回 200 且没有跳转该字段为falsetotal_time_ms整条链路的总耗时单位毫秒。2. chain 数组chain是核心数据数组中的每个元素代表一次 HTTP 请求-响应过程字段说明hop当前跳数从 1 开始计数url本次请求的 URLstatusHTTP 状态码method跳转方式Location 或 Meta-Refreshnext跳转目标地址最后一跳为空duration_ms本次请求耗时单位毫秒以素材中的示例数据为例第一跳https://t.cn/Aabc返回 302跳转方式为Location指向https://example.com/landing耗时 120ms第二跳https://example.com/landing返回 200method为final表示这是最终响应耗时 292ms。一个值得注意的细节method字段区分了两类跳转。Location是 HTTP 头里的标准重定向浏览器会直接发起新请求Meta-Refresh是 HTML 文档里meta http-equivrefresh实现的跳转HTTP 层面返回 200但页面会自动刷新到新地址。这种跳转在域名失效检测场景下尤其容易漏判。常见错误与排查切入点使用过程中遇到问题可以从以下几个方向排查1. 鉴权失败返回 401 或 code 非 0检查请求头中是否包含X-API-Key以及 Key 是否有拼写错误或多余的空格。注意 Key 是请求头字段不是 query 参数。2. url 参数返回解析失败先检查短链地址是否完整。部分短链服务要求带https://前缀裸域名无法解析。另外完整地址中的字符会被 query string 解析器截断必须做 URL 编码。3. max_hops 设置过小导致链路中断如果目标短链本身链路较长而max_hops设置小于实际跳转次数接口会返回错误或截断链路。建议先使用默认值 10观察返回的hops字段再按需调整。4. 响应超时短链目标服务器响应慢时接口本身耗时也会增加。如果服务端对上游依赖较重建议客户端超时时间设置在 15 秒以上。5. QPS 限流接口限制 5 QPS。如果业务侧需要批量展开短链建议在代码中加令牌桶或信号量做限流避免请求被拒绝。工程化注意事项数据状态认定is_redirect字段是判断短链是否有效的参考值之一但不能作为唯一依据。某些短链服务会在第一次访问时返回 302后续访问命中缓存后直接返回 200单次请求结果不能代表该短链的长期行为。Meta-Refresh 处理method为Meta-Refresh时next字段里的地址可能是一个相对路径。在工程化处理中需要把这个相对路径与当前页面 URL 拼接成完整地址否则后续请求会失败。日志记录维度建议在业务日志中记录以下字段便于事后审计原始短链地址final_url总耗时是否包含 Meta-Refresh 跳转每一跳的状态码序列状态码序列可以直接用逗号拼接例如302,200在日志检索时配合正则或 IN 查询就能快速筛选出异常链路。批量场景的速率控制批量展开场景下建议使用固定速率调度器控制请求频率。QPS 限制是 5按 80% 的安全余量计算每秒调度 4 个请求即可。缓存策略短链的还原结果在一定时间范围内是稳定的但并非永久有效。如果业务对实时性要求不高可以按 TTL 做缓存以降低接口调用量。TTL 建议设置在 30 分钟到 1 小时之间具体以业务对时效的容忍度为准。参考文档接口文档页https://apizero.cn/aidocs/unshort原始 Markdown 文档https://apizero.cn/aidocs/unshort/raw.md