Area Service | 云原生高性能行政区划 API

🔍

ES 智能分词模糊检索

基于 Elasticsearch 深度集成，支持中文分词、拼音首字母及多级地名模糊匹配。
输入 bj 定位北京，输入 四川泸州 亦可精准命中，提供极致的搜索体验。

Full-Text Search

⚡

堆外内存零拷贝流

采用 InputStream → ByteBuf → Network 直传架构，数据全程驻留堆外内存。仅需 8KB 微缓冲 即可处理百万级数据导出，零 GC 压力。在 1GB 内存限制下仍可高密度部署多实例。

Zero-Copy & Cloud Native

🛡️

高并发与极致稳定

基于 JDK 21 虚拟线程 重构并发模型，轻松应对流量洪峰。
配合 ZGC 可伸缩的低延迟垃圾收集器，实现毫秒级延迟与低 CPU 占用，确保服务长期稳定运行。

High Concurrency

📡 API 规范文档

https://slave.tooo.top/areas

本服务提供标准化的 RESTful 接口，所有响应均采用流式 JSON 输出，确保大数据量下的低延迟与高稳定性。

GET /areas/{code}

查询指定行政区划的完整元数据。

参数	类型	说明
`code`	Path	标准行政区划代码 (如：`110000`)

GET /areas/{code}/children

流式获取指定行政区划的直接子节点列表。

💡 性能提示： 采用零拷贝流式输出，数据直接从 ES 流向客户端，无堆内存占用。

参数	类型	说明
`code`	Path	父级行政区划代码

GET /areas

全局检索引擎，不传参数默认查询所有国家（根节点），支持多维度过滤与分页。offset 与 size 成对使用，searchAfter 用于 ES 深度分页。

🧠 匹配规则： 基于 ES 分词器，支持拼音首字母、中文模糊及多级地名组合。
示例：q = bj (北京), q = sc lz (四川泸州), q = 朝阳 (朝阳区)。

参数	类型	说明
`q`	Query	搜索关键字（非必传，不传默认查所有国家）
`filter`	Query	层级过滤器，逗号分隔：country,province,city,county,town
`offset`	Int	分页起始偏移量，默认 0，与 size 成对使用
`size`	Int	分页大小，默认 64
`searchAfter`	String	深层分页游标，结果超过 10000 条后使用

POST /areas

创建新的行政区划记录。

⚠️ 约束条件： 创建国家 (level: 0) 时，必须满足 parent_code == code。

                    请求示例：创建主权国家
                    {
                    "code": 408,
                    "parent_code": 408, // 自引用约束
                    "name": "朝鲜民主主义人民共和国",
                    "abbreviation": "朝鲜",
                    "alias": "北韩",
                    "location": { "lat": 39.03, "lon": 125.75 },
                    "level": 0
                    }
                

PUT /areas/{code}

全量更新指定实体的属性信息。

💻 集成调用示例