跳到主要内容
WeaveBit
控制台 免费 DNS 检测

SDK 与代码示例

下载 PHP、Python、Node.js 服务器端轻量 SDK，接入 DNS 污染与 GFW 全量检测，了解超时、幂等重试、结果分页和安全使用方式。

更新于 API v2 v1

官方轻量 SDK 是可复制、修改和下载的服务器端 HTTP 客户端，不是只能查看的请求片段。它帮助你处理 API 认证、请求超时、幂等重试、等待和分页，服务端返回的检测结果保持原样。客户端不包含 DNS 污染判断实现。

下载官方轻量 SDK

首版版本 0.1.0 · 公开接口契约核对 2026-10-12。下载与阅读无需登录，调用检测需要有效账户与余额。

PHP · PHP 8.1+ · cURL / JSON 客户端、运行示例、中英文说明与离线测试 · ZIP Python · Python 3.10+ · standard library 客户端、运行示例、中英文说明与离线测试 · ZIP Node.js · Node.js 18+ · ESM / fetch 客户端、运行示例、中英文说明与离线测试 · ZIP
下载校验 SHA-256

PHP

692b9900ffdcc1c860c6456b5a3a27c892528885254649c388aeffb08f3dca36

Python

17745cdaf21b98d86c4331945ac99c0941dfb0a62fdd1c951925524985a90ace

Node.js

6b4fa4481957c6136ed8a90a235a89ce45c2a033e8d59ecfe0b5e9516928b004

PHP、Python 和 Node.js 均使用语言自带功能或标准扩展，不依赖额外第三方客户端包。当前通过上述版本化 ZIP 分发，尚未发布到 Composer、PyPI 或 npm；不要使用未经确认的同名第三方包。

运行前先确认三件事

  1. 取得 Console 中的统一 API Key，通过服务器环境变量 WEAVEBIT_API_KEY 设置。不要把密钥写入网页、代码仓库、下载包或日志。
  2. 解压后阅读对应中英文 README，确认运行版本与扩展。示例程序默认只估价，API v1 场景默认只打印请求计划；只有显式执行选项才运行收费检测。
  3. 创建 API v2 批次前，保存请求内容和调用者生成的幂等键。PHP、Node.js 示例使用 WEAVEBIT_IDEMPOTENCY_KEY 和请求文件；Python 示例先将键和请求持久化到状态文件。创建结果不明时使用相同内容、相同键重试，不要换一个键再提交。
python3 example.py --help
php example.php --help
node example.mjs --help

以上分别在对应下载包中执行。SDK 是服务器端工具，Node.js 示例不应放到浏览器网页中运行。请先查看估价，再决定是否创建；客户端默认行为不能代替自己的预算审批。

选择接入场景

你需要什么建议接口准备事项
少量单域名即时 DNS 污染检测API v1 同步方法每次一个域名，无幂等重试契约；SDK 不自动重试。
批量 DNS 污染初查API v2，dns_pollution_check提交域名清单，不传用户选择的节点；创建前估价。
便捷、批量的中国访问性综合检查API v2，gfw_full_domain_check按客户地区、运营商选择实际节点；包含 DNS 污染、HTTP Host 与 TLS SNI 三个维度，不是完整浏览器或业务验证。

六个 API v2 端点均有客户端方法：节点、估价、创建、批次列表、结果和余额。其他公开检测类型可通过通用估价、创建方法提交；参数契约以 API 文档 为准，不在 SDK 中复制检测判断逻辑。

客户端处理了什么

  • 分别处理连接、HTTP、JSON 与业务错误；保留服务端结果和金额字符串。
  • 请求默认超时 30 秒，最多 4 次尝试。重试遵循 Retry-After，不会为同一逻辑创建请求生成新的幂等键。
  • 默认等待上限 300 秒，包含请求、重试和间隔；等待超时只停止客户端等待，不取消批次，也不创建新批次。可以用原 batch_id 继续查询。
  • 批次状态按公开契约为 pending、running、completed；未知状态会明确报错。完成只表示执行结束，不表示目标一定正常。
  • 完整结果读取会依次获取所有目标分页，不把第一页当作全量；结果里的 null 保持为无法判定。

Python 标准库使用 socket 超时，并在请求前后检查总期限；这不是操作系统级硬取消，对持续缓慢发送数据的连接不承诺严格实时终止。需要硬期限时，应由调用方增加进程级执行限制。超过服务端要求的重试等待上限时，SDK 停止当前重试，不会提前请求。

客户端等待上限与服务端执行期限不是同一件事。批次执行最多 6 小时，创建后 24 小时清理；请及时保存所需结果。恢复不明创建也受服务端 24 小时幂等记录窗口限制。

验证范围与使用许可

本版完成公开接口契约核对、模拟响应测试和离线测试，未把真实收费检测的结果当作验证记录。随包提供测试，覆盖超时、错误、重试、幂等、分页和等待边界。开始大规模使用前，仍应使用自己获准检测的域名、小批量验证接入并核对费用。

随包客户端代码允许复制和修改，用于接入 WeaveBit API；这不授予服务端实现、商标或第三方依赖的权利。服务访问与计费遵循现有服务条款。完整许可、版本记录和方法签名见下载包内说明。

继续阅读

原有 cURL 与多语言快速示例 · 批量 API 工作流 · 费用与预算指南 · 结果含义 · 免费 DNS 污染检测