Spring Boot 与 MyBatis-Plus 空间几何数据集成指南

在 Spring Boot + MyBatis-Plus 技术栈中处理空间几何数据（如 Point、Polygon）时，开发者常面临配置繁琐、方言适配困难等问题。本文介绍开源项目 mybatis-plus-geometry，一个专为该场景设计的 Starter，它通过自动装配、注解映射和内置 GeoJSON 序列化，让空间数据的持久化与传输变得简单且规范。

一、背景与问题

在业务系统中集成地理空间能力时，Java 开发者通常选择 JTS (Java Topology Suite) 作为几何对象模型，同时依赖 MySQL 或 PostgreSQL/PostGIS 存储实际数据。但在 MyBatis-Plus 框架下，这三者的衔接并不平滑，主要挑战包括：

TypeHandler 碎片化：每个几何子类型（Point、LineString、Polygon 等）都需要自定义 TypeHandler，并与 WKB/WKT 编解码逻辑耦合，代码复用性低。
方言差异难以抽象：MySQL 与 PostgreSQL 在空间数据的二进制格式、函数名称、坐标顺序等方面存在差异，手动适配容易引入隐性问题。
前后端格式不一致：数据库内部使用 WKB 或特定编码，而前端地图组件普遍接受 GeoJSON，需要额外开发转换层。
MyBatis-Plus 配置易忽略 ：开启自动结果映射（autoResultMap = true）是 TypeHandler 生效的前提，但常被遗漏，导致字段读写出错。

这些重复性工作分散了业务开发的精力。mybatis-plus-geometry 将这些通用逻辑封装为 Starter，提供了一致的抽象与开箱即用的体验。

二、mybatis-plus-geometry 概述

mybatis-plus-geometry 是一个面向 Spring Boot 2.7+/3.x 和 MyBatis-Plus 3.5+ 的轻量级增强库。其核心目标是为 JTS 几何类型提供可靠的持久化支持，并自动适配主流空间数据库。

主要特性如下：

零配置集成：引入依赖后，Starter 自动注册所需的 TypeHandler、方言解析器及 Jackson 序列化模块。
注解驱动映射 ：通过 @PointTableField、@LineStringTableField、@PolygonTableField 等注解标记实体字段，无需编写 XML 或 TypeHandler。
MySQL / PostGIS 方言自适应：根据数据源元数据动态选择编码方式和空间函数，开发者无需关心底层差异。
内置 GeoJSON 序列化：依靠自定义的 Jackson 序列化器，JTS 对象可在 REST 响应中直接转换为标准 GeoJSON 格式。
SRID 支持：注解内可指定坐标参考系，确保读写时 SRID 信息的完整传递。
完全兼容 MyBatis-Plus 生态：支持条件构造器、分页、逻辑删除等常用功能。

三、传统方案与注解方案的对比

在未引入本 Starter 之前，一个典型的 Point 字段映射需要以下步骤：

java 复制代码

@Component
@MappedTypes(Point.class)
public class PointTypeHandler extends BaseTypeHandler<Point> {
    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, Point parameter, JdbcType jdbcType)
            throws SQLException {
        // 需自行区分数据库类型，决定写 WKB 还是 WKT
        ps.setBytes(i, new WKBWriter(2, true).write(parameter));
    }

    @Override
    public Point getNullableResult(ResultSet rs, String columnName) throws SQLException {
        byte[] bytes = rs.getBytes(columnName);
        return (Point) new WKBReader().read(bytes);
    }
    // 其余方法省略......
}

随后还需在实体类上指明 @TableName(autoResultMap = true) 并为每个字段添加 @TableField(typeHandler = PointTypeHandler.class)。当实体包含多个几何字段时，配置量线性增长。

使用 mybatis-plus-geometry 后，等效配置简化为：

java 复制代码

@Data
@TableName(value = "user_location", autoResultMap = true)
public class UserLocation {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String name;

    @PointTableField(srid = 4326)
    private Point location;
}

对比可见，代码量大幅减少，且方言细节完全被 Starter 内部处理，提高了可维护性。

四、Quick Start 示例

以下展示一个典型场景：存储用户位置信息，并通过 REST 接口以 GeoJSON 格式返回。

4.1 依赖配置

在 Maven 项目的 pom.xml 中添加：

xml 复制代码

<dependency>
    <groupId>io.github.yoy0o</groupId>
    <artifactId>mybatis-plus-geometry-starter</artifactId>
    <version>1.0.0</version>
</dependency>

同时确保已引入 MyBatis-Plus 及目标数据库驱动。

4.2 数据库准备

MySQL 建表语句：

sql 复制代码

CREATE TABLE user_location (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(50),
    location GEOMETRY NOT NULL SRID 4326,
    SPATIAL INDEX(location)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

PostgreSQL / PostGIS 建表语句：

sql 复制代码

CREATE EXTENSION IF NOT EXISTS postgis;

CREATE TABLE user_location (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(50),
    location GEOMETRY(Point, 4326)
);
CREATE INDEX idx_user_location_location ON user_location USING GIST (location);

两种数据库的 DDL 存在差异，但这对 Java 层是透明的。

4.3 实体与 Mapper

java 复制代码

@Data
@TableName(value = "user_location", autoResultMap = true)
public class UserLocation {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String name;

    @PointTableField(srid = 4326)
    private Point location;
}

@Mapper
public interface UserLocationMapper extends BaseMapper<UserLocation> {
}

4.4 控制器实现

java 复制代码

@RestController
@RequestMapping("/api/locations")
public class UserLocationController {

    @Autowired
    private UserLocationMapper mapper;

    @PostMapping
    public UserLocation save(@RequestBody UserLocation location) {
        mapper.insert(location);
        return location;
    }

    @GetMapping("/{id}")
    public UserLocation get(@PathVariable Long id) {
        return mapper.selectById(id);
    }
}

4.5 交互测试

发送 POST 请求：

json 复制代码

{
    "name": "张三",
    "location": {
        "type": "Point",
        "coordinates": [116.407, 39.904]
    }
}

返回的响应自动序列化为：

json 复制代码

{
    "id": 1,
    "name": "张三",
    "location": {
        "type": "Point",
        "coordinates": [116.407, 39.904]
    }
}

整个过程没有涉及任何 TypeHandler 代码或坐标格式转换。

五、关键配置与避坑

5.1 `autoResultMap = true` 的必要性

MyBatis-Plus 默认采用自动映射模式，这种模式不会激活字段级别的 TypeHandler。必须在 @TableName 注解中显式设置 autoResultMap = true，框架才会为实体生成 <resultMap>，并触发自定义 TypeHandler 的调用。这是许多初次接触空间数据持久化的开发者最容易遗漏的配置。

5.2 数据库方言自动识别

Starter 在启动阶段通过检测 JDBC 连接元数据判断数据库类型，并初始化对应的方言处理器。目前支持 MySQL 和 PostgreSQL（含 PostGIS 扩展）。若需扩展其他数据库，可通过实现 GeometryDialect 接口完成。

5.3 坐标顺序说明

MySQL 的几何类型内部采用 (x y) 顺序，与 GeoJSON 的 [longitude, latitude] 一致。
PostGIS 遵循 (longitude latitude) 即经度在前。Starter 在 WKB/WKT 编解码时已对齐到 JTS 的标准模型（x=经度, y=纬度），确保 GeoJSON 输出始终为 [lon, lat]。

5.4 SRID 处理

若数据库字段指定了 SRID（如 4326），应在注解中同步声明 srid = 4326。Starter 会据此在写入时附加 SRID 信息，并在读取时正确解析，避免坐标系错乱。

六、原理简析

整个处理链可抽象为以下流程：

复制代码

实体 JTS 对象 (Point/LineString/Polygon)
        │
        ▼
 GeometryTypeHandler (方言感知)
        │
        ▼
数据库方言适配器 ──→ 生成 WKB/WKT 字节/字符串
        │
        ▼
    PreparedStatement / ResultSet
        │
        ▼
 WKBReader / WKTReader 反序列化回 JTS 对象
        │
        ▼
  Jackson 序列化器 (GeometrySerializer)
        │
        ▼
     GeoJSON 字符串 (返回前端)

入库：TypeHandler 调用方言适配器，将 JTS 对象转换为与数据库匹配的二进制或文本表示，通过 JDBC 写入。
出库：ResultSet 获取原始数据后，再次使用方言指定的 Reader 重新构建 JTS 对象。
序列化 ：Spring Boot 的 Jackson 配置自动应用注册的 GeometrySerializer 和 GeometryDeserializer，完成与 GeoJSON 的互转。

所有组件均通过 Spring Boot 的自动装配机制加载，用户只需引入 Starter 即可生效。

七、总结

mybatis-plus-geometry 为 Spring Boot + MyBatis-Plus 技术栈提供了一套规范化的空间几何数据操作方案。它消除了 TypeHandler 的重复编写工作，弥合了不同数据库的方言差异，同时打通了后端持久化与前端 GeoJSON 之间的壁垒。

项目目前处于活跃维护状态，欢迎各位开发者使用、测试并反馈意见。无论是 GIS 领域的资深工程师，还是刚接触空间数据的后端开发者，都可以借助本项目快速构建规范的空间数据处理能力。

GitHub 仓库 ：https://github.com/Yoy0o/mybatis-plus-geometry

如果该项目对你的工作有所帮助，请给予 Star 支持。也欢迎提交 Issue 或 Pull Request，共同完善这一解决方案。

Spring Boot 与 MyBatis-Plus 空间几何数据集成指南