【新增】yudao-spring-boot-starter-biz-ip 业务组件，提供地区 & IP 库的封装

yudao-dependencies/pom.xml

@@ -64,6 +64,7 @@
         <tika-core.version>2.5.0</tika-core.version>
         <aj-captcha.version>1.3.0</aj-captcha.version>
         <netty-all.version>4.1.85.Final</netty-all.version>
+        <ip2region.version>2.6.6</ip2region.version>
         <!-- 三方云服务相关 -->
         <okio.version>3.0.0</okio.version>
         <okhttp3.version>4.10.0</okhttp3.version>
@@ -150,6 +151,11 @@
                 <artifactId>yudao-spring-boot-starter-biz-error-code</artifactId>
                 <version>${revision}</version>
             </dependency>
+            <dependency>
+                <groupId>cn.iocoder.cloud</groupId>
+                <artifactId>yudao-spring-boot-starter-biz-ip</artifactId>
+                <version>${revision}</version>
+            </dependency>
             <dependency>
                 <groupId>cn.iocoder.cloud</groupId>
                 <artifactId>yudao-spring-boot-starter-captcha</artifactId>
@@ -564,6 +570,12 @@
                 <version>${netty-all.version}</version>
             </dependency>
 
+            <dependency>
+                <groupId>org.lionsoul</groupId>
+                <artifactId>ip2region</artifactId>
+                <version>${ip2region.version}</version>
+            </dependency>
+
             <!-- 三方云服务相关 -->
             <dependency>
                 <groupId>com.squareup.okio</groupId>

yudao-framework/pom.xml

@@ -39,6 +39,7 @@
         <module>yudao-spring-boot-starter-biz-tenant</module>
         <module>yudao-spring-boot-starter-biz-data-permission</module>
         <module>yudao-spring-boot-starter-biz-error-code</module>
+        <module>yudao-spring-boot-starter-biz-ip</module>
 
         <module>yudao-spring-boot-starter-flowable</module>
         <module>yudao-spring-boot-starter-captcha</module>

yudao-framework/yudao-spring-boot-starter-biz-ip/pom.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <groupId>cn.iocoder.cloud</groupId>
+        <artifactId>yudao-framework</artifactId>
+        <version>${revision}</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+    <artifactId>yudao-spring-boot-starter-biz-ip</artifactId>
+    <packaging>jar</packaging>
+
+    <name>${project.artifactId}</name>
+    <description>IP 拓展，支持如下功能：
+        1. IP 功能：查询 IP 对应的城市信息
+            基于 https://gitee.com/lionsoul/ip2region 实现
+        2. 城市功能：查询城市编码对应的城市信息
+            基于 https://github.com/modood/Administrative-divisions-of-China 实现
+    </description>
+    <url>https://github.com/YunaiV/ruoyi-vue-pro</url>
+
+    <properties>
+        <ip2region.version>2.6.6</ip2region.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>cn.iocoder.cloud</groupId>
+            <artifactId>yudao-common</artifactId>
+        </dependency>
+
+        <!-- IP地址检索 -->
+        <dependency>
+            <groupId>org.lionsoul</groupId>
+            <artifactId>ip2region</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <scope>provided</scope> <!-- 设置为 provided，只有工具类需要使用到 -->
+        </dependency>
+
+        <!-- Test 测试相关 -->
+        <dependency>
+            <groupId>cn.iocoder.cloud</groupId>
+            <artifactId>yudao-spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+</project>

yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/java/cn/iocoder/yudao/framework/ip/core/Area.java

+package cn.iocoder.yudao.framework.ip.core;
+
+import cn.iocoder.yudao.framework.ip.core.enums.AreaTypeEnum;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+/**
+ * 区域节点，包括国家、省份、城市、地区等信息
+ *
+ * 数据可见 resources/area.csv 文件
+ *
+ * @author 芋道源码
+ */
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+public class Area {
+
+    /**
+     * 编号 - 全球，即根目录
+     */
+    public static final Integer ID_GLOBAL = 0;
+    /**
+     * 编号 - 中国
+     */
+    public static final Integer ID_CHINA = 1;
+
+    /**
+     * 编号
+     */
+    private Integer id;
+    /**
+     * 名字
+     */
+    private String name;
+    /**
+     * 类型
+     *
+     * 枚举 {@link AreaTypeEnum}
+     */
+    private Integer type;
+
+    /**
+     * 父节点
+     */
+    private Area parent;
+    /**
+     * 子节点
+     */
+    private List<Area> children;
+
+}

yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/java/cn/iocoder/yudao/framework/ip/core/enums/AreaTypeEnum.java

+package cn.iocoder.yudao.framework.ip.core.enums;
+
+import cn.iocoder.yudao.framework.common.core.IntArrayValuable;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+import java.util.Arrays;
+
+/**
+ * 区域类型枚举
+ *
+ * @author 芋道源码
+ */
+@AllArgsConstructor
+@Getter
+public enum AreaTypeEnum implements IntArrayValuable {
+
+    COUNTRY(1, "国家"),
+    PROVINCE(2, "省份"),
+    CITY(3, "城市"),
+    DISTRICT(4, "地区"), // 县、镇、区等
+    ;
+
+    public static final int[] ARRAYS = Arrays.stream(values()).mapToInt(AreaTypeEnum::getType).toArray();
+
+    /**
+     * 类型
+     */
+    private final Integer type;
+    /**
+     * 名字
+     */
+    private final String name;
+
+    @Override
+    public int[] array() {
+        return ARRAYS;
+    }
+}

yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/java/cn/iocoder/yudao/framework/ip/core/utils/AreaUtils.java

+package cn.iocoder.yudao.framework.ip.core.utils;
+
+import cn.hutool.core.io.resource.ResourceUtil;
+import cn.hutool.core.lang.Assert;
+import cn.hutool.core.text.csv.CsvRow;
+import cn.hutool.core.text.csv.CsvUtil;
+import cn.iocoder.yudao.framework.common.util.object.ObjectUtils;
+import cn.iocoder.yudao.framework.ip.core.Area;
+import cn.iocoder.yudao.framework.ip.core.enums.AreaTypeEnum;
+import lombok.extern.slf4j.Slf4j;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 区域工具类
+ *
+ * @author 芋道源码
+ */
+@Slf4j
+public class AreaUtils {
+
+    /**
+     * 初始化 SEARCHER
+     */
+    @SuppressWarnings("InstantiationOfUtilityClass")
+    private final static AreaUtils INSTANCE = new AreaUtils();
+
+    /**
+     * Area 内存缓存，提升访问速度
+     */
+    private static Map<Integer, Area> areas;
+
+    private AreaUtils() {
+        long now = System.currentTimeMillis();
+        areas = new HashMap<>();
+        areas.put(Area.ID_GLOBAL, new Area(Area.ID_GLOBAL, "全球", 0,
+                null, new ArrayList<>()));
+        // 从 csv 中加载数据
+        List<CsvRow> rows = CsvUtil.getReader().read(ResourceUtil.getUtf8Reader("area.csv")).getRows();
+        rows.remove(0); // 删除 header
+        for (CsvRow row : rows) {
+            // 创建 Area 对象
+            Area area = new Area(Integer.valueOf(row.get(0)), row.get(1), Integer.valueOf(row.get(2)),
+                    null, new ArrayList<>());
+            // 添加到 areas 中
+            areas.put(area.getId(), area);
+        }
+
+        // 构建父子关系：因为 Area 中没有 parentId 字段，所以需要重复读取
+        for (CsvRow row : rows) {
+            Area area = areas.get(Integer.valueOf(row.get(0))); // 自己
+            Area parent = areas.get(Integer.valueOf(row.get(3))); // 父
+            Assert.isTrue(area != parent, "{}:父子节点相同", area.getName());
+            area.setParent(parent);
+            parent.getChildren().add(area);
+        }
+        log.info("启动加载 AreaUtils 成功，耗时 ({}) 毫秒", System.currentTimeMillis() - now);
+    }
+
+    /**
+     * 获得指定编号对应的区域
+     *
+     * @param id 区域编号
+     * @return 区域
+     */
+    public static Area getArea(Integer id) {
+        return areas.get(id);
+    }
+
+    /**
+     * 格式化区域
+     *
+     * @param id 区域编号
+     * @return 格式化后的区域
+     */
+    public static String format(Integer id) {
+        return format(id, " ");
+    }
+
+    /**
+     * 格式化区域
+     *
+     * 例如说：
+     *      1. id = “静安区”时：上海 上海市 静安区
+     *      2. id = “上海市”时：上海 上海市
+     *      3. id = “上海”时：上海
+     *      4. id = “美国”时：美国
+     * 当区域在中国时，默认不显示中国
+     *
+     * @param id 区域编号
+     * @param separator 分隔符
+     * @return 格式化后的区域
+     */
+    public static String format(Integer id, String separator) {
+        // 获得区域
+        Area area = areas.get(id);
+        if (area == null) {
+            return null;
+        }
+
+        // 格式化
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < AreaTypeEnum.values().length; i++) { // 避免死循环
+            sb.insert(0, area.getName());
+            // “递归”父节点
+            area = area.getParent();
+            if (area == null
+                || ObjectUtils.equalsAny(area.getId(), Area.ID_GLOBAL, Area.ID_CHINA)) { // 跳过父节点为中国的情况
+                break;
+            }
+            sb.insert(0, separator);
+        }
+        return sb.toString();
+    }
+
+}

yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/java/cn/iocoder/yudao/framework/ip/core/utils/IPUtils.java

+package cn.iocoder.yudao.framework.ip.core.utils;
+
+import cn.hutool.core.io.resource.ResourceUtil;
+import cn.iocoder.yudao.framework.ip.core.Area;
+import lombok.SneakyThrows;
+import lombok.extern.slf4j.Slf4j;
+import org.lionsoul.ip2region.xdb.Searcher;
+
+import java.io.IOException;
+
+/**
+ * IP 工具类
+ *
+ * IP 数据源来自 ip2region.xdb 精简版，基于 <a href="https://gitee.com/zhijiantianya/ip2region"/> 项目
+ *
+ * @author wanglhup
+ */
+@Slf4j
+public class IPUtils {
+
+    /**
+     * 初始化 SEARCHER
+     */
+    @SuppressWarnings("InstantiationOfUtilityClass")
+    private final static IPUtils INSTANCE = new IPUtils();
+
+    /**
+     * IP 查询器，启动加载到内存中
+     */
+    private static Searcher SEARCHER;
+
+    /**
+     * 私有化构造
+     */
+    private IPUtils() {
+        try {
+            long now = System.currentTimeMillis();
+            byte[] bytes = ResourceUtil.readBytes("ip2region.xdb");
+            SEARCHER = Searcher.newWithBuffer(bytes);
+            log.info("启动加载 IPUtils 成功，耗时 ({}) 毫秒", System.currentTimeMillis() - now);
+        } catch (IOException e) {
+            log.error("启动加载 IPUtils 失败", e);
+        }
+    }
+
+    /**
+     * 查询 IP 对应的地区编号
+     *
+     * @param ip IP 地址，格式为 127.0.0.1
+     * @return 地区id
+     */
+    @SneakyThrows
+    public static Integer getAreaId(String ip) {
+        return Integer.parseInt(SEARCHER.search(ip));
+    }
+
+    /**
+     * 查询 IP 对应的地区编号
+     *
+     * @param ip IP 地址的时间戳，格式参考{@link Searcher#checkIP(String)} 的返回
+     * @return 地区编号
+     */
+    @SneakyThrows
+    public static Integer getAreaId(long ip) {
+        return Integer.parseInt(SEARCHER.search(ip));
+    }
+
+    /**
+     * 查询 IP 对应的地区
+     *
+     * @param ip IP 地址，格式为 127.0.0.1
+     * @return 地区
+     */
+    public static Area getArea(String ip) {
+        return AreaUtils.getArea(getAreaId(ip));
+    }
+
+    /**
+     * 查询 IP 对应的地区
+     *
+     * @param ip IP 地址的时间戳，格式参考{@link Searcher#checkIP(String)} 的返回
+     * @return 地区
+     */
+    public static Area getArea(long ip) {
+        return AreaUtils.getArea(getAreaId(ip));
+    }
+}

yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/java/cn/iocoder/yudao/framework/ip/package-info.java

+/**
+ * IP 拓展，支持如下功能：
+ *
+ * 1. IP 功能：查询 IP 对应的城市信息
+ *      基于 https://gitee.com/lionsoul/ip2region 实现
+ * 2. 城市功能：查询城市编码对应的城市信息
+ *      基于 https://github.com/modood/Administrative-divisions-of-China 实现
+ *
+ * @author 芋道源码
+ */
+package cn.iocoder.yudao.framework.ip;

yudao-framework/yudao-spring-boot-starter-biz-ip/src/test/java/cn/iocoder/yudao/framework/ip/core/utils/AreaUtilsTest.java

+package cn.iocoder.yudao.framework.ip.core.utils;
+
+
+import cn.iocoder.yudao.framework.ip.core.Area;
+import cn.iocoder.yudao.framework.ip.core.enums.AreaTypeEnum;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * {@link AreaUtils} 的单元测试
+ *
+ * @author 芋道源码
+ */
+public class AreaUtilsTest {
+
+    @Test
+    public void testGetArea() {
+        // 调用：北京
+        Area area = AreaUtils.getArea(110100);
+        // 断言
+        assertEquals(area.getId(), 110100);
+        assertEquals(area.getName(), "北京市");
+        assertEquals(area.getType(), AreaTypeEnum.CITY.getType());
+        assertEquals(area.getParent().getId(), 110000);
+        assertEquals(area.getChildren().size(), 16);
+    }
+
+    @Test
+    public void testFormat() {
+        assertEquals(AreaUtils.format(110105), "北京 北京市 朝阳区");
+        assertEquals(AreaUtils.format(1), "中国");
+        assertEquals(AreaUtils.format(2), "蒙古");
+    }
+
+}

yudao-framework/yudao-spring-boot-starter-biz-ip/src/test/java/cn/iocoder/yudao/framework/ip/core/utils/IPUtilsTest.java

+package cn.iocoder.yudao.framework.ip.core.utils;
+
+import cn.iocoder.yudao.framework.ip.core.Area;
+import org.junit.jupiter.api.Test;
+import org.lionsoul.ip2region.xdb.Searcher;
+
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * {@link IPUtils} 的单元测试
+ *
+ * @author wanglhup
+ */
+public class IPUtilsTest {
+
+    @Test
+    public void testGetAreaId_string() {
+        // 120.202.4.0|120.202.4.255|420600
+        Integer areaId = IPUtils.getAreaId("120.202.4.50");
+        assertEquals(420600, areaId);
+    }
+
+    @Test
+    public void testGetAreaId_long() throws Exception {
+        // 120.203.123.0|120.203.133.255|360900
+        long ip = Searcher.checkIP("120.203.123.250");
+        Integer areaId = IPUtils.getAreaId(ip);
+        assertEquals(360900, areaId);
+    }
+
+    @Test
+    public void testGetArea_string() {
+        // 120.202.4.0|120.202.4.255|420600
+        Area area = IPUtils.getArea("120.202.4.50");
+        assertEquals("襄阳市", area.getName());
+    }
+
+    @Test
+    public void testGetArea_long() throws Exception {
+        // 120.203.123.0|120.203.133.255|360900
+        long ip = Searcher.checkIP("120.203.123.252");
+        Area area = IPUtils.getArea(ip);
+        assertEquals("宜春市", area.getName());
+    }
+
+}

yudao-framework/yudao-spring-boot-starter-biz-pay/pom.xml

@@ -3,8 +3,8 @@
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <parent>
-        <artifactId>yudao-framework</artifactId>
         <groupId>cn.iocoder.cloud</groupId>
+        <artifactId>yudao-framework</artifactId>
         <version>${revision}</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>

yudao-module-system/yudao-module-system-biz/pom.xml

@@ -74,6 +74,10 @@
             <groupId>cn.iocoder.cloud</groupId>
             <artifactId>yudao-spring-boot-starter-biz-error-code</artifactId>
         </dependency>
+        <dependency>
+            <groupId>cn.iocoder.cloud</groupId>
+            <artifactId>yudao-spring-boot-starter-biz-ip</artifactId>
+        </dependency>
 
         <!-- Web 相关 -->
         <dependency>

yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/controller/admin/ip/AreaController.http

+### 获得地区树
+GET {{baseUrl}}/system/area/tree
+Authorization: Bearer {{token}}
+tenant-id: {{adminTenentId}}
+

yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/controller/admin/ip/AreaController.java

+package cn.iocoder.yudao.module.system.controller.admin.ip;
+
+import cn.hutool.core.lang.Assert;
+import cn.iocoder.yudao.framework.common.pojo.CommonResult;
+import cn.iocoder.yudao.framework.ip.core.Area;
+import cn.iocoder.yudao.framework.ip.core.utils.AreaUtils;
+import cn.iocoder.yudao.framework.ip.core.utils.IPUtils;
+import cn.iocoder.yudao.module.system.controller.admin.ip.vo.AreaNodeRespVO;
+import cn.iocoder.yudao.module.system.convert.ip.AreaConvert;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiOperation;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
+
+@Api(tags = "管理后台 - 地区")
+@RestController
+@RequestMapping("/system/area")
+@Validated
+public class AreaController {
+
+    @GetMapping("/tree")
+    @ApiOperation("获得地区树")
+    public CommonResult<List<AreaNodeRespVO>> getAreaTree() {
+        Area area = AreaUtils.getArea(Area.ID_CHINA);
+        Assert.notNull(area, "获取不到中国");
+        return success(AreaConvert.INSTANCE.convertList(area.getChildren()));
+    }
+
+    @GetMapping("/get-by-ip")
+    @ApiOperation("获得 IP 对应的地区名")
+    @ApiImplicitParam(name = "ip", value = "IP", required = true, dataTypeClass = String.class)
+    public CommonResult<String> getAreaByIp(@RequestParam("ip") String ip) {
+        // 获得城市
+        Area area = IPUtils.getArea(ip);
+        if (area == null) {
+            return success("未知");
+        }
+        // 格式化返回
+        return success(AreaUtils.format(area.getId()));
+    }
+
+}

yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/controller/admin/ip/vo/AreaNodeRespVO.java

+package cn.iocoder.yudao.module.system.controller.admin.ip.vo;
+
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
+
+import java.util.List;
+
+@ApiModel("管理后台 - 地区节点 Response VO")
+@Data
+public class AreaNodeRespVO {
+
+    @ApiModelProperty(value = "编号", required = true, example = "110000")
+    private Integer id;
+
+    @ApiModelProperty(value = "名字", required = true, example = "北京")
+    private String name;
+
+    /**
+     * 子节点
+     */
+    private List<AreaNodeRespVO> children;
+
+}

yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/convert/ip/AreaConvert.java

+package cn.iocoder.yudao.module.system.convert.ip;
+
+import cn.iocoder.yudao.framework.ip.core.Area;
+import cn.iocoder.yudao.module.system.controller.admin.ip.vo.AreaNodeRespVO;
+import org.mapstruct.Mapper;
+import org.mapstruct.factory.Mappers;
+
+import java.util.List;
+
+@Mapper
+public interface AreaConvert {
+
+    AreaConvert INSTANCE = Mappers.getMapper(AreaConvert.class);
+
+    List<AreaNodeRespVO> convertList(List<Area> list);
+
+}