API 客户端

wow-apiclient 为 Wow 通用命令入口与快照查询路由提供手工维护的 CoApi 接口。它是传输适配器：

CommandRequest / Query DTO
  -> CoApi HTTP exchange
  -> 生成的 WebFlux 路由
  -> 命令管线或受护栏约束的查询管线

它不会生成服务端路由、发现聚合专用字段、创建授权请求头，也不会把投影变成服务端 QueryGateway。运行服务的 OpenAPI 文档仍是路径和线协议的事实来源。

命令客户端的注册、CommandRequest、目标服务解析、响应式/同步调用、等待能力与错误映射统一见命令 API Client。本页保留扩展安装与快照查询合同。

特性

• 使用 Mono、Flux 的响应式命令与查询 API。
• 为明确采用同步 I/O 的调用方提供阻塞式同步 API。
• 通过 /wow/command/send 发送通用命令并携带等待计划请求头。
• typed、仅状态和 dynamic 三种快照查询响应形状。
• single、list、paged、精确 count，以及显式选择的 aggregation 调用。
• 支持 CoApi load-balanced 命令网关。

wow-apiclient 不是 OpenAPI 代码生成器。Fetcher 或其他下游工具可以从 /v3/api-docs 生成另一套客户端；生成 diff 必须单独审阅。

安装

添加 Wow client 与 CoApi Spring Boot Starter：

implementation("me.ahoo.wow:wow-apiclient")
implementation("me.ahoo.coapi:coapi-spring-boot-starter")

注册需要由 CoApi 物化的准确接口：

@EnableCoApi(
    clients = [
        CartQueryClient::class,
    ],
)
@SpringBootApplication
class ClientApplication

快速开始

1. 声明查询客户端

把查询接口绑定到聚合路由基址。以下示例指向无作用域的 /cart/... 路由：

@CoApi(baseUrl = "http://order-service:8080")
@HttpExchange("cart")
interface CartQueryClient : ReactiveSnapshotQueryApi<CartData>

ReactiveSnapshotQueryApi<S> 组合 single、list、paged、count 接口。其继承的 @PostExchange 路径都相对 @HttpExchange：snapshot/single、snapshot/list、snapshot/paged、snapshot/count，以及仅状态变体。

当 CoApi 或应用约定需要具体泛型元数据时，应像仓库示例客户端一样，以具体返回类型和 @RequestBody 重新声明方法。不要在每个方法重复路由路径。

@HttpExchange("cart") 调用基础无作用域快照查询变体。调用 tenant/owner 作用域变体时，应通过应用自有接口或路由层绑定生成路径并提供所需值。基础路由必须被显式保护；选择作用域客户端路径并不等于授权。不要猜测带 context 前缀的 URL，应检查服务端 OpenAPI。

2. 声明命令客户端

命令客户端的注册与调用统一见命令 API Client。

3. 注入并使用

@Service
class CartApplicationService(
    private val carts: CartQueryClient,
) {
    fun getCart(id: String): Mono<CartData> = carts.getStateById(id)
}

getStateById 会把 HTTP 404 转换为空 Mono，其他查询错误继续传播。

服务发现

查询客户端不同：目标由 @CoApi(baseUrl) 与 @HttpExchange 基址决定。服务发现和路由作用域属于应用配置，不会从 Query DTO 推导。命令目标解析属于命令 API Client。

快照查询

快照数据查询、state-only/dynamic 结果、404 语义及独立聚合 API 见查询 API 客户端。

错误处理

查询客户端只会把 single 查询的 404 规范化为空/null；校验、授权、限流、超时与后端错误仍作为传输错误交给应用处理。查询也只应重试被应用策略认定为瞬态的错误；查询 Schema 校验或 HTTP 护栏拒绝不会因重复请求而变为合法。命令错误映射与重试边界见命令 API Client和失败与幂等。