🔒 认证机制

ipapi.co 的 API Key 认证，本库支持两种方式。

为什么需要认证

ipapi.co 提供免费额度，但未认证请求配额低、且共享 IP 池。生产环境强烈建议申请 API Key：

📈 更高配额
🧮 独立计费
🛡 稳定可用性

在 ipapi.co 注册后在控制台获取 Key。

两种认证方式

方式 1：Bearer Header（默认）

Key 放在 Authorization 头：

client := ipapi.NewClient(
	ipapi.WithAPIKey("your_api_key"),
)
// 内部发送: Authorization: Bearer your_api_key

✅ 推荐。Key 不出现在 URL/日志中，更安全。

方式 2：Query Parameter

Key 放在 ?key= 查询参数：

client := ipapi.NewClient(
	ipapi.WithAPIKey("your_api_key"),
	ipapi.WithAPIKeyQuery(),  // 切换为 query 模式
)
// 内部发送: https://ipapi.co/8.8.8.8/json/?key=your_api_key

⚠️ Key 会出现在 URL、访问日志、Referer 中。仅在 Header 不可用时用（如某些受限代理、CDN）。

内部实现

applyAuth 根据字段 APIKeyMode 分支：

switch c.APIKeyMode {
case APIKeyQuery:
	q.Set("key", c.APIKey)        // 查询参数
default:
	req.Header.Set("Authorization", "Bearer "+c.APIKey) // 头
}

APIKeyMode 是 int 枚举：

const (
	APIKeyHeader APIKeyMode = iota // 0，默认
	APIKeyQuery                    // 1
)

🎨 一图抵千言

下面的流程图展示了 applyAuth 在每次请求时如何根据 APIKey 与 APIKeyMode 选择认证方式。

何时用哪种

场景	推荐
一般后端服务	Header ✅
需要在 CDN/网关层按 URL 鉴权	Query
前端 JSONP（无法设 Header）	Query
安全要求高	Header（避免日志泄露）

🎨 选型决策树

上面的表格给出了场景与推荐的对应关系。下面这张决策图从使用者创建 Client 时的选型视角出发，引导你一步步判断该用 Header 还是 Query（与上一节运行时 applyAuth 分支互补）。

安全最佳实践

🔐 切勿硬编码 Key

不要把 Key 写进源码或提交进 Git。用环境变量：

client := ipapi.NewClient(
	ipapi.WithAPIKey(os.Getenv("IPAPI_KEY")),
)

.env / .gitignore 中排除敏感文件。

🗝 Key 当作密码保管，定期轮换
📋 服务端 403 时检查 Key（ErrInvalidKey）
🚫 不要把带 Key 的 URL 打到日志

🎨 安全权衡一览

两种认证模式在 Key 的暴露面上有本质差异。下图对比 Key 从发出到落地各环节的可观测性，帮助理解为何默认推荐 Header。

不认证也能用

省略 WithAPIKey 即可，享受免费额度：

client := ipapi.NewClient() // 匿名

🔒 认证机制 ​

为什么需要认证 ​

两种认证方式 ​

方式 1：Bearer Header（默认） ​

方式 2：Query Parameter ​

内部实现 ​

何时用哪种 ​

安全最佳实践 ​

不认证也能用 ​

下一步 ​