✅ 生产环境 API 调用文档（公网可用）

📌 服务地址：https://ipcx.api.hanyuxin.cn
📌 Swagger 在线文档：https://ipcx.api.hanyuxin.cn/docs/index.html
📌 最后更新：2025年9月13日
📌 版本：v1.0
📌 协议：✅ HTTPS（推荐生产使用）
📌 作者：寒语馨
📌 联系：hanyuxint@hanyuxin.cn

---

🧭 1. 快速开始（30秒上手）

🔍 查询 IP 归属地（推荐使用）

curl "https://ipcx.api.hanyuxin.cn/ip?ip=8.8.8.8"

✅ 响应示例：

{
  "ip": "8.8.8.8",
  "type": "ipv4",
  "region": "美国 加利福尼亚州圣克拉拉县山景市谷歌公司DNS服务器",
  "success": true
}

---

🌐 2. 所有可用接口

接口路径	方法	描述	示例地址
/ip	GET	查询 IP 归属地	https://ipcx.api.hanyuxin.cn/ip?ip=8.8.8.8
/health	GET	服务健康检查	https://ipcx.api.hanyuxin.cn/health
/	GET	Web 可视化前端界面	https://ipcx.api.hanyuxin.cn/
/swagger/...	GET	Swagger API 文档	https://ipcx.api.hanyuxin.cn/docs/index.html

---

📥 3. 详细接口说明

3.1 📍 IP 查询接口 /ip

请求方式

GET https://ipcx.api.hanyuxin.cn/ip?ip={IP地址}

请求参数

参数	类型	必填	示例	说明
ip	string	✅ 是	8.8.8.8	支持 IPv4
ip	string	✅ 是	2001:4860::8888	支持 IPv6

✅ 成功响应（HTTP 200 + success=true）

{
  "ip": "114.114.114.114",
  "type": "ipv4",
  "region": "中国 江苏省南京市 电信DNS服务器",
  "success": true
}

❌ 失败响应（HTTP 200 + success=false）

{
  "ip": "invalid.ip.address",
  "success": false,
  "message": "Invalid IP address format"
}

{
  "ip": "2001:db8::1",
  "type": "ipv6",
  "success": false,
  "message": "ipv6 database not loaded"
}

---

3.2 💚 健康检查接口 /health

用于监控系统状态、数据库是否加载成功。

请求方式

GET https://ipcx.api.hanyuxin.cn/health

✅ 响应示例

{
  "status": "OK",
  "message": "Service is running",
  "ipv4_loaded": true,
  "ipv6_loaded": false
}

✅ ipv4_loaded: true 表示 IPv4 数据库已加载，可正常查询
⚠️ ipv6_loaded: false 表示 IPv6 数据库未加载（不影响 IPv4 查询）

---

🖥️ 4. Web 可视化界面

直接访问 👉 https://ipcx.api.hanyuxin.cn/

功能：

• 输入 IP 地址（支持 IPv4 / IPv6）
• 实时显示归属地结果
• 显示数据库加载状态（✅/❌）
• 底部链接直达 Swagger 文档

---

📘 5. Swagger 自动化文档（强烈推荐）

👉 https://ipcx.api.hanyuxin.cn/docs/index.html

支持：

• 在线调试（Try it out）
• 自动生成 cURL / JavaScript / Python 示例代码
• 下载 OpenAPI 规范（JSON/YAML）
• 查看完整请求/响应结构

---

💻 6. 客户端调用示例

🌐 JavaScript (Fetch)

async function queryIP(ip) {
  const url = `https://ipcx.api.hanyuxin.cn/ip?ip=${encodeURIComponent(ip)}`;
  try {
    const res = await fetch(url);
    const data = await res.json();
    if (data.success) {
      console.log(`✅ ${data.ip} (${data.type}) -> ${data.region}`);
    } else {
      console.error(`❌ ${data.message}`);
    }
  } catch (err) {
    console.error('网络错误:', err);
  }
}

// 使用
queryIP('8.8.8.8');
queryIP('114.114.114.114');

🐍 Python (requests)

import requests

def query_ip(ip_address):
    url = "https://ipcx.api.hanyuxin.cn/ip"
    params = {"ip": ip_address}
    try:
        response = requests.get(url, params=params)
        data = response.json()
        if data.get("success"):
            print(f"✅ {data['ip']} ({data['type']}) -> {data['region']}")
        else:
            print(f"❌ {data.get('message')}")
    except Exception as e:
        print(f"网络错误: {e}")

# 使用
query_ip("8.8.8.8")
query_ip("240e::1")

📱 Postman / Apifox / Hoppscotch

直接导入 URL：

https://ipcx.api.hanyuxin.cn/ip?ip=8.8.8.8

🛡️ 7. 安全与性能说明

项目	说明
协议	HTTPS（加密传输，安全）✅
并发支持	Go 原生高并发，支持数千 QPS ✅
鉴权	当前版本无 API Key 限制 ❌（如需可添加）
限流	未配置（建议生产环境加 Nginx 限流）⚠️
缓存	无（每次查询直接读库）
响应时间	< 50ms（SSD + 内存加载模式）⚡

---

🆘 8. 常见问题 FAQ

❓ 访问返回 404？

→ 请确认路径是否正确：

• ✅ 正确：https://ipcx.api.hanyuxin.cn/ip?ip=8.8.8.8
• ❌ 错误：https://ipcx.api.hanyuxin.cn/?ip=8.8.8.8

**支持IPV4和IPV6

📞 9. 技术支持

如遇任何问题，请联系：

📧 邮箱：hanyuxin@hanyuxin.cn
🌐 文档：https://ipcx.api.hanyuxin.cn/docs/index.html
🕒 响应时间：7×24 小时（紧急问题 30 分钟内响应）

---