# 05. 集成层设计（F6 / Mini 域）

## 决策

供应商（F6）和历史 Mini 域的调用统一收口在 `integration/f6-adapter` / `integration/mini-clients` 模块（模块位置见 [01-project-structure.md](./01-project-structure.md)），业务 domain 不直接持有 HTTP 客户端；用 Resilience4j 统一管理超时、重试、熔断、并发隔离。

HTTP 客户端用 **`RestClient`（同步）**，底层是 Apache HttpClient 5 连接池，不用 `WebClient`/`Mono`。

### 为什么是同步 `RestClient` 而不是 `WebClient`

`WebClient` 是 Spring 官方推荐的现代 HTTP 客户端，但它的返回值是 `Mono`/`Flux`，把响应式编程模型带进了整个调用链。在我们这套以 Spring MVC（同步 Servlet 栈）为主的应用里，这会造成几个实际问题：

- **上下文会丢**。`StoreContextHolder` 是 `@RequestScope` bean、日志的 `traceId` 在 MDC 里，这两样都绑在请求线程上。一旦回调跑在 Reactor 的 event-loop 线程上，两者都拿不到——日志断链、上下文取不到值，而且这类 bug 只在特定时序下出现，很难查。
- **收益用不上**。响应式的价值是用少量线程扛住大量并发连接，前提是**整条链路都是非阻塞的**。我们的链路里有 JPA（阻塞 JDBC），只要还在用 JPA，中间夹一段响应式并不会减少线程占用，只是把复杂度带进来。
- **心智成本**。`Mono` 一旦进入业务代码，测试、异常处理、事务边界都要按另一套规则写，团队要同时掌握两套模型。

`RestClient`（Spring 6.1+）提供的是和 `WebClient` 一样的流式 API，但返回值是普通对象、执行是同步的。等到将来整条链路真的要转非阻塞（比如换掉 JPA），再统一切换到 `WebClient` 不迟——那时是一次有明确收益的整体迁移，而不是现在这样局部引入。

## 结构约定

```
platform-integration/
  RestClientConfig               # 按下游系统构建 RestClient（连接池、超时、拦截器）
  IntegrationClientProperties      # integration.clients.* 配置绑定
  TracePropagationInterceptor       # 统一给出站请求加 X-Trace-Id
  IntegrationException               # 集成层异常基类（继承 platform-web 的 BusinessException）

integration/f6-adapter/
  负责：换票、供应商访问上下文准备、超时/重试/熔断/舱壁策略、异常转换为内部标准错误码

integration/mini-clients/
  对 O2O/Warranty/Retail Store/ROOS 的只读客户端封装，供 workbench / bff-orchestration 调用
```

`platform-integration` 依赖 `platform-web`（为了复用 `BusinessException` 和 `ErrorCode`）是本次允许的少数几个 platform 间依赖之一。

## `RestClient` 配置

```groovy
// platform-integration/build.gradle
dependencies {
    implementation project(':platform:platform-web')
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.apache.httpcomponents.client5:httpclient5'      // 版本由 Boot BOM 管
    implementation 'io.github.resilience4j:resilience4j-spring-boot4:2.4.0'
}
```

```kotlin
// platform-integration/.../RestClientConfig.kt
@Configuration
@EnableConfigurationProperties(IntegrationClientProperties::class)
class RestClientConfig(private val props: IntegrationClientProperties) {

    @Bean
    fun f6RestClient(builder: RestClient.Builder): RestClient = build(builder, props.f6) { req, resp ->
        // 5xx / 连接类问题 → 可重试；4xx → 请求本身有问题，重试没有意义
        if (resp.statusCode.is5xxServerError) {
            throw F6ServerException("F6 返回 ${resp.statusCode}")
        }
        throw F6ClientException("F6 拒绝了请求: ${resp.statusCode}")
    }

    @Bean
    fun miniRestClient(builder: RestClient.Builder): RestClient = build(builder, props.mini) { _, resp ->
        throw MiniIntegrationException("Mini 域返回 ${resp.statusCode}")
    }

    private fun build(
        builder: RestClient.Builder,          // 注入 Boot 提供的 Builder，而不是 RestClient.create()：
        config: ClientConfig,                  // 这样 Micrometer 的 observation/W3C traceparent 会自动挂上（见 08）
        statusHandler: RestClient.ResponseSpec.ErrorHandler,
    ): RestClient = builder
        .baseUrl(config.baseUrl)
        .requestFactory(requestFactory(config))
        .requestInterceptor(TracePropagationInterceptor())
        .defaultStatusHandler(HttpStatusCode::isError, statusHandler)
        .build()

    private fun requestFactory(config: ClientConfig): ClientHttpRequestFactory {
        val connectionManager = PoolingHttpClientConnectionManagerBuilder.create()
            .setMaxConnTotal(config.maxConnections)
            .setMaxConnPerRoute(config.maxConnectionsPerRoute)   // 必须 ≥ 对应的舱壁并发上限，理由见下
            .setDefaultConnectionConfig(
                ConnectionConfig.custom()
                    .setConnectTimeout(Timeout.ofMilliseconds(config.connectTimeoutMs))
                    .setValidateAfterInactivity(TimeValue.ofSeconds(5))   // 复用前探活，避开对端已断的空闲连接
                    .build(),
            )
            .build()

        val httpClient = HttpClients.custom()
            .setConnectionManager(connectionManager)
            .setDefaultRequestConfig(
                RequestConfig.custom()
                    // 从连接池拿连接的等待上限。漏配它是最隐蔽的一个坑：
                    // 池子被占满时线程会无限期地等在这里，前面所有超时配置全部失效。
                    .setConnectionRequestTimeout(Timeout.ofMilliseconds(config.connectionRequestTimeoutMs))
                    .setResponseTimeout(Timeout.ofMilliseconds(config.readTimeoutMs))
                    .build(),
            )
            .evictIdleConnections(TimeValue.ofSeconds(30))
            .build()

        return HttpComponentsClientHttpRequestFactory(httpClient)
    }
}
```

```yaml
integration:
  clients:
    f6:
      base-url: ${F6_BASE_URL}
      connect-timeout-ms: 1000
      read-timeout-ms: 2000
      connection-request-timeout-ms: 500
      max-connections: 60
      max-connections-per-route: 30
    mini:
      base-url: ${MINI_BASE_URL}
      connect-timeout-ms: 500
      read-timeout-ms: 1000
      connection-request-timeout-ms: 300
      max-connections: 60
      max-connections-per-route: 30
```

**超时由 HTTP 客户端承担，不用 `@TimeLimiter`。** Resilience4j 的 `@TimeLimiter` 只能作用于 `CompletableFuture` 或响应式返回值——同步方法上加了不会报错，但**完全不生效**，是个非常容易误配的注解。同步栈下真正管用的是上面三个：`connectTimeout`（建连）、`responseTimeout`（等响应）、`connectionRequestTimeout`（等连接池）。

## Resilience4j 配置

```yaml
resilience4j:
  # 叠加顺序由这几个 *-aspect-order 属性决定，跟注解写在方法上的先后顺序无关（详见文末附录）。
  # 这里显式写死，避免依赖框架默认值——默认值会随版本变，而顺序变了语义就变了。
  retry:
    retry-aspect-order: 3           # 最外层
    instances:
      f6-api:
        max-attempts: 2
        wait-duration: 200ms
        exponential-backoff-multiplier: 2
        retry-exceptions:
          # 同步栈下真实会抛出来的类型：
          # - ResourceAccessException 包住了 SocketTimeoutException/ConnectException 等所有 IO 异常，
          #   业务代码永远不会直接见到 SocketTimeoutException，写它是无效配置
          # - F6ServerException 是我们在 statusHandler 里对 5xx 的转换
          - org.springframework.web.client.ResourceAccessException
          - com.continental.retailapp.integration.f6.F6ServerException
        ignore-exceptions:
          # 熔断已打开时抛的异常，重试它毫无意义，只会白白多等一轮 wait-duration
          - io.github.resilience4j.circuitbreaker.CallNotPermittedException
          - com.continental.retailapp.integration.f6.F6ClientException
  circuitbreaker:
    circuit-breaker-aspect-order: 2
    instances:
      f6-api:
        sliding-window-type: COUNT_BASED
        sliding-window-size: 20
        minimum-number-of-calls: 10    # 样本太少时不做判断，避免启动后头几个请求就把熔断打开
        failure-rate-threshold: 50
        slow-call-duration-threshold: 1500ms
        slow-call-rate-threshold: 80   # 慢调用也算故障：只统计失败率的话，"每次都卡满 2 秒但最终成功"永远不会熔断
        wait-duration-in-open-state: 10s
        permitted-number-of-calls-in-half-open-state: 5
        record-exceptions:
          - org.springframework.web.client.ResourceAccessException
          - com.continental.retailapp.integration.f6.F6ServerException
  bulkhead:
    bulkhead-aspect-order: 1          # 最内层，贴着真实调用
    instances:
      f6-api:
        max-concurrent-calls: 20
        max-wait-duration: 0          # 拿不到名额立刻失败走降级，不排队 —— 排队等于把阻塞换个地方而已
      mini-o2o:
        max-concurrent-calls: 20
        max-wait-duration: 0
```

## F6 客户端示例

```kotlin
// integration/f6-adapter/.../F6ApiClient.kt
@Component
class F6ApiClient(
    private val f6RestClient: RestClient,     // 来自 platform-integration 的统一封装
) {
    @Bulkhead(name = "f6-api")                 // 默认 SEMAPHORE 类型，不额外起线程
    @CircuitBreaker(name = "f6-api", fallbackMethod = "fallbackProcurementList")
    @Retry(name = "f6-api")
    fun fetchProcurementList(storeId: Long): ProcurementListResponse =
        f6RestClient.get()
            .uri("/f6/procurement/list?storeId={storeId}", storeId)
            .retrieve()
            .body(ProcurementListResponse::class.java)!!

    // Resilience4j 约定：fallback 方法签名 = 原方法参数 + Throwable，返回类型与原方法一致（同步下就是 T）
    fun fallbackProcurementList(storeId: Long, ex: Throwable): ProcurementListResponse {
        log.warn("F6 采购列表降级返回，storeId={}, cause={}", storeId, ex.toString())
        return ProcurementListResponse.degraded()
    }
}
```

```kotlin
// platform-integration/.../IntegrationException.kt
// 继承 BusinessException（见 06-api-design.md），复用 GlobalExceptionHandler，
// 不再单独写一个 @RestControllerAdvice —— 少一个会和全局处理器抢优先级的地方。
open class IntegrationException(
    code: Int,
    message: String,
    httpStatus: HttpStatus = HttpStatus.BAD_GATEWAY,
) : BusinessException(code, message, httpStatus)

// integration/f6-adapter/.../F6Exceptions.kt
class F6ServerException(message: String) :
    IntegrationException(ErrorCode.F6_UNAVAILABLE, "供应商服务暂不可用，请稍后重试")

class F6ClientException(message: String) :
    IntegrationException(ErrorCode.F6_BUSINESS_ERROR, "供应商请求被拒绝")
```

错误码是 `Int`，落在 `3xxxx` 集成段（`ErrorCode.F6_UNAVAILABLE = 30001`），完整分段表见 [06-api-design.md](./06-api-design.md)——客户端 [../12-error-and-api-contract.md](../../conti-retail-app/docs/12-error-and-api-contract.md) 的 `ApiCode` 也是数字，两边必须一致。异常里带的原始 `message`（含 F6 的状态码和响应体）只进日志，**不进返回给 APP 的 `message`**，避免把供应商的协议细节泄漏出去。

## Mini 域客户端示例（内部系统，策略更宽松）

```kotlin
// integration/mini-clients/.../O2OClient.kt
@Component
class O2OClient(private val miniRestClient: RestClient) {

    @Bulkhead(name = "mini-o2o")     // 只做超时 + 并发隔离，不加熔断（内部系统，稳定性相对可控）
    fun fetchOrderSummary(storeId: Long): OrderSummary =
        try {
            miniRestClient.get()
                .uri("/o2o/orders/summary?storeId={storeId}", storeId)
                .retrieve()
                .body(OrderSummary::class.java)!!
        } catch (ex: Exception) {
            log.warn("O2O 订单摘要降级返回，storeId={}", storeId, ex)
            OrderSummary.empty()      // 局部降级：首页某个 tile 空着，好过整个首页 500
        }
}
```

## traceId 透传

```kotlin
// platform-integration/.../TracePropagationInterceptor.kt
class TracePropagationInterceptor : ClientHttpRequestInterceptor {
    override fun intercept(
        request: HttpRequest,
        body: ByteArray,
        execution: ClientHttpRequestExecution,
    ): ClientHttpResponse {
        MDC.get("traceId")?.let { request.headers.set("X-Trace-Id", it) }
        return execution.execute(request, body)
    }
}
```

同步栈下拦截器和业务代码跑在同一个线程上，MDC 一定取得到，业务代码零感知。W3C 标准的 `traceparent` 头由 Micrometer Tracing 自动加（前提是用注入的 `RestClient.Builder` 构建，见上面的注释）；这里额外发的 `X-Trace-Id` 是给 F6 这类只认自定义头的外部系统用的，两者并存，规则见 [08-observability.md](./08-observability.md)。

## 关键规则

- **F6 是外部供应商域**，稳定性不可控，必须配齐超时 + 重试 + 熔断 + 舱壁，且熔断后要有降级返回（`fallbackXxx` 方法），不能让异常直接穿透到 APP。
- **异常统一转换**：F6 / Mini 域的异常和非标准错误，在集成模块内部转换成内部标准错误码，业务 domain 和最终 API 响应都不暴露供应商侧的原始协议细节。
- **Mini 域调用相对可控**（内部系统），熔断可以不加，但超时和舱壁不能省，避免慢查询拖垮 `workbench` 聚合——对应架构图 Flow 3 "首页失败按 tile 降级"。
- **只对幂等调用配 `@Retry`**。GET 查询可以放心重试；有副作用的调用（下单、扣减）**默认不重试**，确实需要时接口必须带幂等 key，规则见 [12-concurrency-and-scheduling.md](./12-concurrency-and-scheduling.md)。
- **不在数据库事务里调外部 HTTP**，理由见 [03-persistence.md](./03-persistence.md)。
- 业务 domain（如 `workbench`）只依赖 `integration/*` 暴露的接口，不自己构造 `RestClient` 发请求。
- `workbench` 首页把多个下游并行拉起来的写法（线程池、整体超时预算、按 tile 降级）见 [11-cross-domain-collaboration.md](./11-cross-domain-collaboration.md)——那不属于单个客户端的职责。

## 附录一：超时、重试、熔断、舱壁分别解决什么问题

四者经常被一起提，但作用点不同，配置的时候容易搞混：

- **超时（Timeout）**：解决"对方一直不回应，我方线程/连接被一直占着"的问题。这是最基础、必须有的一道防线。同步栈下它由 HTTP 客户端提供，不是 Resilience4j 提供的。
- **重试（Retry）**：解决"这次失败大概率是偶发的（网络抖动、瞬时过载）"的问题。前提是**幂等**。
- **熔断（Circuit Breaker）**：解决"对方已经持续故障，继续请求只是在浪费资源、拖慢自己"的问题。统计滑动窗口内的失败率（和慢调用率），超阈值后直接短路走 fallback（`OPEN`），过一段时间放几个探测请求（`HALF_OPEN`）判断是否恢复。
- **舱壁（Bulkhead）**：解决"一个慢下游把我方所有工作线程吃光"的问题——**这一道在同步栈下尤其重要**。算笔账：Tomcat 默认 200 个工作线程，F6 读超时 2 秒，如果 F6 全面卡住且没有并发限制，200 个线程会在 2 秒内全部堵在 F6 上，此时这个应用连登录、连查本地数据库的接口都不可用了，一个外部依赖直接把整个服务拖死。配上 `max-concurrent-calls: 20` 之后，最多 20 个线程能进去，剩下 180 个照常干活，超出的请求立刻走降级——**用一个功能的降级换整个服务的存活**。

  响应式栈下这道防线的必要性没这么强（event-loop 天生不会被阻塞占死），这也是从 `WebClient` 换到 `RestClient` 后必须补上它的原因。

  舱壁上限和连接池要对齐：`max-connections-per-route` 必须 ≥ `max-concurrent-calls`，否则真正的瓶颈会变成"抢连接"，请求会堵在 `connectionRequestTimeout` 上，而不是被舱壁干脆利落地挡掉。

## 附录二：叠加顺序由配置决定，不是由注解顺序决定

**一个常见误解是"注解写在上面的就在外层"——不是的。** Resilience4j 的各个切面都是独立的 Spring AOP Aspect，它们的嵌套顺序由 `resilience4j.<type>.<type>-aspect-order` 属性（也就是 Spring 的 `@Order` 语义）决定，跟注解在方法上的书写顺序完全无关。框架的默认顺序是 **Retry 在最外层**：

```
Retry ( CircuitBreaker ( RateLimiter ( TimeLimiter ( Bulkhead ( 真实调用 ) ) ) ) )
```

顺序不同，语义差别很实在：

- **Retry 在外（默认，我们采用）**：每一次重试都会各自经过熔断器，所以一次失败的调用会往熔断器的统计窗口里记 2 笔（`max-attempts: 2`）。好处是下游真出问题时熔断器打开得更快；代价是窗口里的样本数会被重试放大，`sliding-window-size` 要按放大后的量来估。这也是为什么必须把 `CallNotPermittedException` 加进 `ignore-exceptions`——熔断打开后抛的就是它，不排除掉的话每次请求还要白白多等一轮重试。
- **CircuitBreaker 在外**：整组重试合起来只在熔断器上记 1 笔，统计更"干净"，但下游故障时熔断打开会慢一些。

**建议**：像上面 yaml 那样把三个 `*-aspect-order` 显式写出来，不要依赖默认值——默认值可能随版本变化，而这个顺序一变，熔断的触发速度就跟着变了，还很难从现象上察觉。另外，各版本对"order 数值大是更外层还是更内层"的约定容易记反，配完之后**用一个必定失败的集成测试实际验证一次**叠加顺序（比如断言下游被调用了几次、熔断器记录了几笔），比查文档可靠，写法见 [10-testing.md](./10-testing.md)。

## 待补充

- 具体超时/重试/舱壁参数需要结合 F6 实际 SLA 压测后调整，示例里的数值是起点，不是最终值。
- 熔断后降级返回的数据结构约定（`degraded()` 的具体字段，以及 APP 侧如何展示"这块数据是降级的"）。
- F6 换票的具体协议细节（对接 [04-security-auth.md](./04-security-auth.md) 的切店联动失效）。

## 参考链接

- [Resilience4j 官方文档](https://resilience4j.readme.io/docs)
- [Spring Framework: RestClient](https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-restclient)
- [Apache HttpClient 5 连接管理](https://hc.apache.org/httpcomponents-client-5.4.x/current/tutorial/html/connmgmt.html)
- [Martin Fowler: CircuitBreaker](https://martinfowler.com/bliki/CircuitBreaker.html)
- [Release It! 中的 Bulkhead 模式](https://learn.microsoft.com/azure/architecture/patterns/bulkhead)