commflow
  • 简体中文

      • 配置指南

      规划 API： 本页说明 runtime 发布后的 client、target、单次调用和 adapter 配置。commflow@0.0.2 没有运行时配置面；当前可运行导出见 当前版本快速开始。

      如何使用本页

      创建 client 前先确认默认 timeout、retry/reconnect 和服务定位方式；需要单次差异时再使用调用级覆盖。context、metadata 与 hook 应集中配置，避免业务代码重复拼装。

      配置分层

      层级作用示例
      client 默认配置给同一个 client 下所有调用或连接设置默认行为baseURL、timeout、retry、reconnect
      target 配置给多个后端服务设置命名入口targets: [{ name, baseURL }]
      单次调用配置只覆盖本次调用request.get('/path', { timeout: 1000 })
      adapter 配置框架接入层配置，不进入 core 强绑定VextJS propagateRequestId

      推荐原则：把稳定值放在 client 或 target 层，把临时差异放在单次调用层。

      核心配置项

      配置适用能力目标含义选择建议
      baseURLrequest / SSE默认服务地址同一个 client 只访问一个服务时使用。
      headersrequest / RPC默认请求头放通用 headers，不要放每次都变化的字段。
      timeoutrequest / RPC单次调用最长等待时间用户可从 3000-10000ms 起步，再按服务 SLA 调整。
      retryrequest / RPC失败后的额外尝试次数v1 使用数字；对幂等请求可启用，非幂等写入默认谨慎。
      retryDelayrequest / RPCretry 间隔可用毫秒数或 (attempt) => ms。
      reconnectSSE / socket长连接断开后的重连策略不等同于 request retry，需要处理关闭和重新订阅。
      targetsrequest / RPC多后端服务命名入口多个内部服务共用一个 client 时使用。
      resolverRPCprocedure 到 endpoint 的解析服务发现、静态地址或负载均衡都在这里收口。
      contextProviderrequest / adapter注入 requestId、tenant、trace metadata放宿主框架上下文，不要在业务代码里重复拼。
      metadataRPC / SSE / socket透传调用或连接上下文不要放业务 body；用于 requestId、trace、tenant。
      hooksrequest / RPC观察或轻量调整生命周期用于日志、trace、headers 注入，不建议承载业务分支。
      heartbeatIntervalsocket长连接心跳间隔根据服务端心跳要求设置。

      Target 配置

      多后端服务场景应优先用 target，而不是在业务代码里手写多个 base URL。

      const request = createCommflowRequestClient({
  targets: [
    {
      name: 'user',
      baseURL: 'https://user.internal',
      timeout: 3000
    },
    {
      name: 'billing',
      baseURL: 'https://billing.internal',
      timeout: 8000,
      retry: 2
    }
  ]
});

await request.target('user').get('/profiles/42');
await request.target('billing').get('/invoices/latest');

      覆盖规则：

      来源优先级
      单次调用配置最高，只影响本次调用
      target 配置中等，只影响该 target
      client 默认配置最低，作为兜底

      Hook 配置

      Hook 的目标是观察通信生命周期，而不是把业务逻辑藏进通信层。

      const request = createCommflowRequestClient({
  hooks: {
    beforeRequest(event) {
      event.headers.set('x-request-source', 'commflow');
    },
    afterResponse(event) {
      console.log(event.request.method, event.response.status, event.durationMs);
    },
    onRetry(event) {
      console.warn('retrying request', event.attempt, event.reason);
    },
    onError(event) {
      console.error('request failed', event.error);
    }
  }
});

      Hook 边界：

      Hook是否可修改请求失败影响
      beforeRequest可以修改 headers抛错会阻断请求。
      afterResponse不修改响应记录 secondary hook failure，不把成功响应升级为失败。
      onRetry不修改 retry 决策记录 secondary hook failure，不取消既定 retry。
      onError不覆盖原始错误记录 secondary hook failure。

      VextJS 配置边界

      VextJS 是首个重点消费者，但 core 包不应强绑定 VextJS。框架相关配置应留在 adapter 层。

      配置所属层说明
      timeout / retry / retryDelaycommflow corerequest / RPC 可共享。
      requestIdHeadercommflow core 或 adapter 共享可由 adapter 提供默认值。
      propagateRequestIdVextJS adapter是否从 Vext request context 透传 requestId。
      proxy / fetch hook 兼容VextJS adapter用于替换 app.fetch 时保持行为稳定。

      当前版本说明

      commflow@0.0.2 没有运行时配置面。安装当前包不需要环境变量、proxy 设置、retry policy 或 VextJS integration options。

      如果你只想验证当前发布包，请阅读 当前版本快速开始。如果你要理解配置如何影响错误和重试，请继续阅读 错误与重试。