Skip to content

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 或接口函数

创建业务实例 ​

ts
// 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 };

注册拦截器 ​

把拦截器写成「给任意实例安装」的函数,主实例与多域名实例都能复用同一段逻辑。

ts
// 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 的是同一个模块实例,配置与拦截器自动生效,页面只需关心业务数据与状态。

vue
<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 与类型,页面完全看不到请求细节:

ts
// 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());
}
ts
// 页面里
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,单次请求直接走外链:

ts
// 第三方状态查询,不经过 baseURL
request.get('https://open.example.com/v1/status').then((data: any) => {
    console.log(data);
});

params 仍会正常序列化追加,绝对 URL 与相对路径的用法完全一致。

外链请求也会经过全局拦截器

绝对 URL 不跳过拦截器,若拦截器无条件注入 authorization,token 会被发给第三方域名。所以要像上面的 setupInterceptors 那样,用 config.url 判断域名后再注入凭证。

方案二:派生第二个实例(长期多域名) ​

域名会长期使用、需要独立超时或独立配置时,派生一个专用实例,并重新安装需要的拦截器:

ts
// 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:

ts
// 无效: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_CANCELED reject,可用于「未登录不发起请求」,页面侧用 http.isCancel(e) 判断。
  • 页面仍要 catch:拦截器只负责提示与记录,reject 依然会冒泡;不 catch 会产生未处理的 Promise 拒绝警告。需要自动三态时用 useRequest。
  • 拦截器里避免重复弹提示:多个请求并发失败时 showToast 会连弹,必要时加去重或节流。