@composy/http-vue

@composy/http-vue

@composy/http-vue 是 @composy/http-core 的 Vue 3 适配层，提供统一的：

• 原生 Vue Plugin 安装入口
• @composy/engine-core 插件安装入口
• provide/inject HTTP 上下文
• composables、组件和指令

安装

pnpm add @composy/http-vue

peer 依赖:vue >= 3.5 与 @composy/http-core(安装本包时会自动带入 http-core)。除根入口外,还提供 ./plugin、./composables/*、./components/*、./directives/*、./types 等子路径入口。

原生 Vue Plugin

import { createHttpPlugin } from '@composy/http-vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.use(
  createHttpPlugin({
    baseURL: 'https://api.example.com',
    timeout: 10000,
    enableCache: true,
    retry: { retries: 3 },
  })
)

也支持直接使用插件对象：

import { HttpPlugin } from '@composy/http-vue'

app.use(HttpPlugin, {
  baseURL: 'https://api.example.com',
})

Engine Plugin

import { createHttpEnginePlugin } from '@composy/http-vue'

const httpPlugin = createHttpEnginePlugin({
  baseURL: 'https://api.example.com',
  apiName: 'http',
  containerKey: 'httpClient',
})
console.info(httpPlugin)

该插件会在 Vue App 创建后自动补齐：

• HTTP client 的 provide/inject
• $http 全局属性
• engine api.register(...)
• engine container singleton(...)

常用导出

export {
  createHttpEnginePlugin,
  createHttpPlugin,
  HttpLoader,
  HttpProvider,
  useHttp,
  useHttpClient,
  useMutation,
  useQuery,
  vHttp,
} from '@composy/http-vue'

设计说明

• packages/core 保持框架无关，engine 接入能力只放在 packages/vue
• HttpLoader 的默认加载、错误和空态直接复用 core 的 <ldesign-http-state>，Vue 仅管理请求生命周期、插槽与事件
• 插件安装、HttpProvider、指令和 composables 共享同一套上下文解析路径
• useRequest、useQuery、usePolling、useSSE、useWebSocket 等资源型 composable 均使用 onScopeDispose 清理请求、定时器与连接资源，可在 effectScope 中安全使用；useQuery 在同一 Vue App 内隔离并复用查询缓存与浏览器生命周期 lease，不同 App 即使复用同一 client 也不会串扰
• usePolling 的 pauseWhenOffline 可通过 networkPort 接入 Core 或 device-core 的共享网络生命周期，避免每个轮询实例重复注册 online/offline 监听器：

usePolling(
  { url: '/api/job/status' },
  {
    interval: 5000,
    pauseWhenOffline: true,
    networkPort,
  }
)

usePolling 的 pauseWhenHidden 以及 useQuery 的 focus/reconnect 刷新也可以共用 @composy/http-core 的 BrowserLifecyclePort。传入 Device 的生命周期适配器后，HTTP 功能不会再次拥有在线/可见性原生监听器；如果需要 focus 刷新，端口还需提供可选的 subscribeFocus：

import type { BrowserLifecyclePort } from '@composy/http-core'

const browserLifecycle: BrowserLifecyclePort = lifecycle

usePolling(
  { url: '/api/job/status' },
  {
    interval: 5000,
    pauseWhenHidden: true,
    pauseWhenOffline: true,
    browserLifecycle,
  }
)

useQuery(
  client,
  'profile',
  { url: '/api/profile' },
  {
    browserLifecycle,
    refetchOnWindowFocus: true,
    refetchOnReconnect: true,
  }
)

• useRequestQueue、useUploadQueue、useDownloadManager、 useDebouncedRequest 和 useThrottledRequest 也会在 scope 销毁时清理调度/重试定时器；队列活动请求使用各自的 AbortSignal，防抖或节流中被替换、销毁的尾部 Promise 会以 AbortError 结束，不会永久 pending
• 库构建统一走 @composy/builder，不再保留平行的 vite 库模式入口

License

MIT

生命周期与请求竞态

useRequest、useQuery 和 useAsyncRequest 会忽略已被新请求替代的旧结果；取消会立即收敛 loading 状态。useAsyncRequest 的请求函数接收 { signal }，应将该信号传给 fetch 或其他可取消的异步操作：

const request = useAsyncRequest(client, ({ signal }) =>
  fetch('/api/users', { signal })
    .then(response => response.json())
    .then(data => ({
      data,
      status: 200,
      statusText: 'OK',
      headers: {},
      config: { url: '/api/users' },
    }))
)
await request.execute()

同一个 Vue App 只能安装一个 HTTP client。引擎插件卸载时会同时解除 App 注入、全局属性、事件监听、API 注册和容器单例。

工程配置

工程配置位于 .ldesign/：builder.config.ts 使用 @composy/builder / rolldown， tsconfig.json 与 eslint.config.js 分别维护 TypeScript 和 ESLint 规则；包根旧路径只保留兼容 shim。