检查域名可用性
概述
检查某个 名称 在三个通常影响项目命名决策的层面上的可用性：域名 TLD、npm 包名以及 GitHub 用户名/组织。每项检查都是一个独立的、免费的、无需密钥的 API 调用——当用户正在为某事物命名时，应同时运行它们；如果用户只问了域名的情况，则只执行域名检查。
域名 API
GET https://domainee.dev/api/v1/tools/domain-availability-checker?name=<名称>&tlds=<tld>&tlds=<tld>...
name（必需）——不带 TLD 的域名，例如mybrand。tlds（可选，可重复）——例如?tlds=com&tlds=io。省略时，默认为com, io, dev, app, co, net, org, me, ai, xyz。- 无需身份验证。始终使用主机
domainee.dev/api/...，而不是api.domainee.dev——文档页面提到了那个主机，但它会返回 401（“Missing Bearer token”）；可用的、支持 CORS 的端点是同源下的domainee.dev/api。
速率限制：每个 IP 每分钟 30 次请求，每天 500 次请求。剩余配额在响应头 x-ratelimit-remaining-minute / x-ratelimit-remaining-day 中。返回 429 状态码时包含 Retry-After 头——将其展示给用户，而不是静默重试。
成功时返回：
{"ok":true,"data":{"name":"google","results":[
{"tld":"com","fqdn":"google.com","available":false,"registrarHint":null},
{"tld":"io","fqdn":"google.io","available":true,"registrarHint":null}
]}}
错误时返回（例如缺少 name 参数）：
{"ok":false,"error":{"code":"missing_param","message":"Query parameter `name` is required (e.g. ?name=mybrand)"}}
一个未被识别的 TLD 不是错误——它只是返回一个空的 results 数组。
每个 TLD 的注册表查找也可能超时。该 TLD 条目的 "available" 字段会变为 null，并且 registrarHint 字段会解释原因（例如 "The operation was aborted due to timeout"），而 ok 仍为 true，同一响应中的其他 TLD 不受影响。将 null 视为 未知，而不是可注册或已被注册——将其显示为一个单独的“无法检查”行，而不是进行猜测。如果响应中的 每个 TLD 都同时返回 null，那么这表明整个请求出现了短暂的故障，而非 10 次巧合的超时——在将全部未知的结果报告给用户之前，应重试该调用一次。
npm 包名 API
GET https://registry.npmjs.org/<名称>
无需身份验证，实践中也不需要担心速率限制头。200 = 名称已被占用（存在实际的包），404 = 可用。对于作用域包名（@scope/name），请对斜杠进行 URL 编码：https://registry.npmjs.org/@scope%2Fname。
GitHub 用户名/组织 API
GET https://api.github.com/users/<名称>
无需身份验证。200 = 已被占用，404 = 可用。未经身份验证的请求每个 IP 每小时限制 60 次（x-ratelimit-remaining 头）——对于少数几次检查来说没问题，但不要对一个很大的候选名称列表进行循环调用。
工作流程
- 去除用户可能已经键入的任何 TLD，以得到纯粹的
name。 - 如果用户只是询问域名，则仅调用域名 API。如果用户在给项目/初创公司/包/工具命名，则对该单个
name运行全部三项检查（域名、npm、GitHub）——这三项组合才是本技能的实际意义所在，而非孤立地检查域名。 - 调用域名 API。如果用户没有指定具体的 TLD，则省略
tlds参数以使用 10 个扩展名的默认集合。 - 展示一个合并的摘要：一个 TLD 表格（可用 ✅ / 已被占用 ❌ / 未知-超时 ⚠️，来自
registrarHint），再加上 npm 和 GitHub 各一行（✅/❌）。 - 询问一次是否需要检查更多 TLD（建议一些尚未覆盖的 TLD，例如
.ai、.so、一个 ccTLD）——除非用户再次提起，否则不要对同一个名称再次询问。 - 如果用户提供了更多 TLD，则仅用那些
tlds参数重复域名 API 调用，并展示新的结果。
社交媒体账号（X、Instagram 等）故意不包含在内——这些平台都没有提供免费的、无需身份验证的可用性检查；抓取个人资料页面既不可靠，也违反了它们的大多数服务条款。如果被问及，直接说明这一点，而不是通过抓取进行猜测。
示例
curl -s "https://domainee.dev/api/v1/tools/domain-availability-checker?name=mybrand&tlds=com&tlds=io&tlds=ai"
curl -s -o /dev/null -w "%{http_code}" "https://registry.npmjs.org/mybrand"
curl -s -o /dev/null -w "%{http_code}" "https://api.github.com/users/mybrand"
常见错误
- 使用
api.domainee.dev——错误的主机，会返回 401。应使用domainee.dev/api/...。 - 将空的
results数组视为失败——这表示 TLD 未被识别，而不是错误。 - 收到 429 后立即重试——应尊重
Retry-After头并告知用户，不要循环。 - 在简单的“这个域名可用吗？”问题中检查 npm/GitHub——只有用户确实在进行命名操作时才查询这些，而不是对每个域名查询都这样做。
- 声称可以检查社交媒体账号——没有可靠的免费 API 支持；应说明这不在能力范围内。