Java JSON 實現省市二級聯動完整代碼方案

前後端分離架構下的省市聯動：JSON 數據結構設計與前端渲染最佳實踐

省市區三級聯動是表單開發高頻需求。本文提供從後端數據組裝、JSON 序列化、前端 jQuery/Vue 渲染、懶加載優化的完整方案代碼。

後端：構建樹形 JSON 數據結構

// 實體類
@Data
public class Area {
    private Long id;
    private String name;
    private Long parentId;
    private List children = new ArrayList<>();
}

// Service 組裝樹形結構
@Service
public class AreaService {
    @Autowired private AreaMapper areaMapper;
    
    public List getProvinceList() {
        // 1. 查詢所有省 (parentId=0 或 1)
        List provinces = areaMapper.selectByParentId(0L);
        // 2. 批量查詢所有市 (優化：一次查詢所有子節點，記憶體組裝)
        List allCities = areaMapper.selectByParentIds(
            provinces.stream().map(Area::getId).collect(Collectors.toList())
        );
        // 3. 記憶體中構建映射關係
        Map> cityMap = allCities.stream()
            .collect(Collectors.groupingBy(Area::getParentId));
        provinces.forEach(p -> p.setChildren(cityMap.getOrDefault(p.getId(), Collections.emptyList())));
        return provinces;
    }
    
    // 懶加載接口：按需查詢市/區
    public List getChildren(Long parentId) {
        return areaMapper.selectByParentId(parentId);
    }
}

// Controller 返回 JSON
@RestController
@RequestMapping("/api/area")
public class AreaController {
    @Autowired private AreaService areaService;
    
    @GetMapping("/provinces")
    public Result> provinces() {
        return Result.success(areaService.getProvinceList());
    }
    
    @GetMapping("/children/{parentId}")
    public Result> children(@PathVariable Long parentId) {
        return Result.success(areaService.getChildren(parentId));
    }
}

前端方案一：jQuery 經典渲染 (兼容舊專案)

請選擇省份
請選擇城市
請選擇區縣

前端方案二：Vue 3 組合式 API 現代寫法 (推薦新專案)

JSON 數據結構設計建議

生產環境優化清單

• 緩存策略： 省市區數據極少變更，Redis 緩存 24h+，接口加 @Cacheable
• CDN 靜態化： 省份列表生成靜態 JS 文件部署 CDN，瀏覽器直接緩存
• 防抖節流： 搜索框輸入聯想 300ms 防抖
• 索引優化： 數據表建立 idx_parent_id，查詢毫秒級
• 國際化： 字段擴展 name_zh, name_en, name_hk，前端按 locale 顯示
• 直轄市特殊處理： 北京/上海/天津/重慶 省市合一，前端邏輯自動跳過市級選擇

常見坑點避坑指南

• ❌ 城市列表未清空直接 append → 切換省份時殘留舊數據
• ❌ 未禁用下級選擇器 → 用戶可選擇無效組合 (如選廣東省卻顯示北京市)
• ❌ 表單回顯時未觸發 change 事件 → 編輯地址時下級不聯動
• ✅ 回顯邏輯：先設省份值 → 手動觸發 change → 異步載入市 → 設市值 → 觸發 change → 載入區 → 設區值

省市聯動看似簡單，處理好邊界情況、效能體驗、代碼可維護性，才是工程師的專業度體現。