行政区划数据自定义导出指南：零代码/低代码实现高效数据格式转换

场景化需求拆解：你的数据需求属于哪类？

如何快速判断项目需要哪种行政区划数据格式？开发中常见的数据需求可分为三类：

• 前端级需求：仅需名称与层级关系的轻量数据（如地址选择组件）
• 分析级需求：包含完整编码体系的结构化数据（如BI报表系统）
• 系统级需求：符合特定数据库规范的关联数据（如CRM系统集成）

不同需求对应不同的数据提取策略，盲目导出全量数据会导致加载缓慢、存储冗余等问题。

核心功能解析：数据导出工具链全景

基础导出能力矩阵

项目提供三种核心导出方式，满足不同技术栈开发者需求：

导出方式	技术门槛	适用场景	灵活性
Shell脚本	低	快速获取标准格式	★★☆☆☆
Node.js API	中	定制化数据处理	★★★★☆
Python脚本	中	数据科学场景	★★★☆☆

数据字典速查

关键数据字段说明：

• code：12位行政区划编码（如110000代表北京市）
• name：标准行政区划名称
• parentCode：父级行政单位编码
• level：行政级别（1-5级分别对应省/市/县/乡/村）

实现路径：从需求到可用数据的3步落地法

路径一：零代码快速导出（3分钟上手）

如何在不编写代码的情况下获取可用数据？

1. 环境准备

   git clone https://gitcode.com/gh_mirrors/ad/Administrative-divisions-of-China
   cd Administrative-divisions-of-China
   npm install
   

   ✅ 检查点：确认dist目录下生成data.sqlite文件

2. 执行标准导出

   # 导出CSV格式
   npm run csv
   # 导出JSON格式
   npm run json
   

   ✅ 检查点：dist目录下生成provinces.csv、cities.csv等文件

3. 数据验证

   # 查看前10行数据
   head -n 10 dist/provinces.csv
   

路径二：低代码自定义导出（10分钟定制）

如何只导出省市区三级数据用于前端组件？

1. 创建Python提取脚本

   import sqlite3
   import csv
   
   # 连接数据库
   conn = sqlite3.connect('dist/data.sqlite')
   cursor = conn.cursor()
   
   # 查询省市区三级数据并关联
   query = """
   SELECT p.code AS province_code, p.name AS province_name,
          c.code AS city_code, c.name AS city_name,
          d.code AS district_code, d.name AS district_name
   FROM province p
   LEFT JOIN city c ON p.code = c.provinceCode
   LEFT JOIN district d ON c.code = d.cityCode
   ORDER BY p.code, c.code, d.code
   """
   
   # 执行查询并写入CSV
   with open('dist/division_3level.csv', 'w', newline='') as f:
       writer = csv.writer(f)
       # 写入表头
       writer.writerow(['province_code', 'province_name', 'city_code', 'city_name', 'district_code', 'district_name'])
       # 写入数据
       for row in cursor.execute(query):
           writer.writerow(row)
   
   conn.close()
   

2. 添加执行权限并运行

   chmod +x export_3level.sh
   ./export_3level.sh
   

   ✅ 检查点：确认输出文件包含6列数据且无重复

数据校验与清洗：确保数据质量的关键步骤

必做的数据检查项

如何避免导出数据中存在无效信息？

1. 完整性校验

   # 检查省级数据完整性
   def check_province_coverage():
       import sqlite3
       conn = sqlite3.connect('dist/data.sqlite')
       cursor = conn.cursor()
       cursor.execute("SELECT COUNT(*) FROM province")
       count = cursor.fetchone()[0]
       conn.close()
       # 中国大陆共34个省级行政区（含港澳台）
       return count == 34
   
   if not check_province_coverage():
       print("警告：省级数据不完整")
   

2. 层级关系验证

   • 所有市级数据必须关联有效的省级编码
   • 编码长度必须符合规范（省级6位，市级8位，县级10位）

3. 重复数据清洗

   -- 查找重复名称的行政区
   SELECT name, COUNT(*) FROM district GROUP BY name HAVING COUNT(*) > 1;
   

应用拓展：从基础导出到业务系统集成

层级关系提取高级技巧

如何构建前端多级联动组件所需的JSON结构？

// 使用Node.js API构建树形结构
const fs = require('fs');
const division = require('./lib/export');

// 构建省市区三级树形数据
const treeData = division.provinces.map(province => ({
  value: province.code,
  label: province.name,
  children: province.cities.map(city => ({
    value: city.code,
    label: city.name,
    children: city.districts.map(district => ({
      value: district.code,
      label: district.name
    }))
  }))
}));

// 保存为JSON文件
fs.writeFileSync('dist/division_tree.json', JSON.stringify(treeData, null, 2));

增量更新策略

如何只获取最新变更的行政区划数据？

1. 建立更新日志表

   CREATE TABLE IF NOT EXISTS update_log (
     code TEXT PRIMARY KEY,
     update_time DATETIME,
     change_type TEXT
   );
   

2. 编写增量导出脚本

   # 导出30天内更新的数据
   sqlite3 -header -csv ./dist/data.sqlite "
   SELECT d.* FROM district d
   JOIN update_log ul ON d.code = ul.code
   WHERE ul.update_time > date('now', '-30 days')
   ORDER BY d.code;" > ./dist/recent_changes.csv
   

避坑指南：数据导出常见问题解决方案

性能优化

🔍 问题：导出全量数据时内存占用过高
方案：采用流式处理而非一次性加载

// 流式导出大文件示例
const { createWriteStream } = require('fs');
const { pipeline } = require('stream');
const { createSqliteStream } = require('./lib/stream-export');

pipeline(
  createSqliteStream('SELECT * FROM village'),
  createWriteStream('dist/villages.csv'),
  (err) => {
    if (err) console.error('导出失败:', err);
    else console.log('导出完成');
  }
);

数据一致性

📊 问题：不同层级数据编码不匹配
方案：添加校验规则

def validate_code_hierarchy(province_code, city_code):
    # 市级编码前6位应与所属省级编码一致
    return city_code.startswith(province_code[:6])

格式兼容性

⚙️ 问题：导出的CSV在Excel中显示乱码
方案：指定UTF-8 BOM编码

# 添加BOM头解决Excel乱码问题
echo -e '\ufeff' > dist/with_bom.csv && cat dist/provinces.csv >> dist/with_bom.csv

通过本文介绍的方法，你可以根据实际需求灵活定制行政区划数据导出方案，无论是简单的CSV文件还是复杂的树形结构，都能通过零代码或低代码方式快速实现。关键在于明确数据需求，选择合适的工具链，并做好数据校验工作，确保最终数据的准确性和可用性。