152 lines
14 KiB
Markdown
152 lines
14 KiB
Markdown
# 同步调用依赖与失败传播治理基线
|
||
|
||
## 目的与口径
|
||
|
||
本基线覆盖当前官方 22 个 Maven 模块、15 个可执行服务之间的 OpenFeign、`RestClient`、`WebClient` 与 JDK `HttpClient` 调用。海外安全 Inbox/投影属于 Lastleg 内部子域，不再作为独立服务节点。基线用于识别同步依赖方向、在线请求深度、后台中继、超时、重试、熔断、幂等、错误映射和失败传播，不改变 Finance 或海外仓业务业务状态机。
|
||
|
||
“存在双向服务边”不等于“一次在线请求会递归调用”。每条边必须继续区分：
|
||
|
||
- `REQUEST`：用户或设备请求线程内，失败直接影响当前业务结果；
|
||
- `BACKGROUND`：Outbox、Inbox、定时器或导出 Worker 中的同步传输，业务事务已与传输解耦；
|
||
- `INFRASTRUCTURE`：审计、网关会话校验等基础设施调用；
|
||
- `EXTERNAL`：Integration 对第三方供应商的调用。
|
||
|
||
逐客户端可执行清单位于 `scripts/synchronous-dependency-baseline.mjs`，离线合同为 `scripts/synchronous-dependency-contract.test.mjs`。清单逐项冻结 44 个 Feign 与 16 个原始 HTTP 客户端的执行上下文、`READ/WRITE/READ_WRITE`、幂等类型和说明，并从同一事实源输出 REQUEST、BACKGROUND、INFRASTRUCTURE、EXTERNAL 与全图。新增客户端、目标服务、在线边、强连通分量或超时配置时，必须先更新基线并完成调用方与被调用方评审，不能仅修改测试期望以放行。
|
||
|
||
## 当前服务边
|
||
|
||
### OpenFeign
|
||
|
||
| 调用方 | 被调用方 | 客户端数 | 主要上下文 |
|
||
|---|---|---:|---|
|
||
| Auth | IAM | 2 | 登录授权、注册，`REQUEST` |
|
||
| IAM | Auth | 1 | 账号开通/管理，`REQUEST` |
|
||
| IAM | Firstleg | 1 | 客户尺寸默认规则可靠任务投递，`BACKGROUND` |
|
||
| IAM | Warehouse | 1 | 海外仓储费协作，`REQUEST` |
|
||
| IAM | Event Bridge | 1 | 安全事件中继，`BACKGROUND` |
|
||
| Order | Firstleg | 3 | 计价/统一订单查询为 `REQUEST`，入库协作为 Outbox `BACKGROUND` |
|
||
| Order | IAM / File / Warehouse | 各 1 | 资格、图片、仓库守卫，`REQUEST` |
|
||
| Firstleg | Order | 2 | 货物查询同时存在 `REQUEST/BACKGROUND`；PDA 履约分拆为 `REQUEST` |
|
||
| Firstleg | IAM / Finance / Integration / Event Bridge / Print | 各 1 | IAM、Integration、Print 为 `REQUEST`；Finance 与 Event Bridge 为 `BACKGROUND` 中继 |
|
||
| Firstleg | File | 7 | 测量、装柜、凭证、报关、拖车等，`REQUEST` |
|
||
| Firstleg | Warehouse | 4 | 主数据、供应商、库位/托盘，`REQUEST` |
|
||
| Finance | Firstleg | 2 | 费用来源/成本快照，事件消费与平台操作混合 |
|
||
| Finance | File / IAM / Warehouse | 各 1 | 凭证、客户、供应商校验，`REQUEST` |
|
||
| File | IAM | 2 | 资质登记为 `REQUEST`；导出 Provider 为 `BACKGROUND` |
|
||
| File | Order / Firstleg / Finance / Warehouse | 各 1 | 导出 Provider，`BACKGROUND` |
|
||
| File | Integration | 1 | OCR 在上传处理请求线程执行，`REQUEST` |
|
||
| Lastleg | Event Bridge | 1 | 跨区事件 Outbox 中继，`BACKGROUND` |
|
||
| Lastleg | 国内 Warehouse | 1 | 合作仓报价快照，`REQUEST` |
|
||
|
||
合计 44 个 Feign 客户端。公共默认连接/读取超时为 3 秒/5 秒；File 的五个导出 Provider 客户端读取超时单独为 15 秒。
|
||
|
||
### 原始 HTTP
|
||
|
||
| 调用方 | 被调用方 | 实现 | 上下文与当前策略 |
|
||
|---|---|---|---|
|
||
| Gateway Overseas | Auth | `HttpPdaSessionValidationClient` | `INFRASTRUCTURE`；总超时 2 秒，异常由网关失败关闭 |
|
||
| Gateway Overseas | Lastleg Security 子域 | `HttpOverseasSecurityValidationClient` | `INFRASTRUCTURE`；Lastleg 内部安全投影实时校验，异常失败关闭，不进入在线业务图 |
|
||
| Lastleg | Warehouse Overseas | 两个 `RestClient` Gateway | `REQUEST`；分别使用 3 秒连接、5 秒读取超时，配置可覆盖，不自动重试 |
|
||
| Lastleg | File | 两个照片 `RestClient` Gateway | `REQUEST`；分别使用 3 秒连接、30 秒读取超时，配置可覆盖；校验响应 code 且失败关闭，不自动重试 |
|
||
| Event Bridge | Firstleg / Lastleg（业务事件与安全投影两个入口） | 三个 JDK `HttpClient` | `BACKGROUND`；连接 3 秒、请求 10 秒，持久化租约和退避由 Event Bridge 专项治理；Lastleg Security 投影不进入在线业务图 |
|
||
| 启用 Common Audit 的服务 | Audit | `HttpAuditSink` | `INFRASTRUCTURE`；当前捕获异常后仅告警，可能让调用方误以为审计已成功，是高优先级失败传播缺口 |
|
||
| Integration | 外部 OCR/船司 | 六个 JDK `HttpClient` | `EXTERNAL`；OCR 默认 10/60 秒，船司默认 10/30 秒，业务重试必须服从供应商和调度契约 |
|
||
|
||
#### Lastleg 四个有界 RestClient
|
||
|
||
六个客户端统一从 `LastlegRestClientFactory` 构建 JDK HTTP 传输，由 `LastlegRestClientProperties` 绑定独立超时。读取超时是单次请求的硬边界；客户端没有 Retry、fallback 或默认成功配置。
|
||
|
||
| 客户端 | 构建与调用路径 | 写操作幂等性 | 默认超时 |
|
||
|---|---|---|---|
|
||
| `HttpUnloadPhotoFileGateway` | `ReceivingContainerController → ReceivingContainerService → UnloadPhotoFileGateway → /internal/file/v1/business-files/**` | `validate` GET 可重复；`upload` 每次写文件和元数据，没有幂等键，禁止自动重试 | 连接 3 秒、读取 30 秒 |
|
||
| `HttpRelabelPhotoFileGateway` | `RelabelPdaController/Service → RelabelPhotoFileGateway → /internal/file/v1/business-files/**` | `validate` GET 可重复；`upload` 没有幂等键，禁止自动重试 | 连接 3 秒、读取 30 秒 |
|
||
| `HttpCustomerVisitFileGateway` | `CustomerVisitService → CustomerVisitFileGateway → /internal/file/v1/business-files/**` | 附件上传没有幂等键，禁止自动重试；元数据读取可重复 | 连接 3 秒、读取 30 秒 |
|
||
| `HttpProcurementFileGateway` | `OverseasProcurementService → ProcurementFileGateway → /internal/file/v1/business-files/**` | 采购凭证和签收文件上传没有幂等键，禁止自动重试 | 连接 3 秒、读取 30 秒 |
|
||
| `HttpWarehouseResourceGateway` | `InboundPdaWorkflowService`、PDA 仓内查询/盘点及 Dropship → Warehouse Resource/Pallet 内部接口 | 查询可重复；`reserve` 使用 `reservationKey`，`ensureDropship` 使用业务绑定，release/scrap 由服务端状态收敛；尽管服务端具备业务幂等，客户端仍不自动重试 | 连接 3 秒、读取 5 秒 |
|
||
| `HttpPalletPhysicalGateway` | `PdaPalletOperationService`、`PdaInventoryMoveService` → `/internal/v1/pda-pallet-transitions/**` | 查询可重复；apply/compensate 使用稳定 `operationKey` 与请求哈希，服务端幂等；客户端仍不自动重试 | 连接 3 秒、读取 5 秒 |
|
||
|
||
## 分上下文依赖图
|
||
|
||
### 在线 REQUEST 图
|
||
|
||
在线图只包含用户或设备请求线程中实际执行的服务边。Event Bridge、Outbox、船节点定时任务、导出 Provider 和 Gateway→Lastleg Security 基础设施校验均不计入在线深度。
|
||
|
||
当前在线强连通分量为：
|
||
|
||
`Auth ↔ IAM`；`Firstleg ↔ Order`
|
||
|
||
`IAM → Firstleg` 默认尺寸初始化已退出请求线程，合同现冻结 21 条在线服务边；新增在线边或新增强连通分量直接失败。File 不再属于在线强连通分量；Finance、Lastleg 只指向上述分量或叶子服务，不属于在线环；Gateway Overseas→Lastleg Security 是 `INFRASTRUCTURE`，不是 REQUEST 边。
|
||
|
||
### 后台 BACKGROUND 图
|
||
|
||
后台图包含 Outbox/Inbox、导出 Worker 和定时任务，当前强连通分量为：
|
||
|
||
`Event Bridge ↔ Firstleg ↔ Finance ↔ Lastleg ↔ Order`
|
||
|
||
File 的五个导出 Provider、Order→Firstleg 入库 Outbox、该入库消费者为生成箱号而回读 Order 货物的后台回调、IAM 默认尺寸可靠任务、IAM 安全 Outbox、Firstleg/Lastleg 跨区 Outbox、Firstleg→Finance 费用 Outbox及 Event Bridge 三个消费者均只在后台图中计算。Event Bridge→Lastleg Security 与 Event Bridge→Lastleg 业务事件在服务图上收敛为同一条后台服务边，不形成新的在线业务边或独立安全节点。
|
||
|
||
### 全图
|
||
|
||
全上下文合并后，非平凡强连通分量仍为 8 个服务：
|
||
|
||
`Auth ↔ IAM ↔ Order ↔ Firstleg ↔ Finance ↔ File ↔ Event Bridge ↔ Lastleg`
|
||
|
||
全图只用于部署影响和故障域观察，不能再用于推导在线调用“无限深度”。
|
||
|
||
### 用户入口在线最长简单路径
|
||
|
||
默认在线预算为最多 2 个下游服务跳数。合同对每个已知用户入口枚举全部最长简单路径；下表列出的具体路径均超过预算：
|
||
|
||
| 用户入口 | 最长跳数 | 全部长路径 |
|
||
|---|---:|---|
|
||
| 订单 API | 4 | `Order → Firstleg → File → IAM → Auth`；`Order → Firstleg → File → IAM → Warehouse` |
|
||
| 头程 API/PDA | 4 | `Firstleg → Order → File → IAM → Auth`；`Firstleg → Order → File → IAM → Warehouse` |
|
||
| 财务 API | 5 | `Finance → Firstleg → Order → File → IAM → Auth`；`Finance → Firstleg → Order → File → IAM → Warehouse` |
|
||
| 海外尾程 API/PDA | 3 | `Lastleg → File → IAM → Auth`；`Lastleg → File → IAM → Warehouse` |
|
||
|
||
这些是静态服务边可形成的最长简单路径，不表示每个具体 Controller 都会走完整链；后续入口级调用点治理必须继续以实际 Service 调用证据缩小路径，不能用静态可能性宣称线上已经发生。
|
||
|
||
### 已完成的第一个 REQUEST 边退出
|
||
|
||
`IAM → Firstleg` 的 `CustomerDimensionRuleClient` 默认尺寸初始化已经从 REQUEST WRITE 改为可靠后台编排。IAM 与客户主档同事务持久化稳定 `initializationKey` 的任务，显式维护 `PENDING/READY/FAILED`，由租约调度重试并提供诊断查询和人工重试；审批通过与下单资格在未 READY 时失败关闭。此边现在仅属于 BACKGROUND，在线五服务强连通分量实际拆为 Auth↔IAM 与 Order↔Firstleg 两个子环，未触碰财务、Event Bridge 或海外仓业务业务状态机。
|
||
|
||
### Order↔Firstleg 第二阶段结论
|
||
|
||
具体入口、所有权与可执行退出方案见 `docs/Order-Firstleg在线依赖解环设计.md`。当前 `COMPLETE_LOADING` 在 Firstleg 本地事务中同步取得 Order 余量子单后才完成结算，且 Order 货物在 `LOADED` 前仍允许修改；成功时点和货物冻结点尚未冻结，因此本阶段不改业务代码。REQUEST SCC 仍为 `Firstleg↔Order`，合同明确阻止仅改变分类却未退出生产调用的伪解环。
|
||
|
||
## 退出顺序
|
||
|
||
1. **冻结与分层。** 先用清单合同阻止未评审新边；为每个客户端补齐 `REQUEST/BACKGROUND/INFRASTRUCTURE/EXTERNAL`、读写语义、幂等键和失败映射。这个阶段不改变业务状态。
|
||
2. **统一失败传播与时间预算。** 为 Feign 和原始 HTTP 明确连接/读取/总超时；默认禁用自动重试，只有具备幂等键且由业务明确拥有退避状态的后台操作可以重试；禁止空数据、默认成功或仅日志告警替代远端失败。
|
||
3. **先退出伪在线环。** File 导出 Provider、Firstleg/Lastleg Event Bridge、Firstleg→Finance 费用投递继续作为后台链路，但必须从在线深度图剥离，并禁止 Worker 消费时无界同步回调。
|
||
4. **退出 `Order ↔ Firstleg` 在线双向命令。** 保留一个方向的权威查询，将反向状态推进改为带版本、幂等和审计的 Outbox/Inbox；不复制 Order 交易状态或 Firstleg 履约状态。
|
||
5. **退出 `Auth ↔ IAM` 在线双向写。** Auth 保持账号与 Token 唯一所有者，IAM 保持客户/RBAC 所有者；注册和账号开通使用可恢复编排，登录授权快照失败关闭，不引入第二套账号事实。
|
||
6. **收敛 `IAM ↔ Firstleg`。** 客户维度规则和客户快照确定单一事实方向；允许短期只读查询，禁止两个服务互相修正对方数据。
|
||
7. **在财务总控确认后退出 `Firstleg ↔ Finance` 回调。** 优先让版本化事件携带 Finance 校验所需的不可变快照或使用单向快照读取，保持 Finance 状态机和 Firstleg 费用事实边界不变。
|
||
8. **收敛 File 相关环。** File 只拥有文件对象与导出任务；业务服务拥有导出数据和业务归属。凭证/照片校验失败关闭，导出 Worker 使用受限批次、超时和显式失败状态。
|
||
|
||
## 错误、重试与熔断基线
|
||
|
||
- 远端 HTTP 非 2xx、响应体 `code != "200"`、空响应和 DTO 不完整是四类不同失败，均不得变成成功或空列表。
|
||
- 在线查询/命令默认不自动重试。若启用重试，必须同时证明方法幂等、请求具有稳定幂等键、最大尝试次数和总时间预算可控。
|
||
- Outbox/Inbox 重试由持久化状态拥有，Feign/JDK 客户端不得再叠加隐式重试造成次数乘法。
|
||
- 熔断打开时返回统一“依赖不可用”错误并保留 request/trace 关联信息，不配置业务成功型 fallback。
|
||
- 404 只有在契约明确“资源不存在”时可映射为领域未找到；连接失败、超时、5xx、空响应必须映射为依赖不可用。
|
||
- Common Audit 当前“只记录告警后返回”列为已知例外，不能据此推广静默降级；其可靠性与业务阻断口径需和审计/总控共同冻结。
|
||
|
||
## 直接受影响验证
|
||
|
||
| 变更范围 | 最低验证 |
|
||
|---|---|
|
||
| 图、客户端或超时配置 | `node --test scripts/synchronous-dependency-contract.test.mjs` |
|
||
| 单个 Feign/HTTP 签名或错误映射 | `mvn -pl <调用方>,<被调用方> -am test-compile`，并运行双方直接相关测试 |
|
||
| Auth/IAM | `mvn -pl auth,iam -am test` |
|
||
| Order/Firstleg | `mvn -pl order,firstleg -am test` |
|
||
| IAM/Firstleg | `mvn -pl iam,firstleg -am test` |
|
||
| Firstleg/Finance | `mvn -pl firstleg,finance -am test`；业务口径先由财务总控确认 |
|
||
| Firstleg/File 或 File/Finance | `mvn -pl firstleg,file,finance -am test`，按实际消费者缩小模块集 |
|
||
| Lastleg 原始 HTTP | `mvn -pl lastleg-service,warehouse-overseas-service,file -am test`；不改变海外仓业务状态机 |
|
||
| 全部治理阶段收口 | `mvn -DskipTests validate` 后执行 `mvn test` |
|
||
|
||
以上均为本地离线验证；未经明确授权不启动 Java/Nacos/数据库，不执行 SQL、部署或测试环境 HTTP 验收。
|