数字乡村平台从来不是一座孤岛。政务通知要下发到村民、农产品订单要在线支付、寄出去的包裹要能查物流、村庄位置要能在地图上标点导航。万村乐这套系统在生产环境里实际要对接的第三方能力至少覆盖阿里云短信、微信支付、快递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管物流、高德地图管标点导航、本地/阿里云/腾讯云管存储。把这些能力用统一网关收口、用定时任务补齐状态、用行级租户隔离做数据边界一套县域平台就能在多个村庄之间安全复用而不是每接一个县就重写一遍对接代码。
