Watch-IP

在 JavaScript 与 TypeScript 中使用 Watch-IP

@digitload/watch-ip-sdk(npm,v0.1.1)将 GET /v1/geo 封装进一个小型客户端中,为每个响应字段提供 TypeScript 类型,且没有运行时依赖。

安装

需要 Node.js 18 及以上版本,或任意现代浏览器——两者都提供了该软件包所依赖的全局 fetch。

npm

npm install @digitload/watch-ip-sdk

快速开始

使用您的公开可用密钥构造一个客户端,并调用 getGeo()。返回的 GeoResponse 具有完整的类型定义;除 ip 与 isEUCountry 之外的每个字段都可能为 null,请在渲染前先检查该字段。

TypeScript

import { WatchIP } from "@digitload/watch-ip-sdk";

const client = new WatchIP("wip_pub_xxxxxxxx");
const geo = await client.getGeo();

console.log(geo.country, geo.city, geo.timezone);

错误处理与超时

每一次失败——无论是被拒绝的请求(无效密钥、不被允许的来源、速率限制)还是网络错误——都会抛出一个带有 status 与稳定 code 的 WatchIPError。该 SDK 没有内置超时机制;如需自行取消一个耗时过长的请求,请传入 AbortController 的 signal。

TypeScript

import { WatchIP, WatchIPError } from "@digitload/watch-ip-sdk";

const client = new WatchIP("wip_pub_xxxxxxxx");
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

try {
  const geo = await client.getGeo({ signal: controller.signal });
} catch (err) {
  if (err instanceof WatchIPError) {
    console.error(err.code, err.status, err.message);
  }
}

可选字段

传入 include: ["hostname"] 可为当前连接的 IP 添加一次反向 DNS 查询。该功能是可选启用的,因为它会增加一次额外的网络跳转,因此只有在您会使用该字段时才应请求它。

TypeScript

const geo = await client.getGeo({ include: ["hostname"] });

本 SDK 不涵盖的内容

该软件包只调用 GET /v1/geo。它没有针对 IP 查询、邮箱验证或风险检测的方法——这些都是使用私密密钥(而非该 SDK 所围绕的公开可用密钥)进行身份验证的服务器到服务器端点。请直接通过 HTTP 调用它们;参见 IP 查询参考与身份验证指南。

相关页面