测站沿革接口开发与调试记录

发表于 分类于

开发一个查询测站沿革信息列表的第三方API接口，调用水利系统基础数据API获取测站历史变更信息。开发完成后调试时遇到两个常见但容易忽略的问题：参数名错误和响应结构解析错误。

前言

在广东水文项目中，需要开发一个查询测站沿革信息列表的接口，调用第三方水利系统基础数据API获取测站的历史变更记录，包括站名变更、地址变更、所属行政区划调整等信息。这对于数据治理和历史追溯非常重要。

问题背景

项目需要对接水利系统的第三方API，获取测站的历史变更记录。

第三方API信息

项目 说明
请求路径 /stsc/openapi/listGrouped
请求方式 GET
必填参数 stcd（测站编码）

接口开发

实现方案

参考现有”大断面”接口的实现模式，采用 Controller-Biz-DTO 三层架构：

  1. DTO: StationEvolutionDTO - 测站沿革信息数据对象
  2. Biz: StationArchiveBiz.getStationEvolutions() - 业务逻辑层
  3. Controller: StationArchiveController.stationEvolution - 接口层

创建/修改的文件

类型 文件路径
新增 cnsci-admin/.../dto/station/StationEvolutionDTO.java
修改 cnsci-admin/.../biz/station/StationArchiveBiz.java
修改 cnsci-admin/.../station/StationArchiveController.java

接口调用示例

1
GET /stationArchive/stationEvolution?stcd=80505000

调试阶段：两个坑与修复

接口开发完成后，调用测试发现：直接请求第三方接口有数据返回，但通过我们开发的接口返回空数据。

坑一：参数名错误

层级 参数名
Controller 接收 stcd
Biz 层传给第三方 iid ❌
第三方接口需要 stcd

修复：

1
2
3
4
5
// 错误写法
params.put("iid", iid);

// 正确写法
params.put("stcd", iid);

坑二：响应结构解析错误

第三方返回：

1
2
3
4
{
  "total": 104,
  "rows": [...]
}

代码原期望：

1
2
3
4
5
{
  "data": {
    "rows": [...]
  }
}

修复：

1
2
3
4
5
6
// 错误写法
JSONObject data = response.getJSONObject("data");
JSONArray rows = data.getJSONArray("rows");

// 正确写法
JSONArray rows = response.getJSONArray("rows");

Git 操作技巧

在修复 Bug 时，使用 git reset --soft 可以撤销提交但保留修改在暂存区：

1
2
3
git reset --soft d16095b~1
git add cnsci-admin/.../StationArchiveBiz.java
git commit -m "fix: 修复测站沿革接口参数和响应解析问题"

经验总结

  • 调试技巧：遇到第三方接口返回空数据时，添加日志打印原始响应，快速定位响应结构问题
  • 接口对接：调用第三方API时，务必确认参数名和响应结构，不能想当然
  • Git 使用：git reset --soft 是调整提交历史的利器

结语

接口开发看似简单，但在对接第三方API时，参数名和响应结构这两个”小细节”往往是导致问题的根本原因。调试过程中养成打印日志的习惯，能够快速定位问题所在。