🔧 API 方法
pkg/ipapi/api.go— 6 个查询方法与请求基础设施。
方法总览
| 方法 | 端点 | 返回 | 文档 |
|---|---|---|---|
GetIPInfo(ctx, ip, format) | GET /{ip}/{format}/ | *IPInfo | → |
GetIPInfoRaw(ctx, ip, format) | GET /{ip}/{format}/ | []byte | → |
GetField(ctx, ip, field) | GET /{ip}/{field}/ | string | → |
GetClientIPInfo(ctx, format) | GET /{format}/ | *IPInfo | → |
GetClientIPInfoRaw(ctx, format) | GET /{format}/ | []byte | → |
GetClientField(ctx, field) | GET /{field}/ | string | → |
🎨 一图抵千言
6 个方法按「目标 IP」与「返回类型」两个维度划分：左半边查指定 IP，右半边查调用方 IP；每半边的三个方法分别返回结构化、原始字节、单字段。
内部基础设施
newGetRequest
go
func newGetRequest(ctx context.Context, baseURL string, segments ...string) (*http.Request, error)拼接 baseURL + 路径段 + /，创建 GET 请求。用 path.Join 处理 IPv6 冒号。
go
// newGetRequest(ctx, "https://ipapi.co/", "8.8.8.8", "json")
// → GET https://ipapi.co/8.8.8.8/json/doRequest
go
func (c *Client) doRequest(req *http.Request) (*http.Response, error)核心调度：
- 限流：
RateLimiter非空则阻塞拿令牌 - 重试：循环
0..Retries，仅网络错误/5xx 重试，间隔 500ms - 错误映射：
StatusCode >= 400时解析APIError或调mapStatusCodeToError
🎨 一图抵千言
doRequest 是所有 6 个方法的统一执行管道，三段式处理：限流放行 → 重试循环 → 错误映射。
applyAuth
go
func (c *Client) applyAuth(req *http.Request)注入 API Key（Header/Query）与 JSONP 回调。详见 WithAPIKey。
setHeaders
go
func (c *Client) setHeaders(req *http.Request)设置 User-Agent。
mapStatusCodeToError
go
func (c *Client) mapStatusCodeToError(code int) errorHTTP 状态码到哨兵错误的兜底映射：
| 状态码 | 错误 | 含义 |
|---|---|---|
| 400 | ErrServerError | 请求格式错误 |
| 403 | ErrInvalidKey | API Key 无效 |
| 404 | ErrNotFound | 资源不存在 |
| 405 | ErrMethodNotAllowed | 方法不允许 |
| 429 | ErrRateLimited | 触发限流 |
| 500 | ErrServerError | 服务端内部错误 |
| 其它 | unexpected status code: N | 未预期状态码 |
⚠️ 4xx 不重试
doRequest 仅对网络错误和 5xx 重试。4xx（含 429 限流）被视为客户端错误，不重试——因为重试同样会失败，反而可能加剧限流惩罚。
合法字段
validFields map 包含 28 个合法字段名，供 GetField / GetClientField 校验。完整清单见 字段总览。
通用流程
所有方法遵循相同模式：
校验入参 → newGetRequest → applyAuth → setHeaders → doRequest → 解码/raw → handleError🎨 一图抵千言
所有 6 个方法共享同一条调用链，差异仅在「入参校验」和「响应解码」两端。
详见各方法文档。