312 lines
7.9 KiB
Markdown
312 lines
7.9 KiB
Markdown
|
---
|
|||
|
|
name: jjb-common-lib-http
|
|||
|
|
description: 定义 @cqsjjb/jjb-common-lib http 模块使用规范。在使用 Get、Post、Delete、Put、@ 操作符时查阅。
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# http 模块使用规范
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
`http` 模块是 `@cqsjjb/jjb-common-lib` 通用工具库中的 HTTP 请求模块，基于 axios 高度封装，专为微应用场景设计。`declareRequest` 的接口请求就是基于此模块实现。
|
|||
|
|
|
|||
|
|
### 导入方式
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
import { http } from '@cqsjjb/jjb-common-lib';
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 内置方法详解
|
|||
|
|
|
|||
|
|
### Get(api, data?, headers?)
|
|||
|
|
|
|||
|
|
GET 请求方法。
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `api` (string): 请求地址
|
|||
|
|
- `data` (object, 可选): 提交数据，默认为 `{}`
|
|||
|
|
- `headers` (object, 可选): 请求头，默认为 `{}`
|
|||
|
|
|
|||
|
|
**返回值：**
|
|||
|
|
- `Promise<IResponse>`: 返回 Promise，解析为响应对象
|
|||
|
|
|
|||
|
|
**注意事项：**
|
|||
|
|
- GET 请求不允许使用 `@` 操作符，如果使用会抛出错误
|
|||
|
|
|
|||
|
|
**示例：**
|
|||
|
|
```javascript
|
|||
|
|
http.Get(
|
|||
|
|
'http://xxx.xxx.com/api/...',
|
|||
|
|
{ id: 1 },
|
|||
|
|
{ token: 'xxx' }
|
|||
|
|
).then(res => {
|
|||
|
|
console.log(res);
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Post(api, data?, headers?)
|
|||
|
|
|
|||
|
|
POST 请求方法。
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `api` (string): 请求地址
|
|||
|
|
- `data` (object, 可选): 提交数据，默认为 `{}`
|
|||
|
|
- `headers` (object, 可选): 请求头，默认为 `{}`
|
|||
|
|
|
|||
|
|
**返回值：**
|
|||
|
|
- `Promise<IResponse>`: 返回 Promise，解析为响应对象
|
|||
|
|
|
|||
|
|
**特殊说明：**
|
|||
|
|
- 支持 `@` 操作符：如果 URL 中包含 `@`，数据不会包装在 `request` 字段中
|
|||
|
|
- 不使用 `@` 操作符时，数据会自动包装在 `request` 字段中
|
|||
|
|
|
|||
|
|
**示例：**
|
|||
|
|
```javascript
|
|||
|
|
// 不使用 @ 操作符，数据会被包装在 request 字段中
|
|||
|
|
http.Post('/api/user', { name: 'test' })
|
|||
|
|
// 实际发送的数据: { request: { name: 'test' } }
|
|||
|
|
|
|||
|
|
// 使用 @ 操作符，数据直接发送
|
|||
|
|
http.Post('@/api/user', { name: 'test' })
|
|||
|
|
// 实际发送的数据: { name: 'test' }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Delete(api, data?, headers?)
|
|||
|
|
|
|||
|
|
DELETE 请求方法。
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `api` (string): 请求地址
|
|||
|
|
- `data` (object, 可选): 提交数据，默认为 `{}`
|
|||
|
|
- `headers` (object, 可选): 请求头，默认为 `{}`
|
|||
|
|
|
|||
|
|
**返回值：**
|
|||
|
|
- `Promise<IResponse>`: 返回 Promise，解析为响应对象
|
|||
|
|
|
|||
|
|
**特殊说明：**
|
|||
|
|
- 支持 `@` 操作符，行为与 Post 方法相同
|
|||
|
|
|
|||
|
|
**示例：**
|
|||
|
|
```javascript
|
|||
|
|
http.Delete('/api/user/1', {}, { token: 'xxx' })
|
|||
|
|
.then(res => console.log(res));
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Put(api, data?, headers?, redirect?)
|
|||
|
|
|
|||
|
|
PUT 请求方法。
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `api` (string): 请求地址
|
|||
|
|
- `data` (object, 可选): 提交数据，默认为 `{}`
|
|||
|
|
- `headers` (object, 可选): 请求头，默认为 `{}`
|
|||
|
|
- `redirect` (string, 可选): 重定向地址，默认为 `''`
|
|||
|
|
|
|||
|
|
**返回值：**
|
|||
|
|
- `Promise<IResponse>`: 返回 Promise，解析为响应对象
|
|||
|
|
|
|||
|
|
**特殊说明：**
|
|||
|
|
- 支持 `@` 操作符，行为与 Post 方法相同
|
|||
|
|
|
|||
|
|
**示例：**
|
|||
|
|
```javascript
|
|||
|
|
http.Put(
|
|||
|
|
'/api/user/1',
|
|||
|
|
{ name: 'updated' },
|
|||
|
|
{ token: 'xxx' },
|
|||
|
|
false
|
|||
|
|
).then(res => console.log(res));
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Patch(api, data?, headers?)
|
|||
|
|
|
|||
|
|
PATCH 请求方法。
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `api` (string): 请求地址
|
|||
|
|
- `data` (object, 可选): 提交数据，默认为 `{}`
|
|||
|
|
- `headers` (object, 可选): 请求头，默认为 `{}`
|
|||
|
|
|
|||
|
|
**返回值：**
|
|||
|
|
- `Promise<IResponse>`: 返回 Promise，解析为响应对象
|
|||
|
|
|
|||
|
|
**特殊说明：**
|
|||
|
|
- 支持 `@` 操作符，行为与 Post 方法相同
|
|||
|
|
|
|||
|
|
**示例：**
|
|||
|
|
```javascript
|
|||
|
|
http.Patch('/api/user/1', { name: 'patched' }, { token: 'xxx' })
|
|||
|
|
.then(res => console.log(res));
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### request(api, method, data?, headers?)
|
|||
|
|
|
|||
|
|
通用请求方法。
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `api` (string): 请求地址
|
|||
|
|
- `method` (string): 请求方式（如 'get'、'post'、'put'、'delete'、'patch'）
|
|||
|
|
- `data` (object, 可选): 提交数据，默认为 `{}`
|
|||
|
|
- `headers` (object, 可选): 请求头，默认为 `false`
|
|||
|
|
|
|||
|
|
**返回值：**
|
|||
|
|
- `Promise<IResponse>`: 返回 Promise，解析为响应对象
|
|||
|
|
|
|||
|
|
**说明：**
|
|||
|
|
- 此方法支持请求拦截器，如果配置了请求拦截器，会先执行拦截器再发送请求
|
|||
|
|
|
|||
|
|
## 响应数据格式 (IResponse)
|
|||
|
|
|
|||
|
|
所有请求方法返回的响应对象都遵循以下格式：
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
interface IResponse<T = any> {
|
|||
|
|
// 数据总条数
|
|||
|
|
totalCount?: number;
|
|||
|
|
// 数据
|
|||
|
|
data?: T;
|
|||
|
|
// 是否成功
|
|||
|
|
success?: boolean;
|
|||
|
|
// 错误信息
|
|||
|
|
errMessage?: string;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 核心特性
|
|||
|
|
|
|||
|
|
### 自动 URL 处理
|
|||
|
|
|
|||
|
|
- 自动根据 `API_HOST` 配置添加请求前缀
|
|||
|
|
- 支持通过 `getJJBCommonHttpConfig()` 配置 `API_HOST`
|
|||
|
|
- 如果未配置 `API_HOST`，会从 `window.__JJB_ENVIRONMENT__.API_HOST` 读取
|
|||
|
|
- 如果 URL 已经是完整的 HTTP/HTTPS 地址，则不会添加前缀
|
|||
|
|
|
|||
|
|
### Token 自动注入
|
|||
|
|
|
|||
|
|
- 自动从 `window.sessionStorage.token` 读取 token
|
|||
|
|
- 如果配置了 `getJJBCommonHttpConfig().header`，则使用配置的 header
|
|||
|
|
- 否则自动将 token 添加到请求头的 `token` 字段
|
|||
|
|
|
|||
|
|
### 租户代码自动注入
|
|||
|
|
|
|||
|
|
- 自动从 `window.__JJB_ENVIRONMENT__.tenantCode` 读取租户代码
|
|||
|
|
- 如果存在租户代码，会自动添加到请求头的 `tenantCode` 字段
|
|||
|
|
|
|||
|
|
### 请求/响应拦截器
|
|||
|
|
|
|||
|
|
- 支持通过全局配置设置请求拦截器：`getJJBCommonGlobalConfig().httpInterceptor.request`
|
|||
|
|
- 支持通过全局配置设置响应拦截器：`getJJBCommonGlobalConfig().httpInterceptor.response`
|
|||
|
|
- 拦截器可以是同步函数或返回 Promise 的异步函数
|
|||
|
|
|
|||
|
|
### 错误提示
|
|||
|
|
|
|||
|
|
- 接口返回错误时自动通过 `antd.message` 显示错误信息
|
|||
|
|
- 错误信息来自响应数据的 `errMessage` 字段
|
|||
|
|
|
|||
|
|
### 超时配置
|
|||
|
|
|
|||
|
|
- 默认超时时间为 5 分钟（60000 * 5 毫秒）
|
|||
|
|
- 可通过 `getJJBCommonGlobalConfig().httpTimeout` 配置超时时间
|
|||
|
|
|
|||
|
|
### 响应类型配置
|
|||
|
|
|
|||
|
|
- 默认响应类型为 `'json'`
|
|||
|
|
- 可通过 `getJJBCommonGlobalConfig().httpResponseType` 配置响应类型
|
|||
|
|
|
|||
|
|
## @ 操作符说明
|
|||
|
|
|
|||
|
|
`@` 操作符用于控制请求数据的包装方式：
|
|||
|
|
|
|||
|
|
- **不使用 `@` 操作符**：数据会被包装在 `request` 字段中
|
|||
|
|
```javascript
|
|||
|
|
http.Post('/api/user', { name: 'test' })
|
|||
|
|
// 实际发送: { request: { name: 'test' } }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **使用 `@` 操作符**：数据直接发送，不进行包装
|
|||
|
|
```javascript
|
|||
|
|
http.Post('@/api/user', { name: 'test' })
|
|||
|
|
// 实际发送: { name: 'test' }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**注意事项：**
|
|||
|
|
- GET 请求不允许使用 `@` 操作符
|
|||
|
|
- POST、PUT、DELETE、PATCH 请求支持 `@` 操作符
|
|||
|
|
|
|||
|
|
## 使用示例
|
|||
|
|
|
|||
|
|
### 基本 GET 请求
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
import { http } from '@cqsjjb/jjb-common-lib';
|
|||
|
|
|
|||
|
|
http.Get('/api/users', { page: 1, pageSize: 10 })
|
|||
|
|
.then(res => {
|
|||
|
|
if (res.success) {
|
|||
|
|
console.log(res.dataSource);
|
|||
|
|
}
|
|||
|
|
})
|
|||
|
|
.catch(err => {
|
|||
|
|
console.error('请求失败', err);
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### POST 请求（不使用 @ 操作符）
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
http.Post('/api/user', {
|
|||
|
|
name: '张三',
|
|||
|
|
age: 25
|
|||
|
|
}).then(res => {
|
|||
|
|
if (res.success) {
|
|||
|
|
console.log('创建成功');
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### POST 请求（使用 @ 操作符）
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
http.Post('@/api/user', {
|
|||
|
|
name: '张三',
|
|||
|
|
age: 25
|
|||
|
|
}).then(res => {
|
|||
|
|
if (res.success) {
|
|||
|
|
console.log('创建成功');
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 带自定义请求头的请求
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
http.Post('/api/user', { name: 'test' }, {
|
|||
|
|
'Custom-Header': 'custom-value'
|
|||
|
|
}).then(res => {
|
|||
|
|
console.log(res);
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 环境要求
|
|||
|
|
|
|||
|
|
- 必须在 `window` 对象上定义 `__JJB_ENVIRONMENT__`，否则会输出错误日志
|
|||
|
|
- 建议在应用启动时设置 `window.__JJB_ENVIRONMENT__`，包含以下字段：
|
|||
|
|
- `API_HOST`: API 基础地址
|
|||
|
|
- `tenantCode`: 租户代码（可选）
|
|||
|
|
|
|||
|
|
## 相关模块
|
|||
|
|
|
|||
|
|
- **declareRequest**：接口请求声明基于此模块实现
|
|||
|
|
- **详细文档**：参考 `reference/http.js` 查看完整的实现代码
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. **错误处理**：建议使用 `.catch()` 处理请求错误，虽然模块会自动处理部分错误，但网络错误等仍需要手动处理
|
|||
|
|
|
|||
|
|
2. **Token 管理**：Token 会自动从 `sessionStorage` 读取，确保在请求前已正确设置 token
|
|||
|
|
|
|||
|
|
3. **URL 配置**：确保正确配置 `API_HOST`，否则可能无法正确发送请求
|
|||
|
|
|
|||
|
|
4. **响应格式**：响应数据会被统一处理，建议使用 `success` 字段判断请求是否成功
|
|||
|
|
|
|||
|
|
5. **@ 操作符**：理解 `@` 操作符的作用，根据后端接口要求选择是否使用
|