政务与第三方系统对接的工程实践：万村乐的 API 网关编排与定时同步

数字乡村平台从来不是一座孤岛。政务通知要下发到村民、农产品订单要在线支付、寄出去的包裹要能查物流、村庄位置要能在地图上标点导航。万村乐这套系统在生产环境里实际要对接的第三方能力，至少覆盖阿里云短信、微信支付、快递100、高德地图、百度天气这几类外部服务，文件存储还要在本地、阿里云、腾讯云之间做可切换的适配。

这篇文章不聊产品功能，只聊落地时绕不开的几件事：外部调用怎么收口、密钥怎么管、跨系统的数据怎么交换、需要周期刷新的状态怎么用定时任务同步。下面以 Java 版（Jdk 1.8 + SpringBoot 2.5.4 + MybatisPlus 3.5.1 + SaToken 1.30.0 + Hutool 5.7.22）的技术栈为例展开。

一、所有外部调用都应该有统一出口

对接外部服务最容易踩的坑，是各个业务模块各写一套 HttpClient，密钥散落在代码里，哪天要换 AppSecret 得全量搜代码。我们的做法是把所有第三方调用收口到一个 API 网关层，网关只做三件事：鉴权放行、统一注入租户上下文、统一封装外部请求。

业务接口先经过 SaToken 1.30.0 的拦截器完成登录态校验，再进入网关路由。网关在转发前把village_id等上下文塞进请求头，下游服务拿不到合法 token 直接 401，避免外部接口被越权调用。

阿里云短信在系统里主要用于用户注册和身份验证，这是明文写在功能清单里的场景。把 accessKey/secret/endpoint 收口到配置中心（sys_config 表），既能按环境切测试/生产，也方便安全审计时一次性盘点所有外网出口。

二、数据交换：把第三方当作一种数据源

政务侧经常要上数据大屏，比如把各村的公开信息、积分排名、物流签收率聚合到一个可视化页面。万村乐的可视化大数据平台（Vue 3.0 / Vite 3.0 / ECharts 5.0）支持的数据源类型里，明确包含 MySQL、达梦、MongoDB、PostgreSQL、Oracle 这些库，以及 API 数据源。

对一个外部接口返回 JSON 的场景，我们不做实时直连，而是在数据交换层包一层适配器，把第三方响应规整成本地表结构，再做同步落库：

快递100 的物流查询就走这条链路：村民在端内查物流，网关带village_id请求快递100，返回的轨迹先落exchange_express_track，前端再从本表读，既能抗压也能回溯历史轨迹。这样做还有个附带好处——第三方接口抖动时页面不会直接报错，而是展示最近一次成功同步的结果。

三、定时同步：状态类数据靠调度补齐

不是所有外部数据都适合请求时实时拉。物流轨迹、积分变动汇总、通知公告的阅读回执聚合，这些更适合用定时任务周期同步。万村乐后端跑在 SpringBoot 2.5.4 上，周期任务用@Scheduled就够了，重一些的批处理可上 XXL-JOB 这类调度框架。

下面这段是快递轨迹增量同步的示意，每 5 分钟扫一遍 24 小时内状态未终态的运单：

通知公告的阅读情况也类似。功能清单里通知公告支持精准推送给特定标签人群并查看阅读情况，背后就是一条定时聚合任务，把各端上报的阅读事件按 village_id 汇总成「已读/未读」统计，供村干部分批催办。

积分这一侧，会员签到、任务中心、完善信息、发帖回帖、购物都能产生积分，积分变动记录是实时写表的，但家庭积分（以户为单位、由村干部手动增减）和积分排行，则靠定时任务做滚动汇总，避免每次打开页面都跑全量聚合。

四、密钥与存储的可切换适配

文件存储是另一个典型的外部依赖。系统的存储策略支持本地、阿里云、腾讯云三种方式，切换不该改业务代码，而是走策略模式 + 配置开关：

type字段决定运行时注入哪个StorageClient实现，业务侧只依赖StorageClient.upload()抽象接口。这种写法在信创场景也用得上——当底层数据库从 MySQL 8.0.28 切到达梦时，MybatisPlus 的tenant-line拦截器和分页插件基本不用动，主要改的是方言和个别不兼容的 SQL 函数。

五、容错：重试、降级与限流

第三方接口不可控，网关层必须兜底。我们的硬性约定有三条：

– 所有外部调用强制设超时（Hutool 的HttpRequest默认不设超时，必须显式timeout(3000)）； – 读接口失败走本地缓存/最近一次成功结果降级，写接口失败进重试队列； – 按第三方维度做令牌桶限流，避免某个村庄集中发短信把阿里云配额打满。

Druid 1.2.8 负责数据库连接池的体检和慢 SQL 拦截，SaToken 1.30.0 负责把越权请求在网关层挡掉，MybatisPlus 3.5.1 的TenantLineInnerInterceptor保证每个查询自动拼上village_id。这几层叠起来，外部对接才能真正做到「可观测、可隔离、可回退」。

五之一、支付回调与地图标点的两个具体细节

微信支付（Java 版主用微信支付，PHP 版额外支持支付宝）的对接里，最容易被忽略的是异步回调的落库幂等。同一个支付通知微信可能重复推，网关必须先用out_trade_no查一遍订单状态，已处理过就直接回SUCCESS，否则会出现重复发货。回调接口本身要绕开 SaToken 登录校验（支付服务器没有用户 token），做法是在网关的白名单里把它单独放行，同时用微信下发的签名做二次验签，两边都要过。

地图标点是另一个高频场景。Java 版用的是高德地图接口，村民在端内一键定位村庄位置并导航，后端只持久化经纬度与村庄的映射，渲染交给前端的地图 SDK。这里有个工程上的小坑：高德坐标系是 GCJ-02，如果数据来源是 GPS 原始坐标（WGS-84），直接落库再渲染会整体偏移几百米，必须做坐标系转换后再入库，否则导航起点会偏到隔壁村。

小结

政务与第三方系统对接，难点不在调通某一个接口，而在把散落的外部依赖收口成「网关编排 + 数据交换 + 定时同步」三件套。万村乐在这块用到的真实外部能力不多但都很实：阿里云短信管验证、微信支付管交易、快递100管物流、高德地图管标点导航、本地/阿里云/腾讯云管存储。把这些能力用统一网关收口、用定时任务补齐状态、用行级租户隔离做数据边界，一套县域平台就能在多个村庄之间安全复用，而不是每接一个县就重写一遍对接代码。