🧭 Client 客户端

Client 是整个 SDK 的核心，所有查询都通过它发起。

它是什么

Client 是一个线程安全的 HTTP 客户端封装，持有调用 ipapi.co 所需的全部状态：

type Client struct {
	HTTPClient   *http.Client          // 底层 HTTP 客户端
	BaseURL      string                // API 基地址，默认 https://ipapi.co/
	APIKey       string                // API 密钥
	APIKeyMode   APIKeyMode            // 认证方式（Header / Query）
	UserAgent    string                // User-Agent 头
	Retries      int                   // 重试次数，默认 2
	RateLimiter  <-chan time.Time      // 速率限制通道
	Callback     string                // JSONP 回调名
	errorHandler func(error) error     // 自定义错误处理
}

🎨 一图抵千言

下面这张类图展示了 Client 各字段、WithXxx 函数式选项与内部辅助方法之间的装配关系——选项负责写字段，方法负责读字段。

🧩 依赖视角

上面那张图看的是「谁写字段」；下面这张看的是运行时 Client 依赖哪些协作者、各自承担什么职责。http.Client 负责网络传输，RateLimiter 通道负责节流，errorHandler 回调负责错误改写——三者皆可替换，这正是函数式选项的意义。

线程安全

Client 内部无共享可变状态（请求都新建 *http.Request），可以安全地在多个 goroutine 间复用：

var client = ipapi.NewClient()

func handler(w http.ResponseWriter, r *http.Request) {
	// 多个请求并发调用，安全
	info, _ := client.GetClientIPInfo(r.Context(), "json")
	// ...
}

🚀 性能建议

复用同一个 Client 实例，不要每次请求都 NewClient()。复用能复用底层连接池，减少 TCP/TLS 握手开销。

默认值

字段	默认值	来源
`BaseURL`	`https://ipapi.co/`	`defaultBaseURL`
`HTTPClient.Timeout`	`10s`	`defaultTimeout`
`UserAgent`	`ipapi-go-client/1.0`	硬编码
`Retries`	`2`	硬编码
`APIKeyMode`	`APIKeyHeader`	iota 零值
`CheckRedirect`	最多 3 次跳转	`maxRedirects`

六个查询方法

Client 暴露 6 个方法，构成「指定IP / 客户端IP × 完整/单字段 × 解析/raw」的矩阵：

方法	目标	返回	文档
`GetIPInfo`	指定 IP	`*IPInfo`	→
`GetIPInfoRaw`	指定 IP	`[]byte`	→
`GetField`	指定 IP 单字段	`string`	→
`GetClientIPInfo`	客户端 IP	`*IPInfo`	→
`GetClientIPInfoRaw`	客户端 IP	`[]byte`	→
`GetClientField`	客户端 IP 单字段	`string`	→

配置项一览

选项	作用	文档
`WithAPIKey`	设置 API Key	→
`WithAPIKeyQuery`	改用 query 参数认证	→
`WithCustomHTTPClient`	替换底层 `*http.Client`	→
`WithErrorHandler`	注入错误处理回调	→
`WithCallback`	设置 JSONP 回调名	→

何时该自定义

场景	推荐配置
本地开发/小流量	`NewClient()` 默认即可
生产服务	`WithAPIKey` + `WithCustomHTTPClient`(更长超时)
高并发	设 `RateLimiter` 通道 + 复用 Client
跨域前端（JSONP）	`WithCallback`
审计/监控	`WithErrorHandler` 做日志/metrics
受限网络	`WithCustomHTTPClient` 注入代理

🧭 Client 客户端 ​

它是什么 ​

线程安全 ​

默认值 ​

六个查询方法 ​

配置项一览 ​

何时该自定义 ​

下一步 ​