commflow
  • 简体中文

      • commflow 产品功能手册（规划 API）

      规划 API： 本手册描述 commflow 最终面向用户的完整功能契约。request、SSE、RPC、socket 和 VextJS adapter 尚未由 commflow@0.0.2 发布，不能作为当前生产导入。

      当前可运行： 安装验证和已发布导出请先看 当前版本快速开始。

      commflow 能帮你完成什么

      commflow 解决服务端通信能力分散的问题。你不需要在不同框架、不同模块里重复维护 request timeout、RPC 调用超时、SSE 重连、socket 心跳、trace、上下文透传、错误归一和资源释放策略，而是通过一套统一通信层管理这些能力。

      本页建立统一使用模型，具体操作由左侧导航中的功能章节承载：

      功能面用户要完成的事
      request发起普通 HTTP 请求，管理 timeout、数字 retry、headers、target 和上下文。
      SSE订阅服务端事件流，处理 Last-Event-ID、重连、消息解析、错误和关闭。
      RPC以过程调用方式访问服务，管理 timeout、metadata、错误和类型契约。
      socket管理长连接双向消息、心跳、重连、发送顺序、监听释放和关闭。
      VextJS 接入对照 app.fetch 的能力，规划兼容迁移并验证 request context、proxy 与错误语义。
      配置理解全局配置、target 配置、单次调用覆盖和 adapter 配置。
      错误与重试区分 HTTP 响应、timeout、network、aborted、hook failure、retry 和 reconnect 策略。

      功能总览

      章节阅读目的
      Request学会创建 request client、发起 GET/POST、配置 target、上下文和 hook。
      SSE学会订阅事件流、处理消息、重连、关闭和资源释放。
      RPC学会调用 procedure、组织 contract、处理调用错误和 target。
      Socket学会连接、发送消息、监听事件、心跳、重连和关闭。
      配置指南学会区分 request/RPC 的 timeout 和 retry、SSE/socket 的 reconnect、headers、targets、metadata、contextProvider 与 hooks。
      错误与重试学会判断哪些错误应该重试、重连、暴露给业务或立即停止。
      接入 VextJS对照现有 app.fetch 能力并准备兼容接入。
      FAQ 与排错处理当前版本、导入、Node 版本和未发布 API 预期问题。

      安装与运行要求

      npm install commflow

      运行要求：

      项目要求
      Node.jspackage runtime 要求为 >=20.0.0。
      模块格式ESM 优先。
      框架core 包保持 framework-agnostic，不依赖 VextJS。
      当前包能力0.0.2 当前仅可执行 manifest API。

      功能选择

      你要做什么使用
      调 REST API、内部 HTTP 服务、一次性请求request
      服务端持续向客户端推事件SSE
      用过程名调用服务并共享 typed contractRPC
      长连接、聊天室、实时双向消息、房间/频道socket
      替换 VextJS 现有 fetch 编排能力VextJS adapter + request core

      统一使用模型

      四类通信方式共享“上下文、目标、错误、观测”的心智，但不会强行使用同一批字段。request/RPC 是一次调用，SSE/socket 是连接生命周期；SSE/socket 的恢复叫 reconnect，不能当作 request retry 处理。

      1. 创建 client。
      2. 选择服务地址、target、resolver 或 socket URL。
      3. 注入上下文、headers、metadata 或 auth。
      4. 发起调用或建立连接。
      5. 处理响应、事件、错误和关闭。

      下面的功能章节是规划 API 的使用说明。要运行当前包，请使用 当前版本快速开始 中的 manifest 示例；未来 runtime 发布后再使用各章节中的 client 示例。

      同一套配置文档会标清每项能力适用于哪些通信方式；不适用的地方会写明 N/A 理由，避免 SSE/socket 被迫承载 request 专属字段。

      规划功能章节

      功能用户手册章节核心问题
      requestRequest如何发请求、组织 target、覆盖单次调用、注入上下文和 hook。
      SSESSE如何订阅事件、解析消息、重连、关闭和避免订阅泄漏。
      RPCRPC如何按 procedure 调服务、传参数、处理返回和错误。
      socketSocket如何建立连接、收发消息、监听事件、心跳、重连和关闭。

      配置与错误处理

      配置不是开发者内部细节，而是用户使用 commflow 的核心能力。请阅读：

      • 配置指南：字段含义、默认层级、target/resolver 覆盖、hook 边界、VextJS adapter 边界。
      • 错误与重试：HTTP 状态、timeout、network、aborted、config、hook failure、retry/reconnect 策略。

      VextJS 接入

      VextJS 是 commflow 的首个重点消费者。接入时重点核对原有 app.fetch 的 timeout、retry、proxy、request context 和 hook 语义能否完整保留。详细步骤与前置条件见 接入 VextJS。

      当前版本边界

      当前 commflow@0.0.2 仍是骨架包：

      能力当前状态用户应该看
      manifest已发布Manifest API
      request runtime未发布Request
      SSE runtime未发布SSE
      RPC runtime未发布RPC
      socket runtime未发布Socket
      VextJS adapter未发布接入 VextJS

      需要立即运行代码时，从 当前版本快速开始 进入；需要理解完整产品用法时，继续使用本手册左侧的功能章节。