# ldesign-http

**Repository Path**: ldesign-v1/ldesign-http

## Basic Information

- **Project Name**: ldesign-http
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LDesign Http

`@composy/http-workspace`(private)是 LDesign
HTTP 能力体系的工作区编排包,负责编排 `core` / `vue` / `vanilla`
三个发布子包的构建、测试与文档。HTTP 体系解决的问题是:以多适配器架构提供类型安全、可拦截、可缓存、可重试、可取消的完整请求生命周期管理,并按框架提供不同集成层。

## 📦 子包结构

| 子包                                     | 包名                    | 职责                                                                                                                          |
| ---------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| [`packages/core`](./packages/core)       | `@composy/http-core`    | 框架无关核心:`HttpClient` + Fetch 及可选 Axios/Alova/Ky 适配器、拦截器链、缓存、重试、并发控制、SSE/WebSocket/Mock 等高级特性 |
| [`packages/vue`](./packages/vue)         | `@composy/http-vue`     | Vue 3 集成:插件安装、组合式 API(`useHttp` / `useQuery` / `useMutation`)、组件与指令                                           |
| [`packages/vanilla`](./packages/vanilla) | `@composy/http-vanilla` | 原生 JS/TS 集成:请求状态控制器与 DOM 状态绑定                                                                                 |

依赖关系:vue 与 vanilla 均基于
`@composy/http-core`,只做各自生态的生命周期与视图绑定。

## 📥 安装

按使用场景选择子包(通常无需直接安装本工作区包):

```bash
# 核心包(框架无关)
pnpm add @composy/http-core

# 仅 Vue 3 集成
pnpm add @composy/http-vue

# 原生 JavaScript / TypeScript 集成
pnpm add @composy/http-vanilla
```

环境要求:Node.js >= 18;TypeScript 项目建议 >= 5.7。

## 🚀 快速开始

完整用法见各子包 README。最小示例:

```ts
import { createHttpClient } from '@composy/http-core'

// 异步创建(推荐,自动探测最优适配器)
const client = await createHttpClient({
  baseURL: 'https://api.example.com',
  timeout: 10000,
})

const users = await client.get<User[]>('/users')
```

```ts
// Vue 3:app.use() 一行接入
import { createHttpPlugin } from '@composy/http-vue'

app.use(
  createHttpPlugin({
    baseURL: 'https://api.example.com',
    cache: { enabled: true },
    retry: { retries: 3 },
  })
)
```

核心能力速览:**多适配器**(fetch 默认零依赖；Axios/Alova/Ky 通过 optional
subpath 按需接入)、**拦截器链**(同步/异步自动分流)、**智能缓存**(Memory/LocalStorage/IndexedDB 后端)、**自动重试**(指数退避)、**并发控制与去重**、**文件上传下载进度**、**请求取消**。

## 🔨 构建产物与验证

三个子包均通过 `@composy/builder` 产出 `dist` / `es` / `esm` / `lib`
四种产物。本工作区常用脚本:

```bash
pnpm build          # 依次构建 core → vue → vanilla
pnpm type-check     # 全部子包类型检查
pnpm test:run       # 单元测试(ltesting run:unit)
pnpm lint:check     # ESLint 检查
pnpm quality:check  # lint + format + type-check 一键检查
```

## 🔗 相关入口

- 文档站点:`pnpm docs:dev`(Longpress,配置见 `.ldesign/doc.config.ts`)
- Playground:`pnpm playground:dev`(演示注册见
  `.ldesign/playground.config.ts`,演示源码在 `examples/`)
- 子包文档:[core README](./packages/core/README.md) ·
  [vue README](./packages/vue/README.md) ·
  [vanilla README](./packages/vanilla/README.md)

## 安全与生命周期约定

- `cache` 默认关闭；应用层缓存只缓存成功的 GET。带
  `Authorization`、`Cookie`、租户/用户标识或 `credentials: 'include'`
  的请求默认不进入缓存，若业务确认安全共享，必须显式设置 `requestPartitionKey`。
- 并发去重默认只合并 GET/HEAD/OPTIONS；POST/PUT 等写请求只有显式提供 `dedupeKey`
  才会去重，且请求体会参与键计算。
- `destroy()`
  只释放客户端自己创建的运行时资源，不会清空外部传入的持久化 storage；需要清空业务缓存时请显式调用
  `clearCache()`。
- Vue 的 `useRequest`、`useQuery` 和 `useAsyncRequest`
  会隔离过期请求的状态回写；`useAsyncRequest` 的回调必须使用传入的 `signal`
  连接到底层异步工作。

## 架构端口与可选适配器

完整的公开面分级见 [Public API Inventory](./PUBLIC-API.md)。

HTTP Core 不依赖完整的 Cache/Queue/Device/Error/Logger runtime。可以分别通过
`createCacheStorageAdapter()`、`createQueuePortAdapter()`、`BrowserLifecyclePort`、
`HttpDiagnosticSink` 接入宿主运行时；外部对象由调用方拥有，`destroy()`
不会越权销毁。

SSE/WebSocket 的连接、心跳和重连应由 `sse-core` / `websocket-core`
owner 管理，HTTP 只负责兼容映射或 GraphQL subscription transport。

Axios、Alova、Ky 适配器位于 `@composy/http-core/adapters/axios`、
`@composy/http-core/adapters/alova`、`@composy/http-core/adapters/ky`，或统一从
`@composy/http-core/adapters/optional` 导入；根入口只保留零依赖 Fetch 和工厂。

`setConfig()`
会拒绝替换 adapter、monitor、priorityQueue、connectionPool、queuePort、diagnosticSink 等构造期资源；请求基础配置、retry、cache、concurrency 属于热更新字段。可用
`classifyHttpClientConfigChange()` 在提交前获取分类。

性能与发布检查:

```bash
pnpm benchmark:fast-path
pnpm consumer:check
pnpm consumer:tarball
```