行政区划数据实战指南：5分钟解决地址联动难题

▍为什么选择Administrative-divisions-of-China项目？

在开发地址选择功能时，你是否曾因行政区划数据格式混乱而反复调试？是否在实现多级地址联动时因数据不全而影响用户体验？Administrative-divisions-of-China项目提供了一套完整的解决方案，让你轻松应对各类地址相关开发需求。本文将通过"问题-方案-实践"三段式框架，带你快速掌握行政区划数据的应用技巧，让地址功能开发效率提升80%。

▍数据结构深度解析：从基础到进阶

核心数据文件体系

项目提供了覆盖省、市、县、乡、村五级的完整行政区划数据，支持JSON和CSV两种常用格式，满足不同开发场景需求：

数据级别	JSON文件	CSV文件	适用场景
省级	provinces.json	provinces.csv	省份选择器
地级	cities.json	cities.csv	城市级数据筛选
县级	areas.json	areas.csv	区域划分统计
乡级	streets.json	streets.csv	物流配送范围界定
村级	villages.json	villages.csv	精细化地址管理

联动数据特色优势

针对多级地址选择场景，项目特别提供了预构建的联动数据文件，无需手动处理层级关系：

联动级别	普通版	带编码版	数据体积
省-市二级	pc.json	pc-code.json	~50KB
省-市-县三级	pca.json	pca-code.json	~300KB
省-市-县-乡四级	pcas.json	pcas-code.json	~2MB

▍本地化数据接口化方案：从文件到服务

环境准备与依赖安装

要使用项目提供的工具，首先需要准备开发环境：

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/ad/Administrative-divisions-of-China

# 进入项目目录
cd Administrative-divisions-of-China

# 安装依赖
npm install

数据导出与格式转换

项目提供了便捷的脚本工具，可快速导出所需格式的数据：

# 导出JSON格式数据
bash export_json.sh

# 导出CSV格式数据
bash export_csv.sh

执行完成后，数据文件将生成在项目的dist目录下，包含所有级别的行政区划数据。

SQLite数据库操作指南

项目数据同时存储在SQLite数据库中，提供更灵活的查询能力。以下是一个完整的查询示例：

const sqlite3 = require('sqlite3').verbose();

// 连接数据库（注意：首次使用需先运行导出脚本生成数据库文件）
const db = new sqlite3.Database('dist/data.sqlite', (err) => {
  if (err) {
    console.error('数据库连接失败:', err.message);
    return;
  }
  console.log('成功连接到行政区划数据库');
});

// 示例1: 查询所有省份
db.all("SELECT code, name FROM provinces ORDER BY code", (err, rows) => {
  if (err) {
    console.error('查询失败:', err.message);
    return;
  }
  
  console.log('=== 中国省份列表 ===');
  rows.forEach(row => {
    console.log(`${row.code} - ${row.name}`);
  });
});

// 示例2: 根据省份代码查询城市
const getCitiesByProvince = (provinceCode) => {
  return new Promise((resolve, reject) => {
    db.all(
      "SELECT code, name FROM cities WHERE provinceCode = ? ORDER BY code",
      [provinceCode],
      (err, rows) => {
        if (err) return reject(err);
        resolve(rows);
      }
    );
  });
};

// 使用异步函数查询广东省的城市
getCitiesByProvince('44')
  .then(cities => {
    console.log('\n=== 广东省城市列表 ===');
    cities.forEach(city => {
      console.log(`${city.code} - ${city.name}`);
    });
  })
  .catch(err => console.error('查询城市失败:', err.message))
  .finally(() => db.close());

▍实战业务场景：从理论到应用

场景一：电商平台地址选择器实现

📌 实现步骤：

1. 数据准备：使用pca-code.json作为三级联动数据源
2. 前端实现：

   <select id="province"></select>
   <select id="city"></select>
   <select id="area"></select>
   

3. 数据加载与联动逻辑：

   // 加载数据
   fetch('dist/pca-code.json')
     .then(response => response.json())
     .then(data => {
       const provinceSelect = document.getElementById('province');
       const citySelect = document.getElementById('city');
       const areaSelect = document.getElementById('area');
       
       // 填充省份
       data.forEach(province => {
         const option = document.createElement('option');
         option.value = province.code;
         option.textContent = province.name;
         provinceSelect.appendChild(option);
       });
       
       // 省份变化时更新城市
       provinceSelect.addEventListener('change', () => {
         const selectedProvince = data.find(p => p.code === provinceSelect.value);
         citySelect.innerHTML = '<option value="">请选择城市</option>';
         areaSelect.innerHTML = '<option value="">请选择区县</option>';
         
         if (selectedProvince && selectedProvince.children) {
           selectedProvince.children.forEach(city => {
             const option = document.createElement('option');
             option.value = city.code;
             option.textContent = city.name;
             citySelect.appendChild(option);
           });
         }
       });
       
       // 城市变化时更新区县
       citySelect.addEventListener('change', () => {
         const selectedProvince = data.find(p => p.code === provinceSelect.value);
         if (!selectedProvince) return;
         
         const selectedCity = selectedProvince.children.find(c => c.code === citySelect.value);
         areaSelect.innerHTML = '<option value="">请选择区县</option>';
         
         if (selectedCity && selectedCity.children) {
           selectedCity.children.forEach(area => {
             const option = document.createElement('option');
             option.value = area.code;
             option.textContent = area.name;
             areaSelect.appendChild(option);
           });
         }
       });
     });
   

场景二：物流配送区域智能划分

物流企业需要根据行政区划数据划分配送区域，优化配送路线：

const sqlite3 = require('sqlite3').verbose();
const db = new sqlite3.Database('dist/data.sqlite');

// 查询某个城市的所有区县，用于划分配送区域
function getDistrictsByCity(cityCode) {
  return new Promise((resolve, reject) => {
    db.all(
      `SELECT a.code, a.name, a.cityCode, c.name as cityName 
       FROM areas a
       JOIN cities c ON a.cityCode = c.code
       WHERE a.cityCode = ?`,
      [cityCode],
      (err, rows) => {
        if (err) return reject(err);
        resolve(rows);
      }
    );
  });
}

// 示例：查询上海市的所有区县
getDistrictsByCity('310000')
  .then(districts => {
    console.log(`上海市共有${districts.length}个区县:`);
    districts.forEach(district => {
      console.log(`${district.code} - ${district.name}`);
      
      // 实际应用中可根据区县划分配送区域
      // createDeliveryZone(district.code, district.name);
    });
  })
  .catch(console.error)
  .finally(() => db.close());

▍Postman模拟接口实战

虽然项目没有提供现成的API接口，但我们可以使用Postman模拟本地数据接口，方便前端开发和测试：

📌 配置步骤：

1. 首先运行数据导出脚本生成JSON数据文件
2. 打开Postman，创建新的Collection"行政区划数据API"
3. 创建GET请求，URL设置为本地文件路径：

   file:///path/to/Administrative-divisions-of-China/dist/provinces.json
   

4. 发送请求，即可获取省份数据
5. 为不同级别的数据创建相应的请求，形成完整的API集合

通过这种方式，前端开发者可以在后端接口未完成时，使用模拟数据进行开发，提高团队协作效率。

▍避坑指南：常见问题与解决方案

问题一：数据文件路径错误导致加载失败

错误表现：前端加载JSON文件时出现404错误
解决方案：确保数据文件已通过脚本导出，并检查文件路径是否正确。开发环境中可使用绝对路径，生产环境建议将数据文件部署到CDN。

问题二：行政区划代码与身份证前6位混淆

错误表现：使用行政区划代码验证身份证地址码时出现不匹配
解决方案：行政区划代码可能会随区域调整而变化，而身份证地址码是签发时的区划代码。建议在需要身份证验证场景下，使用专门的地址码映射表。

问题三：多级联动数据体积过大影响加载速度

错误表现：四级联动数据文件超过2MB，影响页面加载性能
解决方案：

1. 采用按需加载策略，先加载省级数据，用户选择后再加载对应市级数据
2. 使用gzip压缩数据文件，通常可减少60-70%的文件体积
3. 考虑后端接口动态返回数据，而非一次性加载全部数据

▍数据更新监控：保持数据时效性

行政区划数据并非一成不变，国家统计局每年都会更新部分区域划分。为确保数据准确性，建议建立定期更新机制：

自动更新脚本

创建一个定时任务，定期检查并更新数据：

#!/bin/bash
# save as update_data.sh

# 进入项目目录
cd /path/to/Administrative-divisions-of-China

# 拉取最新代码
git pull origin main

# 重新导出数据
npm install
bash export_json.sh
bash export_csv.sh

# 可选：通知管理员
echo "行政区划数据已更新至最新版本" | mail -s "数据更新通知" [e-mail]

配置定时任务

使用crontab设置每月自动更新：

# 每月1日凌晨3点执行更新
0 3 1 * * /path/to/update_data.sh >> /var/log/ad_data_update.log 2>&1

▍总结

Administrative-divisions-of-China项目为开发者提供了高质量的行政区划数据解决方案，通过本文介绍的本地化数据接口化方案，你可以快速实现各类地址相关功能。无论是电商平台的地址选择器，还是物流系统的区域划分，这套数据都能满足你的需求。记得定期更新数据，并注意避坑指南中提到的常见问题，让你的地址功能更加稳定可靠。

希望本文能帮助你5分钟解决地址联动难题，让开发效率提升一个台阶！如果你有其他使用技巧或业务场景，欢迎在项目 issues 中分享交流。