HTTP 请求方法

awe-axios 封装了常见的 HTTP 请求方法，并以装饰器的形式提供，用于快速定义 API 接口，主要包括：

类装饰器：@HttpApi
方法装饰器：@Get、@Post、@Put、@Delete、@Patch、@Options、@Head

@HttpApi

@HttpApi 是类级别的装饰器，被@HttpApi装饰的类会被视为一个HTTP接口类。如下所示：

/**
 * 表示UserApi是一个HTTP接口类，并且接口基本路径为http://localhost:3000/api/users
 */
@HttpApi('http://localhost:3000/api/users')
class UserApi {}

该装饰器可以定义 API 接口类的基础配置，作为该类中所有请求方法的公共配置。@HttpApi 支持的配置项（HttpApiDecoratorConfig 类型）如下：

配置项	类型	说明
`baseURL`	`string`	基础请求路径，会与方法装饰器的 `url` 拼接
`url`	`string`	相对路径前缀，用于统一拼接在方法路径前
`refAxios`	`AxiosInstance`	自定义 axios 实例，类中所有方法默认使用此实例
`mock`	`Object`	全局 mock 配置 - `on`: 是否开启 mock（布尔值） - `condition`: 触发真实接口的条件（函数，返回布尔值）

使用示例：

typescript

import { HttpApi, Get } from 'awe-axios';

// 基础用法：指定 baseURL
@HttpApi('https://api.example.com')
class UserApi {
  @Get('/users')
  getUserList(): any {} // 实际请求地址：https://api.example.com/users
}

// 完整配置
@HttpApi({
  baseURL: 'https://api.example.com',
  url: '/v1', // 路径前缀
})
class UserApiV1 {
  @Get('/users')
  getUserList(): any {} // 实际请求地址：https://api.example.com/v1/users
}

const api = new UserApiV1();
const { data } = await api.getUserList();

配置合并规则

当类装饰器（@HttpApi）与方法装饰器（如 @Get）存在相同配置时,优先采用方法级别的配置，同时对于某些配置会采用合并策略。如下所示：

baseURL：方法装饰器配置覆盖类装饰器
url：类装饰器的 url 与方法装饰器的 url 自动拼接（处理斜杠）
headers：两者深度合并，方法装饰器配置优先
refAxios：方法装饰器配置覆盖类装饰器

这种设计允许在类级别定义公共配置，在方法级别灵活调整特殊需求，具体请参考子项装饰器。

@Get

@Get 是方法级别的装饰器，用于定义 GET 请求接口。被该装饰器定义的接口默认以 GET 请求方式发送请求。基础用法如下：

typescript

@HttpApi('https://api.example.com')
class UserApi {
  // 仅指定路径
  @Get('/users')
  getUserList(): any {}

  // 带路径参数
  @Get('/users/:id')
  getUserDetail(): any {}
}

@Get 支持的配置项（HttpMethodDecoratorConfig 类型）继承自 axios 配置，并扩展了增强功能：

类别	配置项	说明
基础配置	`url`	请求路径（字符串或带路径参数的模板）
	`baseURL`	覆盖类装饰器的 `baseURL`
	`headers`	请求头信息
	`timeout`	超时时间（毫秒）
	`transformRequest`	请求数据转换器
	`transformResponse`	响应数据转换器
	`...`	你可以享受全部 `axios` 配置项其余`axios` 支持的配置项请参考 axios 文档
增强功能	`retry`	重试配置（次数或详细配置）
	`debounce`	防抖配置（延迟时间或详细配置）
	`throttle`	节流配置（间隔时间或详细配置）
	`mock`	方法级 `mock` 配置（覆盖全局配置）
	`refAxios`	覆盖类装饰器的默认 `axios` 实例

路径参数

通常来说，你需要配合各种参数来实现更复杂的 API 接口。awe-axios 提供了三种参数装饰器来满足你的传参需求：

@QueryParam：用于查询参数（?key=value）
@PathParam：用于路径参数（/path/:id）
@BodyParam：用于请求体参数（application/json 或 x-www-form-urlencoded）

如下所示：

typescript

@HttpApi('https://api.example.com')
class UserApi {
  @Get('/users/:id')
  getUserDetail(@PathParam('id') id: string): any {}
}

路径参数（如 :id）会被自动替换为实际值，并自动添加到请求路径中。参数装饰器的具体用法请参考参数装饰器。

@Post

@Post 用于定义 POST 请求，配置选项与 @Get 一致，主要区别在于默认发送请求体数据。用法如下：

typescript

@HttpApi('https://api.example.com')
class UserApi {
  @Post('/users')
  createUser(@BodyParam() user: { name: string; age: number }) {}

  @Post()
}

请求重传注意事项

@Post配置选项与 @Get 几乎一致，可按需设置重试、防抖等增强功能，但是要注意Post请求重传会有风险，请谨慎使用。同时某些封装功能有使用各类，比如@Debounce通常不会和@Throttle一起使用。具体请参考常用功能

@Put、@Delete、@Patch

这些装饰器的使用方式与 @Get、@Post 类似，分别对应 HTTP 标准的 PUT、DELETE、PATCH 方法，用于资源的更新、删除和部分更新操作。使用示例如下：

typescript

@HttpApi('https://api.example.com')
class UserApi {
  // 更新资源（全量更新）
  @Put('/users/{id}')
  updateUser() {}

  // 删除资源
  @Delete('/users/{id}')
  deleteUser() {}

  // 部分更新资源
  @Patch('/users/{id}')
  patchUser() {}
}

@Options、@Head

@Options：用于请求服务器支持的 HTTP 方法（跨域预检请求常用）
@Head：类似 @Get，但仅返回响应头，不返回响应体

使用示例如下：

typescript

@HttpApi('https://api.example.com')
class ResourceApi {
  // 检查服务器支持的方法
  @Options('/users')
  checkUserOptions() {}

  // 获取资源头信息
  @Head('/users')
  getUserHeaders() {}
}

HTTP 请求方法 ​

@HttpApi ​

@Get ​

@Post ​

@Put、@Delete、@Patch ​

@Options、@Head ​

HTTP 请求方法

@HttpApi

@Get

@Post

@Put、@Delete、@Patch

@Options、@Head