Geo 优化源码二次开发：自定义地域规则改造实操文档

1. 引言

在分布式系统、内容分发网络（CDN）或精准营销等场景中，基于地理位置的优化（Geo Optimization）是提升服务质量和用户体验的关键技术。然而，开源或商业的 Geo 解决方案往往无法完全满足特定业务对地域划分、规则匹配和策略执行的个性化需求。因此，对 Geo 优化引擎的源码进行二次开发，实现自定义地域规则的改造，成为许多技术团队必须面对的挑战。

本文档旨在提供一份从零开始的实操指南，详细阐述如何对一款典型的 Geo 优化引擎（以开源项目 GeoEngine 为例）进行源码级二次开发，重点聚焦于自定义地域规则的改造流程。我们将覆盖环境准备、源码结构分析、核心接口扩展、数据模型改造、规则引擎集成、测试验证以及部署上线的完整闭环。

2. 环境与工具准备

在开始编码之前，请确保你的开发环境满足以下要求：

• 开发语言与版本：Java 11+（假设 GeoEngine 基于 Java）
• 构建工具：Maven 3.6+ 或 Gradle 7.x
• 版本控制：Git
• IDE：IntelliJ IDEA 或 Eclipse（具备良好的 Java 和 Maven/Gradle 支持）
• 测试工具：JUnit 5, Mockito
• 数据库（可选）：根据项目需要准备 PostgreSQL/MySQL 用于存储自定义地域数据。

首先，从官方仓库克隆 GeoEngine 源码：

git clone https://github.com/example/geo-engine.git
cd geo-engine
git checkout -b feature/custom-geo-rule v2.1.0 # 基于稳定版本创建分支

3. 源码结构概览与核心概念

理解现有代码结构是改造的前提。GeoEngine 的核心模块通常包括：

• geo-core：定义地域模型（如 Country, Province, City）、坐标解析和基础匹配算法。
• geo-rule-engine：规则加载、解析和执行的引擎。
• geo-data-loader：从数据库或文件加载预定义的地域数据。
• geo-api：对外提供的 HTTP 或 RPC 接口。

关键接口与类：

// 地域解析器接口
public interface GeoResolver {
    GeoLocation resolve(String ip);
}

// 规则匹配器接口
public interface RuleMatcher {
    boolean matches(GeoLocation location, Rule rule);
}

// 地域规则定义
public class Rule {
    private String id;
    private String name;
    private List<String> targetRegions; // 传统地域编码列表
    private Object action; // 执行动作
}

我们的改造目标是在不破坏原有 Rule 匹配逻辑的前提下，扩展其对"自定义地域"的支持。

4. 自定义地域数据模型设计

首先，需要设计存储自定义地域的数据结构。例如，我们允许用户定义"华东大区"、"重点城市群"等逻辑分组。

// 新增：自定义地域组实体
public class CustomGeoGroup {
    private Long id;
    private String groupId; // 业务唯一标识，如 "east-china-cluster"
    private String groupName;
    private String description;
    private List<CustomGeoMember> members; // 组成员列表
    private String creator;
    private LocalDateTime createTime;
}

// 新增：自定义地域组成员
public class CustomGeoMember {
    private Long id;
    private String groupId;
    private String memberType; // "COUNTRY", "PROVINCE", "CITY", "COORDINATE_RANGE"
    private String memberCode; // 对应标准地域编码或自定义坐标范围表达式
    private Map<String, Object> extraAttributes; // 扩展属性
}

同时，需要创建对应的数据库表（以 JPA 注解为例）：

CREATE TABLE custom_geo_group (
    id BIGINT PRIMARY KEY,
    group_id VARCHAR(64) UNIQUE NOT NULL,
    group_name VARCHAR(255),
    description TEXT,
    creator VARCHAR(64),
    create_time TIMESTAMP
);

CREATE TABLE custom_geo_member (
    id BIGINT PRIMARY KEY,
    group_id VARCHAR(64) NOT NULL,
    member_type VARCHAR(32) NOT NULL,
    member_code VARCHAR(512) NOT NULL,
    extra_attributes JSON,
    FOREIGN KEY (group_id) REFERENCES custom_geo_group(group_id)
);

5. 规则引擎扩展：支持自定义地域匹配

接下来，需要修改规则匹配逻辑，使其能识别并处理自定义地域组。

5.1 扩展 Rule 对象

在原有的 Rule 类中增加对自定义地域组的引用字段：

public class Rule {
    private String id;
    private String name;
    // 原有字段：基于标准地域编码
    private List<String> targetRegions;
    // 新增字段：支持自定义地域组ID列表
    private List<String> targetCustomGroupIds;
    private Object action;
    // getters and setters...
}

5.2 实现自定义地域匹配器

创建一个新的 CustomGeoRuleMatcher，实现 RuleMatcher 接口，专门处理 targetCustomGroupIds：

@Component
public class CustomGeoRuleMatcher implements RuleMatcher {

    @Autowired
    private CustomGeoGroupService groupService; // 自定义地域组服务
    @Autowired
    private StandardGeoMatcher standardMatcher; // 原有的标准地域匹配器

    @Override
    public boolean matches(GeoLocation location, Rule rule) {
        // 1. 如果规则未定义任何自定义组，直接交给标准匹配器
        if (rule.getTargetCustomGroupIds() == null || rule.getTargetCustomGroupIds().isEmpty()) {
            return standardMatcher.matches(location, rule);
        }

        // 2. 遍历所有自定义组，检查location是否属于任一组的成员
        for (String groupId : rule.getTargetCustomGroupIds()) {
            CustomGeoGroup group = groupService.loadGroup(groupId);
            if (group == null) {
                continue; // 组不存在，跳过
            }
            if (isLocationInGroup(location, group)) {
                return true; // 命中任一自定义组即匹配成功
            }
        }

        // 3. 自定义组未命中，回退到标准地域匹配
        return standardMatcher.matches(location, rule);
    }

    private boolean isLocationInGroup(GeoLocation location, CustomGeoGroup group) {
        for (CustomGeoMember member : group.getMembers()) {
            switch (member.getMemberType()) {
                case "COUNTRY":
                    if (location.getCountryCode().equals(member.getMemberCode())) {
                        return true;
                    }
                    break;
                case "PROVINCE":
                    if (location.getProvinceCode().equals(member.getMemberCode())) {
                        return true;
                    }
                    break;
                case "CITY":
                    if (location.getCityCode().equals(member.getMemberCode())) {
                        return true;
                    }
                    break;
                case "COORDINATE_RANGE":
                    if (isInCoordinateRange(location, member.getMemberCode())) {
                        return true;
                    }
                    break;
                // 可扩展其他成员类型
            }
        }
        return false;
    }

    private boolean isInCoordinateRange(GeoLocation location, String rangeExpression) {
        // 解析 rangeExpression (例如: "lat:[30,40];lng:[115,125]") 并判断
        // 实现略...
        return false;
    }
}

5.3 配置规则引擎使用新的匹配器

修改规则引擎的配置或工厂类，使其优先使用我们扩展后的匹配器链：

@Configuration
public class RuleEngineConfig {

    @Bean
    public RuleMatcher compositeRuleMatcher(CustomGeoRuleMatcher customMatcher,
                                             StandardGeoMatcher standardMatcher) {
        // 构建责任链：先尝试自定义匹配，再走标准匹配
        return (location, rule) -> {
            // 自定义匹配器内部已包含回退逻辑，直接调用即可
            return customMatcher.matches(location, rule);
        };
    }
}

6. API 层与管理界面改造

为了让业务方能够创建和管理自定义地域组，需要扩展后端 API 并建议前端增加相应管理界面。

6.1 新增 REST API

@RestController
@RequestMapping("/api/v1/custom-geo-groups")
public class CustomGeoGroupController {

    @PostMapping
    public ResponseEntity<CustomGeoGroup> createGroup(@RequestBody CustomGeoGroup group) {
        // 创建自定义地域组
        CustomGeoGroup saved = groupService.createGroup(group);
        return ResponseEntity.ok(saved);
    }

    @GetMapping("/{groupId}")
    public ResponseEntity<CustomGeoGroup> getGroup(@PathVariable String groupId) {
        // 查询组详情
        return ResponseEntity.ok(groupService.loadGroup(groupId));
    }

    @PostMapping("/{groupId}/members")
    public ResponseEntity<CustomGeoMember> addMember(@PathVariable String groupId,
                                                      @RequestBody CustomGeoMember member) {
        // 向组中添加成员
        return ResponseEntity.ok(groupService.addMember(groupId, member));
    }

    // 其他接口：更新、删除、列表查询等...
}

6.2 规则创建 API 支持自定义组

修改原有的规则创建/更新接口，请求体和响应体需要包含 targetCustomGroupIds 字段。

7. 测试策略

为确保改造质量，需要编写多层次测试：

• 单元测试 ：针对 CustomGeoRuleMatcher、CustomGeoGroupService 等核心类。
• 集成测试：启动嵌入式数据库，测试从 API 创建组到规则匹配的全流程。
• 性能测试：使用大量自定义组和规则，验证匹配性能是否在可接受范围内。

@SpringBootTest
public class CustomGeoRuleMatcherTest {

    @Autowired
    private CustomGeoRuleMatcher matcher;

    @Test
    void testMatches_LocationInCustomGroup() {
        GeoLocation location = new GeoLocation("CN", "ZJ", "HZ"); // 中国-浙江-杭州
        Rule rule = new Rule();
        rule.setTargetCustomGroupIds(List.of("east-china-cluster")); // 假设该组包含杭州

        assertTrue(matcher.matches(location, rule));
    }
}

8. 部署与上线 checklist

1. 数据库变更：执行新增表的 DDL 脚本。
2. 服务发布：将改造后的 GeoEngine 服务打包部署。
3. 数据迁移（如有）：将历史规则中隐含的自定义地域逻辑，转化为新的组数据。
4. 监控与告警：关注新接口的调用量、规则匹配成功率及耗时。
5. 回滚方案：准备快速回滚到旧版本的标准地域匹配模式。

9. 总结与扩展方向

通过上述步骤，我们成功对 GeoEngine 进行了二次开发，使其具备了灵活的自定义地域规则能力。关键点在于：数据模型扩展 、匹配逻辑解耦 以及向后兼容。未来还可以考虑：

• 支持更复杂的组嵌套关系（组内包含子组）。
• 实现地域组的版本管理，支持灰度发布。
• 提供可视化地图编辑器，用于绘制自定义地理围栏。
• 与配置中心集成，实现地域规则的动态热更新。

希望这份实操文档能为你的 Geo 优化源码二次开发之旅提供清晰的路径。开发过程中，请始终关注代码的可维护性和系统的稳定性，做好充分的测试和评审。