📍 什么是 ipapi.co-skills

🖥 命令行优先

本项目同时提供 CLI 命令行工具（ipapi，AI Agent 友好，默认 JSON 输出）和 Go SDK 库。本页及后续"库指南"面向想在 Go 程序中嵌入的开发者。如果你只想在终端查 IP，见 CLI 快速开始。

一个用 Go 语言编写的 ipapi.co IP 地理位置查询 API 客户端库。

一句话介绍

ipapi.co-skills 是 cyberspacesec 团队开源的 Go SDK，它把 ipapi.co 的 REST API 封装成符合 Go 习惯的、类型安全的客户端库，让你在 Go 项目中以最少的样板代码完成 IP 地理位置查询。

ipapi.co 是一个提供 IP 地理定位（IP geolocation）的在线服务。给定一个 IPv4 或 IPv6 地址，它能返回该地址关联的：

ipapi.co-skills 把这些能力包装成一个 Go 包 github.com/cyberspacesec/ipapi.co-skills/pkg/ipapi，提供：

能力	说明
`Client`	线程安全的 HTTP 客户端，可复用
6 个查询方法	覆盖「指定 IP / 客户端 IP」×「完整信息 / 单字段」×「解析 / 原始」
5 种格式	JSON / JSONP / XML / CSV / YAML
函数式选项	`WithAPIKey`、`WithCustomHTTPClient` 等
错误体系	10 个哨兵错误 + 结构化 `APIError`

🎨 一图抵千言

下面这张流程图展示了 SDK 从「输入 IP」到「输出结构化信息」的完整能力链路：用户调用 Client 的查询方法 → applyAuth 注入鉴权 → doRequest 发起 HTTP 请求 → handleError 处理错误 → 返回地理 / 网络 / ASN 三类结果。

🎨 一图抵千言

上面是能力链路，下面换一个时序视角，看一次完整调用中调用方、SDK 客户端、ipapi.co 服务三者之间的消息往返顺序与异步边界。

import "github.com/cyberspacesec/ipapi.co-skills/pkg/ipapi"