@composy/api-vue

@composy/api-vue

English

@composy/api-vue 是 @composy/api-core 的 Vue 3 适配层。它保持 api-core 作为唯一运行时内核，只补齐 Vue 应用注入、组合式请求状态和插件封装。

定位

• @composy/api-core 负责服务器配置、API 注册、请求调度、事件发射与管理器生命周期。
• @composy/api-vue 只负责 Vue 侧能力：
  • provide/inject
  • composables
  • 原生 Vue Plugin
  • @composy/engine-core 的 Vue 插件桥接

这意味着 Vue 层不会重复创建第二套请求内核，也不会把 API 注册逻辑散落到各个 composable 里。

两种插件用法

1. 原生 Vue Plugin

import { createApp } from 'vue'
import App from './App.vue'
import { createApiPlugin, defineRestfulApi, defineRestfulServer } from '@composy/api-vue'

type User = { id: number; name: string }

const server = defineRestfulServer('api', 'https://api.example.com')

const getUserApi = defineRestfulApi<{ id: number }, User>('api', 'getUser', 'GET', '/users/:id')
  .pathParams('id')
  .build()

createApp(App)
  .use(
    createApiPlugin({
      servers: [server],
      apis: [getUserApi],
      defaultServerId: 'api',
      cache: true,
      deduplicate: true,
      retry: { maxRetries: 2 },
    })
  )
  .mount('#app')

2. @composy/engine-core Plugin

import { createVueEngine } from '@composy/engine-vue'
import { createApiEngineVuePlugin, defineRestfulServer } from '@composy/api-vue'

const engine = createVueEngine({
  plugins: [
    createApiEngineVuePlugin({
      servers: [defineRestfulServer('api', 'https://api.example.com')],
      defaultServerId: 'api',
    }),
  ],
})

兼容方式说明：

• createApiEngineVuePlugin() 先调用 @composy/api-core 的 createApiEnginePlugin() 管理 ApiManager 生命周期。
• 管理器级 cache、deduplicate、retry、httpClientFactory 和生命周期钩子都透传给 api-core；Vue composable 不重复实现请求执行。
• 当 engine.getApp() 已可用，或后续收到 app:created 事件时，再把同一个 ApiManager 注入到 Vue App。
• 因此 engine 路径和原生 Vue 路径共享的是同一套 manager/config/eventEmitter，不会重复初始化第二份状态。

Vue App 与异步生命周期

• 原生 Vue 插件创建的管理器由当前 App 拥有；通过 manager 传入的管理器，以及 Engine 插件创建的管理器属于借用资源，App 卸载时不会被重复销毁。
• App binding 会先调用 Vue 原始 unmount，再解除注入并恢复 globalProperties.$api 的旧值。异步初始化会检查 binding generation，已卸载 App 不会再收到迟到的 onReady。
• Engine 插件采用事务式替换：新管理器初始化成功后才释放旧管理器；Engine 卸载后迟到的 app:created 不会再次注入管理器。
• 所有请求 composable 都通过 onScopeDispose 取消当前请求。用户回调属于 observer，回调异常会进入诊断通道，不会改变已经提交的请求状态。

推荐目录结构

src/ 目录已经按职责收敛为以下结构：

src/
  composables/
    shared/
      requestController.ts
      requestOptions.ts
    useApi.ts
    useApiManager.ts
    useApiStatus.ts
    useLeapApi.ts
    useMutation.ts
    usePaginatedApi.ts
    useRestfulApi.ts
    index.ts
  constants/
    injectionKeys.ts
    version.ts
  plugin/
    createApiEngineVuePlugin.ts
    createApiPlugin.ts
    installApiManager.ts
    index.ts
  entry/
    index.ts
  index.ts

命名规则：

• 文件名只表达稳定职责，不使用“优化”“增强”“临时”之类阶段性命名。
• shared/ 只保留被多个 composable 复用、且职责明确的小能力。
• plugin/ 目录只放插件安装与 Vue 注入桥接，不承载请求执行逻辑。

本轮收敛点

• 用 installApiManagerToApp() 统一原生 Vue 与 engine-Vue 两条安装链路，避免重复注入逻辑。
• 用 requestController.ts 统一请求取消与“只提交最新结果”的控制，减少并发覆盖旧状态的问题。
• 用 requestOptions.ts 统一 API 目标解析和请求参数构造，减少各 composable 的分支重复。
• useRestfulApi() / useLeapApi() 不再带注册副作用，只负责消费已有 API 定义。
• usePaginatedApi() 增加内部分页状态护栏，避免内部翻页方法和外部 watch 形成重复请求。
• 原生 Vue 与 engine-Vue 插件都会透传 ApiManagerConfig.cache、deduplicate、retry，让应用只启用 api-core 的运行时能力，不在适配层复制实现。
• .ldesign/tsconfig.typecheck.json 只用于包内联调的源码级类型检查，避免开发态被旧构建产物干扰，同时不污染正式产物构建。

导出能力

• 完整透传 @composy/api-core
• 注入键：
  • API_MANAGER_KEY
  • API_CONFIG_KEY
  • API_EVENT_EMITTER_KEY
• composables：
  • useApi
  • useRestfulApi
  • useLeapApi
  • useMutation
  • usePaginatedApi
  • useApiStatus
• 插件：
  • createApiPlugin
  • createApiEngineVuePlugin
  • createApiEnginePlugin

更多边界与适配器说明见 ../../docs/index.md 和 ../../PUBLIC-API.md。