Uniapp网络请求全面指南：从基础到高级封装

在移动应用和跨平台开发中，网络请求是最基础也是最重要的功能之一。Uniapp作为一款流行的跨平台开发框架，提供了强大而灵活的网络请求API——uni.request。本文将全面介绍Uniapp网络请求的各个方面，包括基础使用、参数详解、错误处理、性能优化以及高级封装技巧，帮助开发者构建健壮的网络请求体系。

一、Uniapp网络请求概述

Uniapp的uni.request是一个基于Promise风格的HTTP客户端，它封装了各平台（小程序、H5、App）的网络请求能力，提供了一致的API接口。与原生JavaScript的fetch或jQuery的$.ajax相比，uni.request具有以下特点：

在Uniapp生态中，网络请求是与后端交互的主要方式，掌握uni.request的使用技巧对于开发高质量应用至关重要。

二、uni.request基础使用

2.1 基本请求示例

让我们从一个最简单的GET请求开始：

uni.request({
url: 'https://api.example.com/data',
success: (res) => {
console.log('请求成功:', res.data);
},
fail: (err) => {
console.error('请求失败:', err);
}
});

这个例子展示了uni.request最基本的使用方式：传入一个配置对象，包含请求URL和成功/失败回调函数。

2.2 请求方法配置

uni.request支持所有常见的HTTP方法：

// GET请求
uni.request({
url: 'https://api.example.com/data',
method: 'GET'
});

// POST请求
uni.request({
url: 'https://api.example.com/create',
method: 'POST',
data: { name: '产品名称', price: 99 }
});

// PUT请求
uni.request({
url: 'https://api.example.com/update/1',
method: 'PUT',
data: { price: 109 }
});

// DELETE请求
uni.request({
url: 'https://api.example.com/delete/1',
method: 'DELETE'
});

2.3 请求参数传递

请求参数可以通过data属性传递，Uniapp会根据请求方法自动处理参数位置：

// GET请求参数会附加在URL后
uni.request({
url: 'https://api.example.com/search',
data: { keyword: '手机', page: 1 }
});

// POST请求参数会放在请求体中
uni.request({
url: 'https://api.example.com/login',
method: 'POST',
data: { username: 'admin', password: '123456' }
});

三、请求配置详解

uni.request接受一个配置对象，包含丰富的配置选项。以下是主要配置项的详细说明：

3.1 核心配置项

3.2 请求头设置

请求头是网络请求中非常重要的部分，常用于传递认证信息、内容类型等：

uni.request({
url: 'https://api.example.com/protected',
header: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + token,
'X-Custom-Header': 'custom-value'
}
});

常见的请求头包括：

• Content-Type: 请求体类型，如application/json、application/x-www-form-urlencoded等

• Authorization: 认证令牌，通常用于JWT等认证方案

• Accept: 告诉服务器客户端能处理的响应类型

3.3 超时设置

网络请求可能会因为各种原因超时，合理的超时设置可以提升用户体验：

uni.request({
url: 'https://api.example.com/data',
timeout: 10000, // 10秒超时
success() {},
fail(err) {
if (err.errMsg.includes('timeout')) {
uni.showToast({ title: '请求超时', icon: 'none' });
}
}
});

超时设置需要考虑业务场景：

• 普通数据请求：5-10秒

• 文件上传：30-60秒

• 关键业务请求：适当延长但要有超时提示

四、响应处理与错误处理

4.1 响应数据结构

uni.request的成功回调会收到一个响应对象，包含以下属性：

{
data: {}, // 响应数据，类型取决于dataType配置
statusCode: 200, // HTTP状态码
header: {}, // 响应头
cookies: [] // 服务器返回的cookies
}

4.2 状态码处理

合理的状态码处理是健壮应用的基础：

uni.request({
url: 'https://api.example.com/data',
success: (res) => {
switch (res.statusCode) {
case 200:
// 成功处理
break;
case 401:
// 未授权，跳转登录
uni.navigateTo({ url: '/pages/login/login' });
break;
case 404:
// 资源不存在
break;
case 500:
// 服务器错误
break;
default:
// 其他状态码
}
}
});

4.3 错误处理

网络请求可能因多种原因失败，完善的错误处理必不可少：

uni.request({
url: 'https://api.example.com/data',
fail: (err) => {
console.error('请求失败:', err);

if (err.errMsg.includes('timeout')) {
uni.showToast({ title: '请求超时，请重试', icon: 'none' });
} else if (err.errMsg.includes('fail')) {
uni.showToast({ title: '网络错误，请检查网络', icon: 'none' });
}
}
});

常见的错误类型包括：

• 网络不可用

• 请求超时

• SSL证书错误（App端）

• 域名未配置（小程序端）

五、高级封装与实践

5.1 Promise封装

回调方式在现代前端开发中已经不推荐使用，我们可以将uni.request封装为Promise：

function request(options) {
return new Promise((resolve, reject) => {
uni.request({
…options,
success: (res) => {
if (res.statusCode >= 200 && res.statusCode < 300) {
resolve(res.data);
} else {
reject(new Error(`请求失败，状态码：${res.statusCode}`));
}
},
fail: (err) => {
reject(err);
}
});
});
}

// 使用示例
request({
url: 'https://api.example.com/data'
}).then(data => {
console.log(data);
}).catch(err => {
console.error(err);
});

5.2 完整请求封装

一个完整的请求封装通常包括以下功能：

• 基础URL配置

• 请求拦截（如添加token）

• 响应拦截（如统一错误处理）

• 请求取消

• 请求重试

const http = {
config: {
baseUrl: 'https://api.example.com',
timeout: 10000,
header: {
'Content-Type': 'application/json'
}
},

interceptors: {
request: null,
response: null
},

request(options) {
// 合并配置
options = { …this.config, …options };
options.url = options.baseUrl + options.url;

// 请求拦截
if (this.interceptors.request) {
options = this.interceptors.request(options);
}

return new Promise((resolve, reject) => {
options.success = (res) => {
// 响应拦截
if (this.interceptors.response) {
res = this.interceptors.response(res);
}
resolve(res.data);
};

options.fail = (err) => {
reject(err);
};

uni.request(options);
});
}
};

// 添加请求拦截器
http.interceptors.request = (config) => {
const token = uni.getStorageSync('token');
if (token) {
config.header.Authorization = `Bearer ${token}`;
}
return config;
};

// 添加响应拦截器
http.interceptors.response = (response) => {
if (response.statusCode === 401) {
uni.navigateTo({ url: '/pages/login/login' });
throw new Error('未授权，请重新登录');
}
return response;
};

// 使用示例
http.request({
url: '/user/info',
method: 'GET'
}).then(data => {
console.log(data);
}).catch(err => {
console.error(err);
});

5.3 文件上传与下载

除了普通的请求，Uniapp还提供了专门的文件上传和下载API：

// 文件上传
uni.chooseImage({
success: (res) => {
const tempFilePaths = res.tempFilePaths;
uni.uploadFile({
url: 'https://api.example.com/upload',
filePath: tempFilePaths[0],
name: 'file',
formData: {
'description': '图片描述'
},
success: (uploadRes) => {
console.log(uploadRes.data);
}
});
}
});

// 文件下载
uni.downloadFile({
url: 'https://example.com/file.pdf',
success: (res) => {
if (res.statusCode === 200) {
const filePath = res.tempFilePath;
uni.openDocument({
filePath: filePath,
fileType: 'pdf'
});
}
}
});

六、跨平台注意事项

Uniapp虽然提供了跨平台的网络请求API，但在不同平台上仍有一些差异需要注意：

6.1 小程序平台

6.2 H5平台

6.3 App平台

七、性能优化与最佳实践

// 请求取消示例
let requestTask = uni.request({
url: 'https://api.example.com/data',
success() {}
});

// 在页面卸载时取消请求
onUnload() {
requestTask.abort();
}

// 错误重试示例
function requestWithRetry(options, retry = 3) {
return new Promise((resolve, reject) => {
const wrappedRequest = (attempt) => {
request(options)
.then(resolve)
.catch(err => {
if (attempt < retry) {
setTimeout(() => wrappedRequest(attempt + 1), 1000);
} else {
reject(err);
}
});
};
wrappedRequest(0);
});
}

总结

Uniapp的uni.request提供了强大而灵活的网络请求能力，通过合理的封装和扩展，可以满足各种复杂的业务场景需求。本文从基础使用到高级封装，全面介绍了Uniapp网络请求的各个方面，希望可以帮助开发者构建更加健壮、高效的网络请求体系。

在实际项目中，建议根据团队规范和项目需求，开发适合自己项目的请求工具库，统一处理认证、错误、日志等公共逻辑，提高开发效率和代码质量。

记住，良好的网络请求处理不仅能提升应用性能，还能显著改善用户体验，是高质量应用不可或缺的一部分。