姬轩亦脚手架做到第十期，地图服务这块终于是躲不过去了。倒不是说业务上有多刚需，而是几乎每个Java后端项目走到一定程度，都会被问到“能不能接个地图”“能不能在地图上标几个点”。尤其如果做的是校园类、园区类、设备管理类系统，地图点位展示基本是标配功能。与其每次从零查文档、重新踩坑，不如直接在脚手架里把地图服务做成一个通用模块，后面积累复用比什么都值钱。
这篇就把我在Java脚手架项目里集成地图服务的完整过程拆开讲明白，包括后端数据模型怎么设计、接口为什么返回GeoJSON、前端Vue3脚手架里怎么快速接入在线地图瓦片、坐标偏移这种经典坑怎么处理，以及联调时最容易出的几个问题。适合正在做Java脚手架、恰好需要地图模块的朋友参考，也适合那种“项目里只要一个能标注点位的地图页面，不想引入重型GIS引擎”的团队直接抄作业。
1. 需求梳理与整体设计
1.1 脚手架里为什么需要地图服务
先想清楚一个问题：脚手架作为一个基础工程，应该内置多少地图能力才算合理。我见过不少团队把高德地图、百度地图的JavaScript API直接写进业务代码里，每个业务模块各引一套，token散落各处，地图初始化代码复制粘贴三份，最后维护起来非常痛苦。这其实就是脚手架应该解决的问题——把地图能力收拢成一个公共模块，统一封装初始化、统一管理凭据、统一提供数据接口。
但注意，脚手架内置的东西不能太重。地图服务跟权限认证、日志、异常处理这些基础能力不一样，它不是所有项目都必须用的。所以设计原则应该是“插拔式”：脚手架里提供geo模块和对应前端组件，但默认不强制所有业务依赖它。想用的项目引入依赖、配置好参数就能跑，不想用的项目完全无感知。这就是为什么地图模块在脚手架里通常独立成一个starter或者独立目录，而不是写在core里。
1.2 技术选型：轻量第一，能跑就行
地图这块的技术选择其实很容易走极端。一端是ArcGIS、SuperMap这种重型GIS平台，功能强大但部署复杂、学习成本高，对脚手架项目来说完全是杀鸡用牛刀。另一端是纯手写Canvas画坐标，能画出来但缩放、平移、标注、弹窗全得自己实现，成本也不低。夹在中间的正解是开源WebGIS方案：前端用Leaflet，后端用MySQL自带的GIS功能，瓦片源用公开的在线地图服务。
为什么选Leaflet而不是Mapbox GL或者OpenLayers？最直接的原因是Leaflet足够小、足够轻，核心包压缩后不到40KB，API设计非常简单，十分钟就能上手。Mapbox GL功能更强但需要处理样式、token，OpenLayers体量更大，都超出了“脚手架里内置一个够用的地图”这个定位。至于后端，MySQL 8.0自带的Geo数据类型和空间索引已经能覆盖“点位标注”“区域圈选”这类需求，完全不值得为这个单独引入PostGIS。等以后真要做复杂空间分析时再拆出去也不迟。
这里还涉及一个选型原则：在线瓦片服务用标准XYZ模板就能访问的公开服务，不要整那些需要申请复杂鉴权的。开发阶段直接加载公共在线瓦片，等上线部署到内网再换成内网发布的瓦片服务即可。这样脚手架里不需要写死任何一家地图厂商的SDK，依赖干净、可替换性强。
1.3 模块拆分：geo模块该放什么
确定选型后，我在地图模块里规划了四块内容：实体和仓储层、接口层、前端组件、数据初始化脚本。实体和仓储层负责把地图点位、区域、路径数据落库；接口层对外提供GeoJSON格式的数据；前端组件是用Vue3封装好的地图组件，业务页面只要传数据进去就能渲染；数据初始化脚本是给开发者快速准备一堆测试点位用的，不然每次手动往数据库插点太痛苦了。
四个部分各司其职，但都围绕一个约定：前后端统一用GeoJSON作为地图数据交换格式。后端接口返回GeoJSON，前端组件接收GeoJSON。这个约定是整个模块的灵魂，下面细说。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 后端地图数据模型与接口实现
2.1 数据模型设计：点位、区域、路径三类数据
地图业务最常见的数据就三类：点、线、面。对应到具体场景就是：设备点位、巡检路线、服务范围区域。设计表结构时我统一用一个map_feature表来存，通过feature_type字段区分，而不是建三张表。原因很简单：三类数据都要维护创建时间、更新时间、名称、标签，公共字段抽出来共用一张表，工程上更清爽。
sql复制CREATE TABLE `map_feature` (
`id` bigint NOT NULL AUTO_INCREMENT,
`feature_type` varchar(20) NOT NULL COMMENT 'POINT / LINE / AREA',
`name` varchar(100) NOT NULL COMMENT '名称',
`latitude` decimal(10, 7) DEFAULT NULL,
`longitude` decimal(10, 7) DEFAULT NULL,
`geojson` json DEFAULT NULL COMMENT '完整GeoJSON数据',
`status` tinyint NOT NULL DEFAULT '1',
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
KEY `idx_feature_type` (`feature_type`),
KEY `idx_lng_lat` (`longitude`, `latitude`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT ='地图要素表';
两个关键设计点。第一，经纬度字段单独拎出来建索引，是为了按范围查询点位时能走索引，比如“查某个矩形区域的设备”，这种查询在Leaflet拖动地图、按视野加载数据时非常高频。第二，geojson字段用JSON类型存完整数据，是为了适配线的多点坐标和面的多点坐标，一条巡检路线可能是几十个坐标点串成的LineString，面则是Polygon，这类结构放不到单列字段里，直接用GeoJSON