ip:
  resolver:
    enabled: true              # 是否啟用 IP 解析
    db_path: "data/ip2region_v4.xdb"  # 數(shù)據(jù)文件路徑（服務(wù)器要在根目錄下例如：/f服務(wù)器根目錄/your-project/data/ip2region_v4.xdb）
    mode: "memory"             # 查詢模式：memory(內(nèi)存緩存) / file(文件讀取)

// internal\infra\ip\provider.go
package ip

import "github.com/google/wire"

// ProviderSet IP解析器依賴注入集合
var ProviderSet = wire.NewSet(
	NewResolver,
)

// internal\infra\ip\resolver.go

// Package ip 提供IP地址解析功能
package ip

import (
	"context"
	"net"
	"strings"

	"go-api/config"
	"go-api/pkg/logx"

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

// Resolver IP解析器接口
type Resolver interface {
	// Resolve 根據(jù)IP地址解析城市信息
	// 返回空字符串表示無法解析（內(nèi)網(wǎng)IP、IPv6、查詢失?。?
	Resolve(ctx context.Context, ip string) string

	// Close 關(guān)閉解析器，釋放資源
	Close()
}

// ip2regionResolver 基于ip2region的實(shí)現(xiàn)
type ip2regionResolver struct {
	searcher *xdb.Searcher
}

// NewResolver 創(chuàng)建IP解析器
// 如果配置文件未啟用或數(shù)據(jù)文件不存在，返回nil（不報(bào)錯(cuò)，服務(wù)可正常啟動(dòng)）
func NewResolver(cfg *config.Config) (Resolver, error) {
	if !cfg.IP.Resolver.Enabled {
		logx.Default.Info("IP解析器已禁用")
		return nil, nil
	}

	dbPath := cfg.IP.Resolver.DBPath
	if dbPath == "" {
		logx.Default.Warn("IP解析器數(shù)據(jù)文件路徑未配置，IP解析功能將不可用")
		return nil, nil
	}

	// 從數(shù)據(jù)文件加載頭部信息，獲取版本
	header, err := xdb.LoadHeaderFromFile(dbPath)
	if err != nil {
		logx.Default.Warn("加載IP數(shù)據(jù)庫頭部失敗，IP解析功能將不可用",
			"db_path", dbPath,
			"error", err,
		)
		return nil, nil
	}

	// 從頭部獲取版本信息
	version, err := xdb.VersionFromHeader(header)
	if err != nil {
		logx.Default.Warn("獲取IP數(shù)據(jù)庫版本失敗，IP解析功能將不可用",
			"db_path", dbPath,
			"error", err,
		)
		return nil, nil
	}

	// 創(chuàng)建 searcher（使用文件模式，根據(jù)數(shù)據(jù)文件版本）
	searcher, err := xdb.NewWithFileOnly(version, dbPath)
	if err != nil {
		logx.Default.Warn("加載IP數(shù)據(jù)庫失敗，IP解析功能將不可用",
			"db_path", dbPath,
			"error", err,
		)
		return nil, nil
	}

	logx.Default.Info("IP解析器初始化成功",
		"db_path", dbPath,
		"mode", cfg.IP.Resolver.Mode,
		"version", version.Name,
	)

	return &ip2regionResolver{
		searcher: searcher,
	}, nil
}

// Resolve 解析IP獲取城市信息
func (r *ip2regionResolver) Resolve(ctx context.Context, ip string) string {
	if r == nil || r.searcher == nil {
		return ""
	}

	// 清洗IP地址
	ip = cleanIP(ip)
	if ip == "" {
		return ""
	}

	// 檢查是否為內(nèi)網(wǎng)IP
	if isPrivateIP(ip) {
		logx.G(ctx).Debug("內(nèi)網(wǎng)IP，跳過解析", "ip", ip)
		return ""
	}

	// 將IP轉(zhuǎn)換為字節(jié)數(shù)組
	ipBytes, err := xdb.ParseIP(ip)
	if err != nil {
		logx.G(ctx).Warn("IP地址解析失敗", "ip", ip, "error", err)
		return ""
	}

	// 查詢ip2region
	region, err := r.searcher.Search(ipBytes)
	if err != nil {
		logx.G(ctx).Warn("IP解析失敗", "ip", ip, "error", err)
		return ""
	}

	// 解析結(jié)果格式：國(guó)家|區(qū)域|省份|城市|ISP
	city := extractCity(region)
	logx.G(ctx).Debug("IP解析成功", "ip", ip, "city", city, "region", region)

	return city
}

// Close 關(guān)閉解析器
func (r *ip2regionResolver) Close() {
	if r != nil && r.searcher != nil {
		r.searcher.Close()
	}
}

// cleanIP 清洗IP地址
// - 去除端口信息 [::1]:8080 -> ::1, 192.168.1.1:8080 -> 192.168.1.1
// - 處理IPv6映射地址 ::ffff:192.168.1.1 -> 192.168.1.1
func cleanIP(ip string) string {
	if ip == "" {
		return ""
	}

	// 使用 net.SplitHostPort 分離 IP 和端口
	host, _, err := net.SplitHostPort(ip)
	if err == nil {
		// 成功分離，使用 host 部分
		ip = host
	}
	// 如果分離失?。]有端口），保持原樣

	// 處理IPv6映射的IPv4地址 ::ffff:192.168.1.1
	if strings.HasPrefix(ip, "::ffff:") {
		ip = ip[7:]
	}

	return ip
}

// isPrivateIP 檢查是否為內(nèi)網(wǎng)IP
func isPrivateIP(ip string) bool {
	parsedIP := net.ParseIP(ip)
	if parsedIP == nil {
		return false
	}

	// 檢查IPv4私有地址段
	privateRanges := []string{
		"10.0.0.0/8",     // 10.0.0.0 - 10.255.255.255
		"172.16.0.0/12",  // 172.16.0.0 - 172.31.255.255
		"192.168.0.0/16", // 192.168.0.0 - 192.168.255.255
		"127.0.0.0/8",    // 127.0.0.0 - 127.255.255.255
		"169.254.0.0/16", // 鏈路本地地址
	}

	for _, cidr := range privateRanges {
		_, ipNet, err := net.ParseCIDR(cidr)
		if err != nil {
			continue
		}
		if ipNet.Contains(parsedIP) {
			return true
		}
	}

	return false
}

// extractCity 從ip2region結(jié)果中提取省份
// 格式：國(guó)家|省份|城市|ISP|國(guó)家代碼
// 示例：中國(guó)|廣東省|深圳市|電信|CN
func extractCity(region string) string {
	logx.Default.Info("ip2region返回的region", "region", region)
	if region == "" {
		return ""
	}

	parts := strings.Split(region, "|")
	if len(parts) < 2 {
		return ""
	}

	// 省份是第2個(gè)字段（索引1）
	province := parts[1]

	return province
}

// internal\infra\ip\util.go

package ip

import (
	"strings"

	"github.com/gin-gonic/gin"
)

// GetClientIP 從gin.Context獲取客戶端真實(shí)IP
// 優(yōu)先級(jí)：X-Forwarded-For → X-Real-IP → RemoteAddr
func GetClientIP(c *gin.Context) string {
	// 1. 嘗試從 X-Forwarded-For 獲取
	if xff := c.GetHeader("X-Forwarded-For"); xff != "" {
		if ip := parseXForwardedFor(xff); ip != "" {
			return ip
		}
	}

	// 2. 嘗試從 X-Real-IP 獲取
	if xri := c.GetHeader("X-Real-IP"); xri != "" {
		if ip := cleanIP(xri); ip != "" {
			return ip
		}
	}

	// 3. 從 RemoteAddr 獲取
	if ip := cleanIP(c.Request.RemoteAddr); ip != "" {
		return ip
	}

	return ""
}

// parseXForwardedFor 解析X-Forwarded-For頭
// 格式：client, proxy1, proxy2，取第一個(gè)有效IP
func parseXForwardedFor(header string) string {
	if header == "" {
		return ""
	}

	// 按逗號(hào)分割，取第一個(gè)IP
	parts := strings.Split(header, ",")
	for _, part := range parts {
		ip := strings.TrimSpace(part)
		if ip = cleanIP(ip); ip != "" {
			return ip
		}
	}

	return ""
}

// api\test\v1\test_handler.go
package v1

import (
	"go-api/internal/infra/ip"
)

// 從gin.Context獲取客戶端真實(shí)IP
func (h *UserDeviceLogHandler) GetClientIP(c *gin.Context) string {
	// 獲取客戶端真實(shí)IP
	clientIP := ip.GetClientIP(c)
	resp, err := h.logService.CreateLog(c, userID, clientIP, &req)
	if err != nil {
		logx.G(c).Error("創(chuàng)建設(shè)備日志失敗", "error", err)
		return nil
	}
	return resp
}

// internal\modules\test\service\test_service.go
func (s *userDeviceLogService) CreateLog(ctx context.Context, userID int64, clientIP string, req *v1.CreateUserDeviceLogReq) (*v1.UserDeviceLogResp, error) {

    // 解析IP獲取城市
    city := s.ipResolver.Resolve(clientIP)
    if city == "" {
        // 如果解析失敗，保持?jǐn)?shù)據(jù)庫字段為空
        city = nil
    }
    // 后面的處理我省略了
}