Go语言实战案例-项目实战篇：开发一个 IP 归属地查询接口

在日常开发中，IP 地址归属地查询是一个常见需求：比如记录用户访问日志时展示用户的地理位置，或在安全防护系统中分析异常登录来源。本文将带你用 Go 语言快速开发一个 IP 归属地查询接口服务。

功能目标

1. 提供一个 HTTP 接口，输入 IP 地址返回归属地信息

2. 支持查询单个 IP，也可扩展成批量查询

3. 数据源可选择：

   • 本地离线 IP 数据库（如 ip2region）
   • 第三方 API（如 ip-api、ipinfo 等）

4. 结果返回 JSON 格式

技术栈

• Go 标准库：net/http、encoding/json

• 第三方库：

  • github.com/lionsoul2014/ip2region/binding/golang/xdb —— 离线 IP 数据库解析

• 存储方式：使用本地 ip2region.xdb 文件

项目结构

ip-lookup/
├── main.go
├── ip2region.xdb   # 离线数据库文件
├── go.mod

核心代码（main.go）

package main

import (
	"encoding/json"
	"log"
	"net"
	"net/http"

	"github.com/lionsoul2014/ip2region/binding/golang/xdb"
)

// 响应结构
type IPInfo struct {
	IP      string `json:"ip"`
	Region  string `json:"region"`
	Error   string `json:"error,omitempty"`
}

var searcher *xdb.Searcher

func main() {
	// 加载 ip2region 数据库
	var err error
	searcher, err = xdb.NewWithFileOnly("ip2region.xdb")
	if err != nil {
		log.Fatalf("❌ 加载 ip2region.xdb 失败: %v", err)
	}

	http.HandleFunc("/ip", queryIP)

	log.Println("✅ IP 归属地查询服务已启动: http://localhost:8080/ip?addr=1.1.1.1")
	http.ListenAndServe(":8080", nil)
}

func queryIP(w http.ResponseWriter, r *http.Request) {
	addr := r.URL.Query().Get("addr")
	if addr == "" {
		writeJSON(w, IPInfo{Error: "缺少参数 addr"})
		return
	}

	if net.ParseIP(addr) == nil {
		writeJSON(w, IPInfo{IP: addr, Error: "无效的 IP 地址"})
		return
	}

	region, err := searcher.SearchByStr(addr)
	if err != nil {
		writeJSON(w, IPInfo{IP: addr, Error: err.Error()})
		return
	}

	writeJSON(w, IPInfo{IP: addr, Region: region})
}

func writeJSON(w http.ResponseWriter, data IPInfo) {
	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(data)
}

使用方法

1. 初始化项目并安装依赖

go mod init ip-lookup
go get github.com/lionsoul2014/ip2region/binding/golang/xdb

2. 下载 ip2region.xdb 数据库文件，放到项目根目录

3. 运行

go run main.go

4. 请求示例

curl "http://localhost:8080/ip?addr=8.8.8.8"

返回结果示例：

{
  "ip": "8.8.8.8",
  "region": "美国|0|加利福尼亚|圣克拉拉|谷歌"
}

扩展功能

1. 批量查询：支持上传 IP 列表文件，返回批量结果
2. 缓存机制：对高频 IP 查询做缓存，提升性能
3. 前端展示：结合简单前端页面展示查询结果
4. 多数据源支持：同时支持 ip2region 和第三方 API，作为备份

总结

通过本案例，我们实现了一个 IP 归属地查询接口，使用 ip2region 离线库做到快速查询，性能高效且无需依赖外部服务。这个小工具既能单独运行，也能嵌入到日志分析、Web 服务或安全监控系统中使用，是 Go 项目开发中的一个实用模块。