SDK 文档

JavaScript / Python / curl 多语言 SDK · 统一封装 REST/RPC/GraphQL

安装

# npm
npm install @xiaoniao/dns

# pnpm
pnpm add @xiaoniao/dns

# bun
bun add @xiaoniao/dns

快速开始

SDK 默认使用 REST 后端，可切换为 RPC 或 GraphQL：

import { Client } from "@xiaoniao/dns";

// 初始化客户端
const client = new Client({
  apiKey: "cfsd_xxxxxxxxxxxxxxxx",
  apiSecret: "yyyyyyyyyyyyyyyyyyyy",
  // 默认指向 https://your-host，可自定义
  baseUrl: "https://your-host",
  // 可选: "rest" | "rpc" | "graphql" (默认 rest)
  transport: "rest",
});

// 验证凭证
const verify = await client.auth.verify();
console.log(verify.account.quota);
// { used: 3, total: 7, available: 4 }

// 列出子域名
const list = await client.subdomains.list({ per_page: 10 });
console.log(list.subdomains);

// 注册新子域名
const created = await client.subdomains.create({
  subdomain: "myapp",
  rootdomain: "us.kg",
});

// 创建 DNS 记录
await client.dnsRecords.create(created.subdomain_id, {
  type: "A",
  content: "192.0.2.1",
  ttl: 600,
});

// 查询 WHOIS
const whois = await client.whois.query("foo.example.com");

// 检测某域名是否安装了小雫DNS
const detect = await client.system.detect("example.com");
if (detect.detected) {
  console.log(`检测到小雫DNS v${detect.version}`);
}

SDK API 总览

命名空间

方法

对应 RPC method

说明

auth

verify()

auth.verify

验证凭证并返回配额摘要

subdomains

list(opts)

subdomains.list

分页列出子域名

subdomains

create({subdomain, rootdomain})

subdomains.create

注册子域名

subdomains

get(id)

subdomains.get

获取子域名详情（含 DNS 记录）

subdomains

delete(id)

subdomains.delete

删除子域名及其 DNS 记录

subdomains

renew(id)

subdomains.renew

续费子域名

dnsRecords

list(subdomainId)

dns_records.list

列出 DNS 记录

dnsRecords

create(subdomainId, body)

dns_records.create

创建 DNS 记录

dnsRecords

update(id, body)

dns_records.update

更新 DNS 记录

dnsRecords

delete(id)

dns_records.delete

删除 DNS 记录

apiKeys

list()

api_keys.list

列出 API 密钥

apiKeys

create(name, ipWhitelist?)

api_keys.create

创建 API 密钥

apiKeys

delete(keyId)

api_keys.delete

删除 API 密钥

apiKeys

regenerate(keyId)

api_keys.regenerate

重置 API Secret

quota

get()

quota.get

查询配额

whois

query(domain)

whois.query

WHOIS 查询

permanentUpgrade

list()

permanent_upgrade.list

永久升级状态

permanentUpgrade

create(subdomainId)

permanent_upgrade.create

申请永久升级

permanentUpgrade

assist(code)

permanent_upgrade.assist

助力好友邀请码

permanentUpgrade

cancel(requestId)

permanent_upgrade.cancel

取消升级任务

system

detect(domain)

system.detect

检测目标域名是否安装小雫DNS

传输层切换

SDK 内置三种传输层，无需改业务代码即可切换。三种层语义完全等价，性能略有差异：

rest

默认 · 资源化 URL · 缓存友好

rpc

单端点 · 支持批量调用

graphql

按需取字段 · 减少传输量

// JavaScript
const client = new Client({ ..., transport: "rpc" });

// Python
client = Client(..., transport="graphql")

错误处理

import { Client, ApiError } from "@xiaoniao/dns";

try {
  await client.subdomains.create({ subdomain: "x", rootdomain: "us.kg" });
} catch (e) {
  if (e instanceof ApiError) {
    console.log(e.code);        // "quota_exceeded"
    console.log(e.message);     // "Quota exceeded"
    console.log(e.httpStatus);  // 429
    console.log(e.details);     // { limit: 60, reset_at: "..." }
  }
}

命令行工具 xndns

SDK 自带 CLI，安装后即可在终端使用：

# 通过环境变量配置凭证
export XNDNS_API_KEY="cfsd_xxx"
export XNDNS_API_SECRET="yyyy"
export XNDNS_HOST="https://your-host"

# 查询配额
xndns quota

# 列出子域名
xndns subdomains list --per-page 10

# 注册子域名
xndns subdomains create --subdomain myapp --rootdomain us.kg

# 列出某子域名的 DNS 记录
xndns dns list --subdomain-id 12345

# 创建 DNS 记录
xndns dns create --subdomain-id 12345 \
  --type A --content 192.0.2.1 --ttl 600

# WHOIS 查询
xndns whois foo.example.com

# 检测某域名是否安装小雫DNS
xndns detect example.com

# 输出格式：默认 human-readable，加 --json 切换为 JSON
xndns quota --json

提示：本控制台侧边栏「CLI 控制台」也内置了交互式命令行，可直接在浏览器内试用。