request 最佳实践
17:43说明
业务里不要在每个页面各 http.create 一次:把实例、defaults 与拦截器收敛到一个模块文件,页面统一 import 这份实例。ESM 模块在同一运行环境只执行一次,因此这份实例天然是应用级单例——所有页面共享同一套 baseURL、超时、请求头、token 注入与解包规则。
与 http 的关系
http 是库内置的默认实例(baseURL 为空、无业务拦截器);api/request.ts 里派生出的 request 才是业务实例。页面只 import request,不要直接改 http。
目录建议
api/
├── request.ts 业务实例:defaults + 导出
├── interceptors.ts 可复用拦截器:任意实例都能装
└── user.ts 业务接口函数(可选,页面不拼 URL)
pages/
└── user/index.uvue 页面:import request 或接口函数创建业务实例
// api/request.ts
import { http } from '@/uni_modules/uview-pro-x';
import { setupInterceptors } from './interceptors';
// 默认请求头:模块级只建一次
const defaultHeaders = new JsonObject();
defaultHeaders['content-type'] = 'application/json';
defaultHeaders['x-client'] = 'uview-pro-x';
// 业务实例:继承 http 的内置默认值,再覆盖 baseURL / timeout / headers
const request = http.create({
baseURL: 'https://api.example.com',
timeout: 15000,
headers: defaultHeaders
});
// 拦截器不随 create 继承,必须显式注册
setupInterceptors(request);
export { request };注册拦截器
把拦截器写成「给任意实例安装」的函数,主实例与多域名实例都能复用同一段逻辑。
// api/interceptors.ts
import type { HttpInstance } from '@/uni_modules/uview-pro-x';
export function setupInterceptors(instance: HttpInstance): void {
instance.interceptors.request.use((config) => {
// config.url 是拼好 baseURL 的完整地址,可据此只给业务域名注入凭证
if (!config.url.startsWith('https://api.example.com')) {
return config;
}
// 每次请求都读 storage:登录后换 token 立即生效
const raw = uni.getStorageSync('token');
let token = '';
if (raw != null && typeof raw == 'string') {
token = raw as string;
}
if (token.length > 0) {
config.headers['authorization'] = 'Bearer ' + token;
}
return config;
});
instance.interceptors.response.use((res) => {
// 解包:页面直接拿业务数据,而不是 HttpResponse
return res.data;
}, (error) => {
// 取消是正常流程,不提示
if (error.code != 'ERR_CANCELED') {
uni.showToast({ title: error.message, icon: 'none' });
}
// 必须返回:返回值就是最终 reject 给页面的内容
return error;
});
}拦截器注册时机
setupInterceptors 在 api/request.ts 顶层执行,模块只加载一次,所以拦截器只注册一次。不要在页面里再调一次:实例没有 eject,数组只增不减,每进一次页面就会多一层拦截器。
页面中使用
页面 import 的是同一个模块实例,配置与拦截器自动生效,页面只需关心业务数据与状态。
<template>
<ux-button text="加载用户" type="primary" @click="load()" />
<text>{{ summary }}</text>
</template>
<script setup lang="ts">
import { request } from '@/api/request';
import type { HttpError } from '@/uni_modules/uview-pro-x';
type User = {
id: number;
name: string;
};
const summary = ref<string>('待加载');
const load = (): void => {
// 响应拦截器已解包,data 就是接口返回的数据
request.get('/user/1').then((data: any) => {
const user = data as User;
summary.value = user.name;
}).catch((e: any) => {
const err = e as HttpError;
summary.value = err.code + ' · HTTP ' + err.status.toString();
});
};
</script>再包一层接口函数能进一步收敛 URL 与类型,页面完全看不到请求细节:
// api/user.ts
import { request } from './request';
export type User = {
id: number;
name: string;
};
export function fetchUser(id: number): Promise<any> {
return request.get('/user/' + id.toString());
}// 页面里
import { fetchUser } from '@/api/user';
import type { User } from '@/api/user';
const load = (): void => {
fetchUser(1).then((data: any) => {
const user = data as User;
console.log(user.name);
});
};需要 loading / error 三态时,用 useRequest 包住同一个 request 调用即可,实例与拦截器都不变。
多域名
先按场景选方式:
| 场景 | 方式 | 是否继承 defaults | 是否继承拦截器 |
|---|---|---|---|
| 偶发调用第三方接口、静态资源 | 直接传绝对 URL | -(跳过 baseURL 拼接) | 是 |
| 长期存在的第二域名(上传、开放平台) | request.create({ baseURL }) | 是 | 否,需重新注册 |
| 凭证 / 超时 / 拦截器完全独立 | http.create({ baseURL }) | 否 | 否,需重新注册 |
方案一:绝对 URL(偶发请求)
url 以 http://、https://、// 开头时不会拼接 baseURL,单次请求直接走外链:
// 第三方状态查询,不经过 baseURL
request.get('https://open.example.com/v1/status').then((data: any) => {
console.log(data);
});params 仍会正常序列化追加,绝对 URL 与相对路径的用法完全一致。
外链请求也会经过全局拦截器
绝对 URL 不跳过拦截器,若拦截器无条件注入 authorization,token 会被发给第三方域名。所以要像上面的 setupInterceptors 那样,用 config.url 判断域名后再注入凭证。
方案二:派生第二个实例(长期多域名)
域名会长期使用、需要独立超时或独立配置时,派生一个专用实例,并重新安装需要的拦截器:
// api/cdn.ts
import { request } from './request';
import { setupInterceptors } from './interceptors';
// 以业务实例为父:继承 headers 等 defaults,只覆盖 baseURL 与超时
const cdnRequest = request.create({
baseURL: 'https://cdn.example.com',
timeout: 30000
});
// create 不继承拦截器,需要重新注册
setupInterceptors(cdnRequest);
export { cdnRequest };setupInterceptors 里的域名白名单会让这个实例自动跳过 token 注入(config.url 不是主域名),行为符合预期。若第二个域名需要另一套凭证,就不要复用它,单独写一套拦截器再 use。
不能在单次请求里覆盖 baseURL
get / post 等方法的第三参是 HttpCallConfig,只有 headers / timeout / validateStatus / meta / signal,没有 baseURL:
// 无效:HttpCallConfig 不支持 baseURL,写上去类型检查直接报错
request.get('/list', null, { baseURL: 'https://other.example.com' });要换域名只有两条路:传绝对 URL(单次),或 create 一个实例(长期)。
不要做的事
| 写法 | 后果 |
|---|---|
页面里 request.interceptors.request.use(...) | 每进一次页面多一层拦截器,且没有 eject 可移除 |
页面里 request.setDefaults({...}) | 改的是应用级单例,所有页面同时受影响 |
页面里 request.defaults.headers['x'] = ... | 同上,且后续 request.create 派生实例会继承这个 header |
页面里 http.create({...}) 当业务实例 | 不继承业务 headers 与拦截器,每个页面一份配置,无法统一治理 |
页面里 http.setDefaults({...}) | 污染库内置默认实例,之后所有 http.create 都被影响 |
注意事项
- 实例是单例:
api/request.ts顶层代码只在首次 import 时执行,所有页面共享同一实例;request.create()每次都会新建实例,且拦截器为空。 - token 在拦截器里现读:不要在模块顶层读一次存到变量,登录 / 登出后不会更新。
config.url是拼接后的完整地址:拦截器里改url会直接生效,库不会再次拼baseURL。- 解包只作用于
request与方法糖:upload()返回UploadResult、download()返回DownloadResult,不受响应拦截器影响。 - 请求拦截器返回
null会中断请求:以ERR_CANCELEDreject,可用于「未登录不发起请求」,页面侧用http.isCancel(e)判断。 - 页面仍要 catch:拦截器只负责提示与记录,reject 依然会冒泡;不 catch 会产生未处理的 Promise 拒绝警告。需要自动三态时用
useRequest。 - 拦截器里避免重复弹提示:多个请求并发失败时
showToast会连弹,必要时加去重或节流。