从网络取数据
这一篇讲怎么用 fetch() 发 HTTP 请求:取回 JSON、发送数据、上传和下载文件、处理失败、取消和超时。涉及的类是 Response、Request、Blob、AbortController 和 AbortSignal。大文件、下载进度和服务器持续推送的内容见边下载边读响应。
下面的例子都写在 async 函数里:await 只能写在 async 函数里,文件顶层不能直接写。
推荐的做法
把两种失败和超时写在一个函数里,所有请求都经过它。 网络不通时 fetch() 抛异常;服务器返回 404、500 时 fetch() 不抛异常,只是 res.ok 是 false。两处都要处理,写在一处,每个调用的地方只需要处理一种异常。
/**
* @param {string} url
* @param {RequestInit} [init]
*/
async function request(url, init) {
let res;
let data;
try {
// 15 秒内没有完成就放弃。调用方给了自己的 signal 时以调用方的为准
res = await fetch(url, { signal: AbortSignal.timeout(15000), ...init });
if (res.ok) data = await res.json();
} catch (err) {
if (err instanceof SyntaxError) throw new Error('服务器返回的不是 JSON');
if (err instanceof Error && err.name === 'AbortError') {
throw new Error('请求超时或被取消');
}
throw new Error('网络不通');
}
if (!res.ok) {
throw new Error('服务器返回 ' + res.status);
}
return data;
}
request('https://httpbin.org/get')
.then((data) => console.log(data.url))
.catch((err) => console.log(err.message));结果
- 请求成功时输出
https://httpbin.org/get。 - 没有网络或连不上服务器时输出
网络不通。 - 服务器返回 404 时输出
服务器返回 404。 - 15 秒内没有下载完时输出
请求超时或被取消。 - 内容不是合法的 JSON 时输出
服务器返回的不是 JSON。
另外四条:
- 文件和图片用
blob()读。 内容不进入 JS 的内存,拿到后直接交给UIImage.imageWithData()或application.fileSystem的writeBytes()。只有要自己逐字节处理时才用arrayBuffer()。 - 不再需要的请求要取消。 用户离开页面或者发起了新的搜索时,用
AbortController取消旧请求。不取消的话它会继续下载,下载的内容留在内存里。 - 大文件和不结束的响应用
res.body读。 几十 MB 的文件用整个读的四个方法会全部留在内存里;服务器持续推送的响应永远下载不完,四个方法的Promise永远不会完成。见边下载边读响应。 - 读内容之前先检查
res.ok。 服务器返回错误时,内容通常是一段错误说明,不是预期的数据。
第一个请求
下面的代码请求一个返回 JSON 的地址,把结果输出到控制台。整段可以直接写在 main.js 的顶层,不用等 sceneconnect。
async function load() {
// 1. 发请求。响应头和第一块内容到达时这一行就返回了
const res = await fetch('https://httpbin.org/get');
// 2. 检查服务器是否返回了成功的状态
if (!res.ok) {
console.log('服务器返回了错误:', res.status);
return;
}
// 3. 读出响应内容,按 JSON 解析
const data = await res.json();
console.log(res.status, data.url);
}
// 4. 网络不通时 fetch 会失败,要接住
load().catch((err) => {
console.log('请求没有发出去或没有收到响应:', err.message);
});结果
- 网络正常时,控制台输出
200 https://httpbin.org/get。 - 服务器返回 404 或 500 时,输出
服务器返回了错误: 404。 - 没有网络或连不上服务器时,输出
请求没有发出去或没有收到响应:加一段错误说明。
四步分别是:发请求、检查状态、读内容、处理失败。第 2 步和第 4 步处理的是两种不同的失败,见请求什么时候算失败。
地址要写完整
地址必须是完整的 URL,带协议和主机名,比如 https://api.example.com/items。fetch('/api/items') 这种相对地址没有可以参照的基准地址,Promise 以 TypeError 被拒绝。
fetch() 可以请求任何服务器。请求不受跨域规则限制,服务器不需要返回 CORS 响应头,也不会先发预检请求。
地址用 https://。iOS 默认拦截发往明文 http:// 地址的请求,CLI 生成的工程没有放开这条限制。fetch() 请求 http:// 地址的结果未在模拟器验证;同一条限制下,WebView 加载 http:// 地址实测被拦截。
请求本机的测试服务
开发时要请求本机或局域网里的 http:// 服务(比如跑在电脑上的测试服务),在 nacre.config.json 里放开本地网络这一项:
{
"ios": {
"infoPlist": {
"NSAppTransportSecurity": { "NSAllowsLocalNetworking": true }
}
}
}结果:发往 127.0.0.1 的 http:// 请求不再被拦截(模拟器上实测)。按 iOS 的文档,这一项同样放开局域网地址和 .local 主机名,其它地址仍然要 https://,这两点未在模拟器验证。配置文件的写法见配置 App。
取回 JSON
async function getJson() {
const res = await fetch('https://httpbin.org/get');
const data = await res.json();
console.log(data.url);
}结果:输出 https://httpbin.org/get。data 是解析好的普通对象。
内容不是合法的 JSON 时,res.json() 返回的 Promise 以 SyntaxError 被拒绝。
判断请求是否成功
async function checkStatus() {
const res = await fetch('https://httpbin.org/status/404');
console.log(res.ok); // false
console.log(res.status); // 404
}结果:这段代码不会抛异常。服务器返回 404 或 500 时,fetch() 仍然成功,只是 res.ok 是 false。res.ok 在状态码是 200 到 299 时为 true。
发送 JSON
async function postJson() {
const res = await fetch('https://httpbin.org/post', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'nacre', count: 3 }),
});
const echo = await res.json();
console.log(echo.json.name);
}结果:输出 nacre。这个测试地址会把收到的内容原样返回。
- 普通对象不能直接当
body:它会被转成字符串[object Object]发出去,不报错。要先用JSON.stringify()转成字符串。字符串里的中文按 UTF-8 发送。 Content-Type要自己写。字符串body不写时,发出去的是text/plain;charset=UTF-8,服务器不会把它当 JSON 解析。
body 能接受哪些值见 fetch() 的参数。
上传二进制数据
body 可以是类型数组、ArrayBuffer 或 Blob,字节原样发送。
async function postBytes() {
const bytes = new Uint8Array([0, 255, 16, 128]);
const res = await fetch('https://httpbin.org/post', {
method: 'POST',
headers: { 'Content-Type': 'application/octet-stream' },
body: bytes,
});
const echo = await res.json();
console.log(echo.data);
}结果:输出 data:application/octet-stream;base64,AP8QgA==。四个字节原样到了服务器。这个测试地址把二进制内容用 base64 回显。
注意:
body是类型数组或ArrayBuffer时,要自己写Content-Type。不写的话系统会填上application/x-www-form-urlencoded,服务器会把这些字节当成表单来解析(实测)。
body 是 Blob 时,Blob 的 type 会成为 Content-Type,不用另外写:
async function postBlob() {
const bytes = new Uint8Array([0, 255, 16, 128]);
const blob = new Blob([bytes], { type: 'application/octet-stream' });
const res = await fetch('https://httpbin.org/post', { method: 'POST', body: blob });
const echo = await res.json();
console.log(echo.headers['Content-Type']);
}结果:输出 application/octet-stream。
上传一个文件
先用 application.fileSystem 的 readBytes() 把文件读成 ArrayBuffer,再当 body 发送。
async function uploadFile() {
const path = application.fileSystem.documents + '/photo.jpg';
const bytes = await application.fileSystem.readBytes(path);
const res = await fetch('https://httpbin.org/post', {
method: 'POST',
headers: { 'Content-Type': 'image/jpeg' },
body: bytes,
});
console.log(res.status);
}结果:文件的字节作为请求体发出,输出 200。这个例子未在模拟器验证。
整个文件会先读进内存。上传期间得不到进度。
带上自定义请求头
async function withHeaders() {
const res = await fetch('https://httpbin.org/get', {
headers: {
'Authorization': 'Bearer abc123',
'Accept': 'application/json',
},
});
console.log(res.status);
}结果:请求带着这两个请求头发出,输出 200。
headers 可以是普通对象,也可以是 Headers 对象。请求头的名字里有不合法的字符,或者值里有换行时,fetch() 的 Promise 被拒绝。Host、Cookie、Origin 这些请求头都可以自己设置。
读响应头
async function readHeaders() {
const res = await fetch('https://httpbin.org/get');
console.log(res.headers.get('content-type'));
console.log(res.headers.get('CONTENT-TYPE'));
}结果:两行都输出 application/json。响应头的名字不区分大小写。
服务器返回了多个同名的响应头时,get() 得到用 , 连接起来的一个字符串。
取回文本
async function getText() {
const res = await fetch('https://httpbin.org/range/16');
const text = await res.text();
console.log(text);
}结果:输出 abcdefghijklmnop。
text() 一律按 UTF-8 解码,不看响应头里声明的编码。内容不是合法的 UTF-8 时得到空串 '',不报错。其它编码的文本用 arrayBuffer() 读出字节,自己解码。
下载一张图片并显示
async function getImage() {
const res = await fetch('https://httpbin.org/image/png');
const blob = await res.blob();
const image = UIImage.imageWithData(blob);
console.log(blob.size, image !== null);
}结果:输出图片的字节数和 true。image 可以赋给 UIImageView 的 image 属性,见 UIImage。内容不是图片时 image 是 null。
把下载的内容存成文件
async function saveFile() {
const res = await fetch('https://httpbin.org/bytes/1024');
const blob = await res.blob();
const path = application.fileSystem.documents + '/data.bin';
await application.fileSystem.writeBytes(path, blob);
console.log(blob.size);
}结果:输出 1024。文档目录里多了一个 1024 字节的文件 data.bin。这个例子未在模拟器验证。
内容从下载到写入文件都不进入 JS 的内存。下载期间整个文件仍然在 App 的内存里:整个读的四个方法,下载的内容一直留在内存里,直到 Response 不再被任何变量引用并被回收。
取回二进制数据自己处理
async function getBytes() {
const res = await fetch('https://httpbin.org/range/256');
const buffer = await res.arrayBuffer();
const bytes = new Uint8Array(buffer);
console.log(buffer.byteLength, bytes[0]);
}结果:输出 256 97。97 是字母 a 的编码。
四种读法的区别见四种读法怎么选。响应内容只能读一次,需要用两次的话把第一次读出的结果存进变量,见响应内容只能读一次。
取消一个请求
async function cancelRequest() {
const controller = new AbortController();
const promise = fetch('https://httpbin.org/delay/5', { signal: controller.signal });
setTimeout(() => controller.abort(), 200);
try {
await promise;
} catch (err) {
console.log(err instanceof Error ? err.name : err);
}
}结果:200 毫秒后输出 AbortError。请求被真正取消,不再占用网络。
- 一个
controller.signal可以交给多个请求,abort()一次全部取消。已经完成的请求不受影响。 signal也可以在构造Request时给,之后把这个Request交给fetch(),取消的效果相同。- 拿到
Response之后、读内容之前不想要了,也可以用它取消,下载立即停止。
给请求设超时
运行时不给请求另设超时,使用系统的默认值(iOS 的文档说是连续 60 秒没有收到数据,未在模拟器验证)。要更短的超时,用 AbortSignal.timeout():
async function withTimeout() {
try {
await fetch('https://httpbin.org/delay/5', { signal: AbortSignal.timeout(300) });
} catch (err) {
console.log(err instanceof Error ? err.name : err);
}
}结果:300 毫秒后请求被取消,输出 AbortError。
- 参数单位是毫秒。计时从调用
AbortSignal.timeout()的那一刻开始,不是从发请求开始。 - 时间包括下载内容的时间:
fetch()已经返回、内容还没读完时到了时间,读取内容的那一步被拒绝。 - 超时和手动取消得到的异常相同,都是
AbortError,从异常上区分不出是哪一种。
同时发多个请求
async function many() {
const urls = [
'https://httpbin.org/get?id=1',
'https://httpbin.org/get?id=2',
'https://httpbin.org/get?id=3',
];
const responses = await Promise.all(urls.map((url) => fetch(url)));
const results = await Promise.all(responses.map((res) => res.json()));
console.log(results.length);
}结果:三个请求同时发出,全部完成后输出 3。
- 运行时不限制同时进行的请求数量,请求之间互不等待。实测同时发出 10 个请求,总耗时小于单个请求的 4 倍。
- 其中一个请求在网络层失败时,
Promise.all整体被拒绝,其余请求的结果拿不到。要分别得到每个请求的结果,用Promise.allSettled。
自己创建一块数据
async function makeBlob() {
const blob = new Blob(['前缀-', '后缀'], { type: 'text/plain' });
console.log(blob.size, blob.type);
console.log(await blob.text());
}结果:输出 13 text/plain 和 前缀-后缀。size 是 UTF-8 编码后的字节数,一个汉字占 3 个字节。
在测试里代替真实的请求
new Response() 创建一个响应,不发请求。把要测的函数写成接收 Response,测试时传自己创建的那个:
async function fakeResponse() {
const res = new Response('{"ok":true}', {
status: 201,
headers: { 'Content-Type': 'application/json' },
});
const data = await res.json();
console.log(res.status, data.ok);
}结果:输出 201 true。
App 进入后台之后
iOS 在 App 进入后台后很快会暂停它的运行。那时还没完成的请求是继续、暂停还是失败,未在模拟器验证。必须完成的请求,回到前台后检查结果,失败了重发。
请求自动带上 cookie
服务器用 Set-Cookie 写的 cookie 被系统保存下来,之后发往同一站点的请求自动带上。未在模拟器验证。 这份 cookie 和 WebView 里网页的 cookie 是分开的两份(实测):用户在网页里登录,不会让 fetch() 带上登录状态,反过来也一样。
参见
fetch():函数和这一组类Response、Request、BlobAbortController、AbortSignal:取消和超时Headers、URL:请求头和地址- 边下载边读响应:大文件、下载进度、服务器推送