纯 Java 手写 TopoJSON 生成器：零依赖实战教程

三、纯 Java 代码实现 TopoJSON 生成

前面了解了 TopoJSON 的核心原理，接下来直接上「生产级简易工具类」，拆分核心模块实现，代码可直接复制到项目中使用，支持 GeoJSON 转 TopoJSON、多要素处理、弧段自动去重，全程零依赖第三方库。

3.1 基础结构与构造函数

先搭建工具类的基础结构，继承抽象转换器（可自行实现简单抽象类），定义核心常量和构造函数，支持默认配置和自定义配置，适配不同场景需求。

package com.example;
import com.example.model.Feature;
import com.example.model.Geometry;
import java.io.IOException;
import java.util.*;

/**
 * TopoJSON 生成器工具类（基础版本）
 *
 * 实现 {@link TopologyConverter} 接口，使用纯 Java 实现将 GeoJSON 格式转换为 TopoJSON 格式。
 * 不依赖任何第三方地理空间库
 *
 * 主要功能：
 * 将 GeoJSON FeatureCollection 转换为 TopoJSON
 * 将 GeoJSON Feature 转换为 TopoJSON
 * 支持 Polygon 和 MultiPolygon 几何类型
 * 自动去重相同的弧段以减小数据体积
 *
 * @version 2.0.0
 * @see TopologyConverter
 * @see AbstractTopologyConverter
 * @see TopologyConfig
 */
public class TopoJsonGenerator extends AbstractTopologyConverter {
    /** 转换器名称 */
    public static final String NAME = "TopoJsonGenerator";
    /** 转换器版本 */
    public static final String VERSION = "2.0.0";

    /**
     * 默认构造函数
     * 使用默认配置创建转换器
     */
    public TopoJsonGenerator() {
        super();
    }

    /**
     * 带配置的构造函数
     *
     * @param config 转换配置（如精度、是否复制属性等）
     */
    public TopoJsonGenerator(TopologyConfig config) {
        super(config);
    }

    /**
     * 获取转换器名称（实现接口方法）
     *
     * @return 转换器名称 "TopoJsonGenerator"
     */
    @Override
    public String getName() {
        return NAME;
    }
}

3.2 核心转换方法（GeoJSON 转 TopoJSON）

这部分是工具类的核心，实现 GeoJSON 字符串到 TopoJSON 字符串、TopoJSON Map 对象的转换，支持 Feature 和 FeatureCollection 两种 GeoJSON 类型，适配主流使用场景。

/**
 * 将 GeoJSON 字符串转换为 TopoJSON 字符串
 *
 * @param geoJson GeoJSON 格式的字符串
 * @return TopoJSON 格式的字符串
 * @throws RuntimeException 如果转换失败（如解析异常）
 */
@Override
public String convertGeoJsonToTopoJson(String geoJson) {
    try {
        // 先将 GeoJSON 转换为 TopoJSON Map 结构
        Map<String, Object> topology = convertGeoJsonToTopology(geoJson);
        // 将 Map 结构转为 JSON 字符串（toJson 方法需自行实现，纯原生无依赖）
        return toJson(topology);
    } catch (IOException e) {
        throw new RuntimeException("Failed to convert GeoJSON to TopoJSON", e);
    }
}

/**
 * 将 GeoJSON 字符串转换为 TopoJSON Map 对象（便于后续灵活处理）
 *
 * @param geoJson GeoJSON 格式的字符串
 * @return TopoJSON 格式的 Map 对象
 * @throws IllegalArgumentException 如果 GeoJSON 类型不支持（仅支持 Feature/FeatureCollection）
 */
@Override
public Map<String, Object> convertGeoJsonToTopology(String geoJson) {
    try {
        // 解析 GeoJSON 字符串为 Map（parseJson 方法需自行实现，纯原生无依赖）
        Map<String, Object> geoJsonMap = parseJson(geoJson);
        String type = (String) geoJsonMap.get("type");
        // 处理 FeatureCollection 类型（多个要素）
        if ("FeatureCollection".equals(type)) {
            @SuppressWarnings("unchecked")
            List<Map<String, Object>> featuresList = (List<Map<String, Object>>) geoJsonMap.get("features");
            return createTopologyFromFeatures(featuresList);
        }
        // 处理单个 Feature 类型
        else if ("Feature".equals(type)) {
            List<Map<String, Object>> singleFeature = new ArrayList<Map<String, Object>>();
            singleFeature.add(geoJsonMap);
            return createTopologyFromFeatures(singleFeature);
        }
        // 不支持的 GeoJSON 类型
        else {
            throw new IllegalArgumentException("Unsupported GeoJSON type: " + type);
        }
    } catch (IOException e) {
        throw new RuntimeException("Failed to parse GeoJSON", e);
    }
}

3.3 拓扑构建核心方法（弧段去重 + 要素组装）

这部分实现 TopoJSON 最核心的逻辑：将 GeoJSON 的 Feature 列表转换为 TopoJSON 结构，自动提取弧段、去重弧段，通过索引引用弧段，从根源实现数据轻量化。

/**
 * 将 GeoJSON Feature 列表（Map 形式）转换为 TopoJSON Map 结构
 * 内部将 Map 形式的 Feature 转为自定义 Feature 对象，便于后续处理
 *
 * @param featuresList Feature 列表的 Map 表示
 * @return TopoJSON 格式的 Map 结构
 */
private Map<String, Object> createTopologyFromFeatures(List<Map<String, Object>> featuresList) {
    List<Feature> features = new ArrayList<Feature>();
    // 遍历 Map 形式的 Feature，转为自定义 Feature 对象（封装 ID、几何信息、属性）
    for (Map<String, Object> featureMap : featuresList) {
        // 获取要素 ID（优先从配置的 ID 字段获取，无则用默认 ID）
        String id = (String) featureMap.get(config.getIdProperty());
        if (id == null) {
            id = (String) featureMap.get("id");
        }
        // 获取要素属性（支持配置是否复制属性）
        @SuppressWarnings("unchecked")
        Map<String, Object> properties = (Map<String, Object>) featureMap.get("properties");
        if (config.isCopyProperties() && properties == null) {
            properties = new HashMap<String, Object>();
        }
        // 解析几何信息（类型 + 坐标），封装为 Geometry 对象
        @SuppressWarnings("unchecked")
        Map<String, Object> geometryMap = (Map<String, Object>) featureMap.get("geometry");
        String geometryType = (String) geometryMap.get("type");
        Object coordinates = geometryMap.get("coordinates");
        Geometry geometry = new Geometry(geometryType, coordinates);
        features.add(new Feature(id, geometry, properties));
    }
    // 调用核心方法，从 Feature 列表创建 TopoJSON
    return createTopology(features);
}

/**
 * 从 Feature 列表创建 TopoJSON 结构（核心实现）
 *
 * 核心逻辑：
 * 1. 提取所有弧段，用 Map 记录弧段唯一标识，实现自动去重
 * 2. 用 arcs 数组存储所有唯一弧段，用索引关联
 * 3. 用 objects 对象存储要素，通过弧段索引引用 arcs 中的弧段
 *
 * @param features Feature 对象列表
 * @return TopoJSON 格式的 Map 结构
 */
public Map<String, Object> createTopology(List<Feature> features) {
    // 存储完整 TopoJSON 结构，用 LinkedHashMap 保证顺序
    Map<String, Object> topology = new LinkedHashMap<String, Object>();
    topology.put("type", "Topology"); // TopoJSON 标志性类型
    // 存储所有唯一弧段（arcs 核心数组）
    List<List<List<Double>>> arcs = new ArrayList<List<List<Double>>>();
    // 弧段去重核心：key=弧段唯一标识，value=弧段在 arcs 中的索引
    Map<String, Integer> arcIndexMap = new HashMap<String, Integer>();
    int arcIndex = 0; // 弧段索引计数器
    // 存储 TopoJSON 的 objects 部分（要素集合）
    Map<String, Object> objects = new LinkedHashMap<String, Object>();
    // 遍历每个 Feature，处理其几何信息，提取弧段
    for (Feature feature : features) {
        // 生成要素 ID（无 ID 则自动生成）
        String featureId = feature.getId() != null ? feature.getId() : "feature_" + objects.size();
        // 单个要素对象，存储该要素的类型、弧段引用、属性
        Map<String, Object> object = new LinkedHashMap<String, Object>();
        object.put("type", feature.getGeometry().getType());
        // 处理 Polygon 类型（多边形）
        if (feature.getGeometry().getType().equals("Polygon")) {
            @SuppressWarnings("unchecked")
            List<List<List<Double>>> rings = (List<List<List<Double>>>) feature.getGeometry().getCoordinates();
            List<List<Integer>> arcsList = new ArrayList<List<Integer>>();
            // 遍历多边形的每个环（外环 + 内环），提取弧段
            for (List<List<Double>> ring : rings) {
                // 生成弧段唯一标识，用于去重
                String arcKey = createArcKey(ring);
                Integer existingArcIndex = arcIndexMap.get(arcKey);
                // 弧段已存在，直接引用其索引
                if (existingArcIndex != null) {
                    arcsList.add(Collections.singletonList(existingArcIndex));
                }
                // 弧段不存在，添加到 arcs 数组，记录索引
                else {
                    arcsList.add(Collections.singletonList(arcIndex));
                    arcs.add(ring);
                    arcIndexMap.put(arcKey, arcIndex);
                    arcIndex++;
                }
            }
            // 关联该多边形的弧段索引
            object.put("arcs", arcsList);
        }
        // 处理 MultiPolygon 类型（多多边形）
        else if (feature.getGeometry().getType().equals("MultiPolygon")) {
            @SuppressWarnings("unchecked")
            List<List<List<List<Double>>>> polygons = (List<List<List<List<Double>>>>) feature.getGeometry().getCoordinates();
            List<List<List<Integer>>> arcsList = new ArrayList<List<List<Integer>>>();
            // 遍历每个多边形
            for (List<List<List<Double>>> polygon : polygons) {
                List<List<Integer>> polygonArcs = new ArrayList<List<Integer>>();
                // 遍历每个多边形的环，提取弧段
                for (List<List<Double>> ring : polygon) {
                    String arcKey = createArcKey(ring);
                    Integer existingArcIndex = arcIndexMap.get(arcKey);
                    if (existingArcIndex != null) {
                        polygonArcs.add(Collections.singletonList(existingArcIndex));
                    } else {
                        polygonArcs.add(Collections.singletonList(arcIndex));
                        arcs.add(ring);
                        arcIndexMap.put(arcKey, arcIndex);
                        arcIndex++;
                    }
                }
                arcsList.add(polygonArcs);
            }
            // 关联该多多边形的弧段索引
            object.put("arcs", arcsList);
        }
        // 若要素有属性，添加到要素对象中
        if (feature.getProperties() != null && !feature.getProperties().isEmpty()) {
            object.put("properties", feature.getProperties());
        }
        // 将要素添加到 objects 中
        objects.put(featureId, object);
    }
    // 组装完整 TopoJSON（arcs + objects）
    topology.put("arcs", arcs);
    topology.put("objects", objects);
    return topology;
}

3.4 辅助方法与使用示例

补充弧段唯一键生成方法（用于去重）、便捷工厂方法（快速创建 Feature），以及完整使用示例，复制即可运行，降低使用门槛。

System.out.println("=== Test 1: Basic Converter ===");
TopologyConverter converter = new TopoJsonGenerator();
System.out.println("Converter: " + converter.getName() + " v" + converter.getVersion());
String geoJson = "{\"type\":\"FeatureCollection\",\"features\":[" +
    "{\"type\":\"Feature\",\"id\":\"f1\",\"properties\":{\"name\":\"China\",\"population\":1400000000}," +
    "\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[73,18],[135,18],[135,54],[73,54],[73,18]]]}}," +
    "{\"type\":\"Feature\",\"id\":\"f2\",\"properties\":{\"name\":\"Japan\",\"population\":126000000}," +
    "\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[129,30],[146,30],[146,46],[129,46],[129,30]]]}}" +
    "]}";
String topoJson = converter.convertGeoJsonToTopoJson(geoJson);
System.out.println("Result:");
System.out.println(topoJson);

在 IDE 中运行代码可以看到信息输出表示成功。

代码核心说明

1. 结构设计：采用工具类设计，继承抽象转换器，支持默认配置和自定义配置，符合 Java 开发规范，可直接集成到 SpringBoot 等项目。
2. 核心能力：支持 GeoJSON（Feature/FeatureCollection）转 TopoJSON，自动去重弧段，支持 Polygon、MultiPolygon 两种常用几何类型，贴合实际业务场景。
3. 去重逻辑：通过 createArcKey 方法将弧段坐标拼接为唯一字符串，用 Map 记录弧段索引，避免重复存储，实现数据轻量化。
4. 便捷性：提供工厂方法快速创建 Feature，丰富的使用示例，降低开发门槛；纯原生实现，无需依赖第三方 GIS 库、JSON 库。
5. 可扩展性：可基于此扩展支持 LineString、MultiLineString 等几何类型，优化坐标精度、相对坐标存储等功能。

补充说明：工具类中依赖的 TopologyConverter、AbstractTopologyConverter、TopologyConfig、Feature、Geometry 类，均为自定义简单类，核心是封装配置、要素、几何信息。

四、总结

本文实现了纯 Java、零依赖、可直接运行的 TopoJSON 生成器工具类，相比简易实现，更贴合生产环境需求，核心价值如下：

1. 无技术栈限制：纯后端 Java 即可生成，无需 Node.js 等额外环境，无缝集成 Java 后端项目，解决跨语言依赖痛点。
2. 轻量化高效：遵循 TopoJSON 拓扑原理，自动去重弧段，大幅减少地理数据体积，提升前端加载速度和数据传输效率。
3. 扩展性极强：支持 Polygon、MultiPolygon 类型，可轻松扩展支持更多几何类型、坐标精度配置、相对坐标存储等功能。
4. 生产可用：代码结构清晰、注释完善，提供完整使用示例，可直接复制到项目中使用，适配 GIS 开发、数据可视化等多种场景。

基于本工具类，可以将数据库中的经纬度数据、GIS 矢量数据、前端传入的 GeoJSON 数据，直接转换为标准 TopoJSON，用于前端大屏、地图可视化、地理数据分析等场景。后续可进一步优化弧段去重效率、增加坐标压缩、支持更多 GeoJSON 类型，提升工具类的实用性。