💡 带 API Key 认证

配置 API Key 提升配额与稳定性。

🎨 一图抵千言

调用结构如下：环境变量注入 Key → 函数式选项注入 Client → 每次请求由内部 applyAuth 注入 Authorization: Bearer → 发起请求。

场景

生产环境、高流量服务需要认证。

func main() {
	client := ipapi.NewClient(
		ipapi.WithAPIKey(os.Getenv("IPAPI_KEY")),
	)
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	info, err := client.GetIPInfo(ctx, "8.8.8.8", "json")
	if err != nil {
		if errors.Is(err, ipapi.ErrInvalidKey) {
			log.Fatal("API Key 无效，请检查")
		}
		log.Fatal(err)
	}
	fmt.Println(info.City)
}

内部发送 Authorization: Bearer <key>。

🎨 一图抵千言

从时序视角看一次带 Key 请求的往返：调用方、SDK 内部、ipapi.co 服务三者之间的交互如下。

Query 模式

client := ipapi.NewClient(
	ipapi.WithAPIKey(os.Getenv("IPAPI_KEY")),
	ipapi.WithAPIKeyQuery(), // ?key=...
)

用于 JSONP 等无法设 Header 的场景。

安全最佳实践

🔐 勿硬编码

// ❌ 危险
client := ipapi.NewClient(ipapi.WithAPIKey("sk-xxx-hardcoded"))

// ✅ 安全
client := ipapi.NewClient(ipapi.WithAPIKey(os.Getenv("IPAPI_KEY")))

用环境变量 / 密钥管理
.env 加入 .gitignore
定期轮换 Key
403 时检查 Key（ErrInvalidKey）

运行

bash

export IPAPI_KEY="your_key_here"
go run main.go

📋 运行预期输出与常见问题

预期输出（Header 模式，Key 有效）：

txt

Mountain View

常见问题：

403 Forbidden / ErrInvalidKey：环境变量未设置或 Key 失效，检查 IPAPI_KEY 是否正确导出。
仍被限流（ErrRateLimited）：即使带 Key 也可能触发，确认套餐配额；可重试，详见错误处理。
Query 模式仍走 Header：确认同时传了 WithAPIKeyQuery，它将 APIKeyMode 切换为 Query 模式。
JSONP 场景建议用 Query 模式，因为浏览器无法附带自定义 Header。

💡 带 API Key 认证

场景

Header 模式（默认推荐）

Query 模式

安全最佳实践

运行

下一步

💡 带 API Key 认证 ​

场景 ​

Header 模式（默认推荐） ​

Query 模式 ​

安全最佳实践 ​

运行 ​

下一步 ​

💡 带 API Key 认证

场景

Header 模式（默认推荐）

Query 模式

安全最佳实践

运行

下一步