sakura-request

sakura-request 是一个基于 axios 的请求增强插件，面向“默认配置完整、类型可读、文档规范、适合 AI 代码生成”的场景设计。

1. 插件定位

• 保留 axios 作为默认底层依赖
• 提供实例级配置与单次请求配置双层覆盖
• 提供默认成功判定、错误提取、认证失效判断与重试策略
• 提供 headers、日志、认证失效、错误处理等生命周期钩子
• 提供响应队列能力，适合搜索联想等“自动取消旧请求、只消费最后一次响应”的场景

2. 目录结构

sakura-request/
  src/
    core/
      create-request-client.ts
      defaults.ts
      types.ts
      utils.ts
    index.ts
  dist/
    core/
      create-request-client.js
      defaults.js
      types.js
      utils.js
    index.js
    index.d.ts
  README.md
  USAGE.md
  API.md
  AI_GUIDE.md
  CHANGELOG.md
  examples/

3. 快速开始

import {
    createRequestClient,
    RequestMethodEnum
} from 'sakura-request'

const request = createRequestClient({
    baseURL: import.meta.env.VITE_PROXY_API,
    prefixUrl: import.meta.env.VITE_URL_PREFIX
})

const result = await request('/users', {
    method: RequestMethodEnum.GET,
    params: {
        page: 1
    }
})

4. 导出清单

4.1 核心方法

• createRequestClient
• defineRequestConfig
• createRequestHooks
• mergeRequestConfig

4.2 默认策略

• createDefaultRequestConfig
• defaultIsSuccess
• defaultIsAuthExpired
• defaultGetErrorMessage
• defaultGetResponseData
• defaultRetryCondition

4.3 枚举

• RequestMethodEnum
• RequestErrorTypeEnum
• RequestLogTypeEnum

4.4 类型

• RequestConfig
• RequestOptions
• RequestContext
• RequestResult
• NormalizedError
• RequestHooks
• RequestLogInfo
• ResolvedRequestConfig
• SakuraAxiosRequestConfig

5. 配置规则

• 默认配置始终存在，业务侧不配置也可以直接使用
• 优先级固定为：请求级配置 > 实例级配置 > 插件默认配置
• 通用配置放实例级，个别请求差异放请求级
• method 推荐优先使用 RequestMethodEnum
• getErrorMessage、onError、onAuthExpired 用于承接业务副作用，不要直接改内部 core/*

6. 常用能力

6.1 动态请求头

const request = createRequestClient({
    getHeaders: async () => ({
        Authorization: `Bearer ${ localStorage.getItem('token') || '' }`
    })
})

6.2 自定义成功判定

const request = createRequestClient({
    isSuccess: (response) => response?.data?.code === 1000
})

6.3 自定义错误提取

const request = createRequestClient({
    getErrorMessage: (errorOrResponse) => {
        return errorOrResponse?.response?.data?.msg
            || errorOrResponse?.data?.msg
            || errorOrResponse?.message
            || '请求失败'
    }
})

6.4 自定义响应数据提取

const request = createRequestClient({
    getResponseData: (response) => response?.data?.payload ?? null
})

6.5 启用重试

const request = createRequestClient({
    enableRetry: true,
    retryCount: 3,
    retryDelay: 500
})

未自定义 retryCondition 时，默认会对网络错误、超时错误和 5xx 响应执行重试。

6.6 响应队列

const result = await request('/search', {
    method: RequestMethodEnum.GET,
    params: {
        keyword: 'sakura'
    },
    useResponseQueue: true
})

同一 responseQueueKey 下发起新请求时，旧请求会被自动取消，旧 Promise 也会正常结束，不会一直挂起；这类队列内部取消不会再触发错误钩子和错误日志。

7. 文档导航

• API 手册
• AI 使用指南
• 场景示例

8. 本地验证

• 构建类型与产物：pnpm run build
• 校验 AI 示例代码：pnpm run typecheck:examples
• 一键验证：pnpm run verify:ai

9. 适用边界

• 适合在当前项目中作为 npm 包安装后复用
• 适合作为 AI 读取的统一请求层标准实现
• 推荐从 sakura-request 引入构建产物