微服务架构落地：接口服务架构设计（一）—— 统一收口，内外接口的边界与整体架构

上一篇，我们拆解了日志服务，搭建起分布式系统的日志采集、检索与告警底座。 从今天开始，我们用连续 3 篇文章，完整拆解的接口服务。 接口服务内容多、模块复杂，一次性讲完内容太重，拆成分篇，由宏观到细节，逐步落地。

在大宗商品销采运储业务中，系统从来不是孤立运行： 对外，需要对接物流平台、第三方仓储、行情接口、上下游客户 ERP； 对内，各个业务微服务之间也存在大量跨服务调用。

很多团队的通病：直接在采购、仓储、销售业务服务中硬编码三方对接逻辑，上线后各种问题集中爆发：

• 每个业务服务重复开发对接逻辑，签名、异常处理、重试代码遍地复制

• 密钥、AppSecret 散落各个业务服务，存在严重安全隐患

• 三方接口一旦变更，所有业务模块都要修改代码，改动面极大

• 调用日志分散，出现对接故障，无法快速定位是我方、还是第三方平台问题

• 没有熔断保护，外部接口抖动、超时，直接拖垮内部核心业务

接口服务，就是把所有内外部接口调用能力统一收口的基础底座。

一、接口服务在六层架构中的定位

回顾整套大宗商品销采运储六层架构：

1. 展示层（Web / APP / 其他客户端）

2. 统一网关层（鉴权、路由、限流）

3. 业务服务层（采购、销售、仓储、运输、财务）

4. 基础服务层：用户服务、日志服务、接口服务、调度服务、报表服务

5. 公共中间件层：注册中心 / 配置中心，消息队列，Redis，监控，链路追踪

6. 数据层：数据库集群，文件存储

接口服务归属【基础服务层】，定位是统一接口代理、三方对接网关。 ✅ 负责：接口路由、协议适配、调用治理、报文转换、调用日志、安全签名、熔断重试 ❌ 不负责：业务逻辑（采购下单、库存扣减这类业务代码，绝对不放到接口服务）

核心设计原则：接口服务只处理通信与治理，不侵入业务。

二、整体宏观架构与调用链路

完整调用链路：业务服务 → 接口服务（统一入口） → 接口治理模块 → 协议适配层 → 内部微服务 / 外部第三方API

顶层模块划分

1. 路由配置模块

   统一管理所有接口元数据，区分内部接口、外部三方接口；接口地址、请求方式、超时时间全部配置化，无需修改代码即可切换环境、切换服务商。 例如更换物流服务商，只需要在后台修改接口配置，采购、仓储业务代码完全不用改动。

2. 接口治理核心模块

   接口服务最核心能力，包含：密钥托管、签名验签、重试、熔断降级、限流、黑白名单。 这部分内容较多，我们放在第二篇详细拆解。

3. 协议与报文适配层

   兼容多种通信协议，做报文转换、字段映射、版本兼容。 大宗商品行业大量老旧仓储、物流系统使用 WebService 等老式协议，这一层屏蔽底层协议差异。第三篇重点讲解。

4. 日志与链路上报模块

   深度对接上一篇的日志服务。每一次接口调用，自动记录入参、出参、耗时、错误码、TraceID，自动完成敏感字段脱敏。 所有内外调用全链路留痕，满足故障排查与审计要求。

5. 异步任务编排模块

   同步调用、异步任务双支持。大批量拉取运单、批量同步库存这类慢接口，转为异步任务，对接调度服务。

三、两大核心业务场景

场景 1：对外第三方平台对接（最常用）

业务服务需要推送出库单到第三方仓库、拉取物流轨迹： 业务服务发起请求 → 接口服务读取配置、加载密钥 → 执行签名、发起调用 → 接收返回报文，做格式转换、记录调用日志 → 返回结果给业务服务。 遇到接口报错，自动重试；错误率持续走高，自动熔断保护内部业务。

场景 2：对内接口聚合转发

对内可做接口聚合门面，把多个内部服务接口合并成一次返回，减少前端或者业务服务多次请求。

注意：接口聚合只做数据组装，不做复杂业务计算，守住服务边界。

四、接口服务设计目标

1. 解耦

   ：业务服务和外部第三方解耦，第三方系统变更，业务层无感知

2. 能力复用

   ：签名、熔断、重试、日志等通用能力统一实现，全业务复用，避免重复开发

3. 安全可控

   ：密钥统一托管，集中管控，减少泄露风险

4. 可观测

   ：所有接口调用统一日志、监控、告警，问题快速定位

5. 可扩展

   ：新增第三方对接，低成本接入，不用重构核心框架

五、本期小结

本篇我们先搭建接口服务的整体框架，明确它的定位、边界、宏观架构与两大业务场景。 接口服务的核心价值，就是把接口通信、调用治理这类通用底层能力，从业务代码中剥离出来，收敛到基础服务层。 业务开发人员可以专注大宗商品销、采、运、储的业务逻辑，不用反复处理对接三方平台的底层脏活。

下篇预告：接口服务架构设计（二）—— 核心能力落地：签名鉴权、重试熔断、限流降级的治理实战