配置参考

CoApi 的配置系统旨在提供最大的灵活性，同时保持合理的默认值和清晰的优先级规则。配置采用分层方法，允许全局设置和特定于客户端的覆盖，使开发人员能够跨整个 API 客户端生态系统或针对各个服务自定义行为。

概述

CoApi 的配置架构在声明式便利性和程序化控制之间取得平衡。通过支持注解驱动和基于属性的配置，它适应不同的开发风格和部署场景。系统优先考虑显式属性声明，同时为向后兼容性和快速原型设计提供注解回退。

配置属性

全局属性

属性	类型	默认	描述	来源
coapi.enabled	Boolean	true	启用/禁用 CoApi 功能	CoApiProperties.kt
coapi.mode	ClientMode	AUTO	全局客户端模式（AUTO、REACTIVE、SYNC）	CoApiProperties.kt
coapi.base-packages	List<String>	[]	客户端发现的基础包	CoApiProperties.kt

客户端属性

属性	类型	默认	描述	来源
coapi.clients.<name>.base-url	String	""	客户端的基础 URL，覆盖注解。lb:// URL 会被改写为 http:// 并启用负载均衡（自 v2.3.0 起）	CoApiDefinition.kt:156
coapi.clients.<name>.load-balanced	Boolean?	null	覆盖负载均衡（true 启用 / false 禁用；未设置时跟随 base-url，再回退注解）	CoApiDefinition.kt:156

INFO

配置键 coapi.clients.<name>.* 中的 <name> 是 @CoApi 的 name 属性——未设置时为接口的简单类名。在注解上设置自定义 name 会改变配置键。

自 v2.2.0 起，@CoApi baseUrl/serviceId 中的 ${...} 占位符必须在当前环境中可解析：无法解析的占位符（且无 ${name:default} 兜底）会在启动期抛出 Could not resolve placeholder ...，而不是把字面量 ${...} 泄入客户端 baseUrl 并在运行期破坏请求。同名客户端冲突同样会在启动期报错并列出冲突类型。

响应式客户端属性

属性	类型	默认	描述	来源
coapi.clients.<name>.reactive.filter.names	List<String>	[]	ExchangeFilterFunction Bean 名称	CoApiProperties.kt:64
coapi.clients.<name>.reactive.filter.types	List<String>	[]	ExchangeFilterFunction Bean 类型（全限定类名）	CoApiProperties.kt:64

同步客户端属性

属性	类型	默认	描述	来源
coapi.clients.<name>.sync.interceptor.names	List<String>	[]	ClientHttpRequestInterceptor Bean 名称	CoApiProperties.kt:68
coapi.clients.<name>.sync.interceptor.types	List<String>	[]	ClientHttpRequestInterceptor Bean 类型（全限定类名）	CoApiProperties.kt:68

配置解析流程

配置系统遵循严格的优先级顺序以确保可预测的行为：

flowchart TD
    A[Start Configuration Resolution] --> B{"coapi.clients.<name>.base-url set?"}
    B -->|Yes| C["Use properties baseUrl (lb:// rewritten to http://)"]
    B -->|No| D{"@CoApi baseUrl / serviceId set?"}
    D -->|Yes| E["Use annotation baseUrl (lb:// rewritten to http://)"]
    D -->|No| F[Empty baseUrl - client uses absolute URIs per request]

    A --> G{"coapi.clients.<name>.load-balanced set?"}
    G -->|Yes| H[Use configured value]
    G -->|No| I{"coapi.clients.<name>.base-url set?"}
    I -->|Yes| J["Load balanced only if it is an lb:// URL"]
    I -->|No| K["Annotation: @LoadBalanced, lb://, or serviceId"]

    C --> L[Effective CoApiDefinition]
    E --> L
    F --> L
    H --> L
    J --> L
    K --> L

属性层次结构

配置层次结构决定了不同配置源的合并和优先级：

graph TD
    subgraph "Global Level"
        A[coapi.enabled]
        B[coapi.mode]
        C[coapi.base-packages]
    end

    subgraph "Client Level"
        D[coapi.clients.<name>.base-url]
        E[coapi.clients.<name>.load-balanced]
    end

    subgraph "Client Sub-Level"
        F[coapi.clients.<name>.reactive.filter.*]
        G[coapi.clients.<name>.sync.interceptor.*]
    end

    subgraph "Annotation Level"
        H["@CoApi(baseUrl)"]
        I["@LoadBalanced"]
    end

    A --> D
    B --> D
    C --> D
    D --> F
    D --> G
    E --> F
    E --> G
    H --> D
    I --> E

客户端配置示例

一个完整的客户端配置示例，显示所有可用选项：

graph TB
    subgraph "Application.yml"
        A["coapi:"]
    end

    subgraph "Global Settings"
        B["enabled: true"]
        C["mode: AUTO"]
        D["base-packages:"]
        E[ - com.example.clients]
    end

    subgraph "Client Definitions"
        F["clients:"]
        G["GitHubApiClient:"]
        H["base-url: https://api.github.com"]
        I["ServiceApiClient:"]
        J["load-balanced: true"]
        K["reactive:"]
        L["filter:"]
        M["names:"]
        N[ - loadBalancerExchangeFilterFunction]
        O["types:"]
        P[" - org.springframework.cloud.client.loadbalancer.reactive.LoadBalancedExchangeFilterFunction"]
        Q["sync:"]
        R["interceptor:"]
        S["names:"]
        T[ - loadBalancerInterceptor]
    end

    A --> B
    A --> C
    A --> D
    D --> E
    A --> F
    F --> G
    G --> H
    F --> I
    I --> J
    I --> K
    K --> L
    L --> M
    M --> N
    L --> O
    O --> P
    I --> Q
    Q --> R
    R --> S
    S --> T

配置解析序列

解析过程遵循明确定义的序列以确保可预测的行为：

sequenceDiagram
    participant P as Properties File
    participant A as Annotations
    participant F as FactoryBean
    participant C as Client Instance

    autonumber

    F->>P: Check coapi.clients.<name>.base-url
    alt Has property
        P-->>F: Return baseUrl from properties
    else No property
        F->>A: Check @CoApi annotation
        alt Has annotation
            A-->>F: Return baseUrl from annotation
        else No annotation
            F-->>F: Use empty baseUrl (client must use absolute URIs per request)
        end
    end

    F->>P: Check coapi.clients.<name>.load-balanced
    alt Has property
        P-->>F: Return loadBalanced from properties
    else No property
        F->>A: Check @LoadBalanced annotation
        alt Has annotation
            A-->>F: Return loadBalanced from annotation
        else No annotation
            F-->>F: Use default behavior
        end
    end

    F->>F: Build ClientDefinition
    F-->>C: Return configured client

YAML 配置示例

coapi:
  enabled: true
  mode: AUTO  # AUTO, REACTIVE, SYNC
  base-packages:
    - com.example.clients
  clients:
    GitHubApiClient:
      base-url: https://api.github.com
    ServiceApiClient:
      load-balanced: true
      reactive:
        filter:
          names:
            - loadBalancerExchangeFilterFunction
          types:
            - org.springframework.cloud.client.loadbalancer.reactive.LoadBalancedExchangeFilterFunction
      sync:
        interceptor:
          names:
            - loadBalancerInterceptor

交叉引用

• 客户端模式 - 不同客户端操作模式的详细信息
• 架构概述 - 深入了解注册流程

参考资料

源文件

• CoApiProperties.kt - 主配置属性类
• CoApiDefinition.kt - 配置覆盖规则（withOverrides）
• ClientProperties.kt - 客户端配置 SPI（ClientProperties、ReactiveClientProperties、SyncClientProperties）
• ClientMode.kt - 客户端模式枚举
• ConditionalOnCoApiEnabled.kt - 条件配置

相关页面

• 概述 - CoApi 基础介绍
• 配置参考 - 完整配置指南