中国行政区划数据自定义导出指南：从需求到实现的完整路径

需求场景：为什么需要自定义行政区划数据导出

在实际开发过程中，我们经常会遇到各种基于行政区划数据的应用场景，但不同项目对数据格式的要求往往大相径庭：

• 电商平台：需要简洁的省市区三级联动数据用于收货地址选择
• 数据分析系统：要求包含完整编码和层级关系的详细数据用于地域分析
• 政务系统：需要符合特定标准的行政区划数据用于业务办理

这些不同的需求意味着我们不能简单使用固定格式的数据集，而需要根据实际场景进行灵活定制。

解决方案：三种自定义数据导出方法对比

方法一：直接修改导出脚本

这种方法适合快速调整输出字段和格式，无需编程知识，通过修改SQL查询即可实现定制。

适用场景对比：

适用场景	优势	局限性
简单字段筛选	操作简单，无需编程基础	无法实现复杂数据转换
快速格式调整	直接生效，无需额外依赖	不支持数据计算和逻辑处理
一次性导出需求	执行速度快	难以复用和维护

实施步骤：

1. 打开项目根目录下的export_csv.sh文件
2. 找到类似以下的SQL导出命令：

   # 原始命令：导出完整省份数据
   sqlite3 -header -csv ./dist/data.sqlite 'SELECT * FROM province ORDER BY code;' > ./dist/provinces.csv
   

3. 修改SELECT语句来选择需要的字段：

   # 只导出代码和名称字段
   sqlite3 -header -csv ./dist/data.sqlite 'SELECT code, name FROM province ORDER BY code;' > ./dist/provinces_simple.csv
   

4. 保存文件后运行脚本：bash export_csv.sh

方法二：使用Node.js进行高级数据处理

通过项目提供的Node.js API，可以实现更复杂的数据转换和处理逻辑，适合需要编程能力的高级定制需求。

适用场景对比：

适用场景	优势	局限性
复杂数据转换	支持各种数据处理逻辑	需要JavaScript编程基础
数据过滤和计算	可以实现复杂业务规则	执行效率相对较低
批量自动化处理	可集成到自动化流程	需要额外学习API使用

实施步骤：

1. 确保已安装项目依赖：npm install
2. 创建自定义导出脚本custom-export.js：

   // 引入核心模块
   const exportModule = require('./lib/export');
   const fs = require('fs');
   const path = require('path');
   
   // 自定义导出函数
   async function exportCustomData() {
     try {
       // 获取省份数据
       const provinces = await exportModule.getProvinces();
       
       // 处理数据 - 仅保留需要的字段并添加自定义属性
       const processedData = provinces.map(province => ({
         code: province.code,
         name: province.name,
         shortName: getShortName(province.name),
         level: 'province'
       }));
       
       // 保存为JSON文件
       const outputPath = path.join(__dirname, 'dist', 'custom_provinces.json');
       fs.writeFileSync(outputPath, JSON.stringify(processedData, null, 2));
       console.log(`自定义数据已导出至: ${outputPath}`);
     } catch (error) {
       console.error('导出失败:', error);
     }
   }
   
   // 辅助函数：获取省份简称
   function getShortName(fullName) {
     const shortNames = {
       '北京市': '北京',
       '上海市': '上海',
       // 其他省份简称映射...
     };
     return shortNames[fullName] || fullName;
   }
   
   // 执行导出
   exportCustomData();
   

3. 运行自定义脚本：node custom-export.js

方法三：直接操作SQLite数据库

对于熟悉SQL的开发者，可以直接操作项目的SQLite数据库文件，实现最灵活的数据查询和导出。

适用场景对比：

适用场景	优势	局限性
复杂查询需求	SQL功能强大，支持各种复杂查询	需要SQL知识
多表关联数据	可轻松实现表连接操作	需了解数据库结构
批量数据导出	执行效率高	命令行操作不够直观

实施步骤：

1. 确保系统已安装sqlite3工具
2. 直接连接数据库文件执行查询：

   # 启动sqlite3交互模式
   sqlite3 ./dist/data.sqlite
   
   # 在sqlite3终端中执行查询
   sqlite> .headers on
   sqlite> .mode csv
   sqlite> .output ./dist/city_with_province.csv
   sqlite> SELECT c.code, c.name, p.name as province_name 
           FROM city c 
           JOIN province p ON c.provinceCode = p.code 
           ORDER BY c.code;
   sqlite> .exit
   

实施步骤：从零开始的自定义导出流程

准备工作

1. 获取项目代码：

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

2. 安装依赖并初始化数据：

   npm install
   npm run build
   

实战案例：电商地址选择数据导出

假设我们需要为电商平台导出适合前端地址选择器的省市区三级联动数据：

1. 创建SQL脚本文件export_address_data.sql：

   -- 导出省份数据
   .headers on
   .mode csv
   .output ./dist/provinces.csv
   SELECT code, name FROM province ORDER BY code;
   
   -- 导出城市数据
   .output ./dist/cities.csv
   SELECT code, name, provinceCode FROM city ORDER BY code;
   
   -- 导出区县数据
   .output ./dist/districts.csv
   SELECT code, name, cityCode FROM district ORDER BY code;
   

2. 执行SQL脚本：

   sqlite3 ./dist/data.sqlite < export_address_data.sql
   

3. 创建合并脚本combine_address_data.js：

   const fs = require('fs');
   const csv = require('csv-parser');
   
   // 读取CSV文件并转换为JSON
   async function readCsvFile(filePath) {
     return new Promise((resolve, reject) => {
       const results = [];
       fs.createReadStream(filePath)
         .pipe(csv())
         .on('data', (data) => results.push(data))
         .on('end', () => resolve(results))
         .on('error', reject);
     });
   }
   
   // 主函数：合并三级数据
   async function combineAddressData() {
     try {
       // 读取省市区数据
       const provinces = await readCsvFile('./dist/provinces.csv');
       const cities = await readCsvFile('./dist/cities.csv');
       const districts = await readCsvFile('./dist/districts.csv');
       
       // 构建三级联动结构
       const addressData = provinces.map(province => {
         const provinceCities = cities
           .filter(city => city.provinceCode === province.code)
           .map(city => {
             const cityDistricts = districts
               .filter(district => district.cityCode === city.code);
             return { ...city, districts: cityDistricts };
           });
         return { ...province, cities: provinceCities };
       });
       
       // 保存为JSON文件
       fs.writeFileSync(
         './dist/address_3level.json', 
         JSON.stringify(addressData, null, 2)
       );
       console.log('三级联动地址数据生成成功！');
     } catch (error) {
       console.error('数据合并失败:', error);
     }
   }
   
   // 执行
   combineAddressData();
   

4. 安装csv-parser依赖并运行脚本：

   npm install csv-parser
   node combine_address_data.js
   

5. 最终在dist目录下生成address_3level.json文件，包含完整的省市区三级联动数据

扩展应用：数据字段与业务场景结合

数据字段解析与业务应用

行政区划数据包含多个核心字段，理解这些字段的含义和用途对于正确使用数据至关重要：

字段名	描述	业务应用场景
code	行政区划代码	作为唯一标识用于数据关联和查询
name	行政区划名称	用于UI展示和用户交互
provinceCode	所属省份代码	构建层级关系，实现数据联动
cityCode	所属城市代码	实现城市级数据过滤和聚合
areaCode	所属区县代码	区县级别数据统计和分析
streetCode	所属乡镇街道代码	更精细的地域数据分析

新增实用场景：物流配送范围管理系统

在物流配送系统中，我们需要根据行政区划数据定义不同区域的配送规则和费用：

1. 导出包含完整层级关系的数据：

   sqlite3 -header -csv ./dist/data.sqlite "
     SELECT p.code as provinceCode, p.name as provinceName,
            c.code as cityCode, c.name as cityName,
            d.code as districtCode, d.name as districtName
     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
   " > ./dist/delivery_areas.csv
   

2. 导入数据到物流系统的区域管理模块，设置不同区域的配送规则

3. 在用户下单时，根据收货地址的行政区划代码匹配对应的配送规则

附录：常见问题排查指南

导出文件为空或不完整

1. 检查数据文件是否存在：确认dist/data.sqlite文件已生成且大小正常
2. 验证SQL查询：单独执行SQL语句检查是否返回结果
3. 检查文件权限：确保当前用户对输出目录有写入权限

中文乱码问题

1. 指定字符编码：在导出命令中添加编码参数

   sqlite3 -header -csv -cmd ".encoding utf-8" ./dist/data.sqlite "SELECT * FROM province;" > provinces.csv
   

2. 检查文本编辑器设置：确保使用UTF-8编码打开CSV文件

Node.js脚本执行错误

1. 检查依赖安装：确保所有依赖已正确安装
2. 查看错误信息：根据控制台输出的错误信息定位问题
3. 验证API使用：参考lib/export.js文件中的函数定义，确保API调用正确

通过以上方法，你可以根据实际需求灵活定制行政区划数据，满足不同项目场景的数据格式要求。无论是简单的字段筛选还是复杂的多级联动数据生成，都能通过这些方法快速实现。关键在于理解数据结构和业务需求，选择最适合的定制方法。