wangdoc/webapi-tutorial
1
0
Fork 0
mirror of https://github.com/wangdoc/webapi-tutorial.git synced 2025-12-20 00:59:54 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs(request): edit Request API

Browse Source
This commit is contained in:
ruanyf
2023-09-09 23:54:09 +08:00
parent 6ff6cdbe48
commit 1bd668c414
2 changed files with 146 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

178
docs/request.md
View File

@@ -2,6 +2,8 @@
浏览器原生提供 Request() 构造函数，用来构造发给服务器的 HTTP 请求。它生成的 Response 实例，可以作为`fetch()`的参数。
注意，构造一个 Request 对象，只是构造出一个数据结构，本身并不会发出 HTTP 请求，只有将它传入`fetch()`方法才会真的发出请求。
## 构造方法
Request 作为构造函数的语法如下，返回一个 Request 实例对象。
@@ -10,28 +12,59 @@ Request 作为构造函数的语法如下，返回一个 Request 实例对象。
new Request(url: String, [init: Object]): Request
```
它的第一个参数是请求的 URL 字符串，第二个参数是一个可选的对象，用来构造 HTTP 请求，它的类型如下。
它的第一个参数是请求的 URL 字符串，第二个参数是一个可选的配置对象，用来构造 HTTP 请求，该对象的类型描述如下。
```javascript
{
body : Object // 发送的数据体，必须是 Blob、BufferSource、FormData、String、URLSearchParams 类型之一
cache : String
credentials : String
headers : Object
integrity : String
keepalive : Boolean
method : String // HTTP 方法，必须是 'GET'、'POST'、'DELETE' 等值
mode : String
redirect : String // 必须是 'follow'、'error'、'manual' 之一
referrer : String
referrerPolicy : String
requestMode : String
requestCredentials : String
signal : AbortSignal
body: Object
cache: String
credentials: String
headers: Object
integrity: String
keepalive: Boolean
method: String
mode: String
redirect: String
referrer: String
referrerPolicy: String
requestMode: String
requestCredentials: String
signal: AbortSignal
}
```
它的第一个参数也可以是另一个 Request 对象，通过第二个参数对其进行修改。
第二个参数配置对象的各个属性的含义如下。
- `body`：HTTP 请求的数据体，必须是 Blob、BufferSource、FormData、String、URLSearchParams 类型之一。
- `cache`：请求的缓存模式。
- `credentials`：请求所用的凭证，可以设为 omit、same-origini、include。Chrome 47 之前，默认值为 same-origin；Chrome 47 之后，默认值为 include。
- `headers`：一个代表 HTTP 请求数据头的对象，类型为 Headers 对象实例。
- `integrity`：请求的资源的资源完整度验证值，比如`sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`。
- `method`：HTTP 方法，一般为`GET`、`POST`、`DELETE`，默认是`GET`。
- `mode`：请求模式，比如 cors、no-cors、navigate，默认为 cors。
- `redirect`：请求所用的模式，可以设为 error、follow、manual，默认为 follow。
- `referrer`：请求的来源，默认为 about:client。
下面是两个示例。
```javascript
// 示例一
const request = new Request('flowers.jpg');
// 示例二
const myInit = {
method: "GET",
headers: {
"Content-Type": "image/jpeg",
},
mode: "cors",
cache: "default",
};
const request = new Request('flowers.jpg', myInit);
```
`Request()`还有另一种语法，第一个参数是另一个 Request 对象，第二个参数还是一个配置对象。它返回一个新的 Request 对象，相当于对第一个参数 Request 对象进行修改。
```javascript
new Request(request: Request, [init: Object]): Request
@@ -39,26 +72,83 @@ new Request(request: Request, [init: Object]): Request
## 实例属性
- bodyUsed : Boolean readonly
- cache : String readonly。Will be one of: 'default', 'force-cache', 'no-cache', 'no-store', 'only-if-cached', 'reload'.
- credentials : String readonly。Will be one of: 'include', 'omit', 'same-origin'.
- destination : String readonly。Will be one of: '', 'audio', 'audioworklet', 'document', 'embed', 'font', 'frame', 'iframe', 'image', 'manifest', 'object', 'paintworklet', 'report', 'script', 'sharedworker', 'style', 'track', 'video', 'worker', 'xslt'.
- headers : Headers readonly。
- integrity : String readonly。
- isHistoryNavigation : Boolean readonly。
- isReloadNavigation : Boolean readonly。
- keepalive : Boolean readonly。
- method : String readonly。
- mode : String readonly。Will be one of: 'same-origin', 'no-cors', 'cors'.
- redirect : String readonly。
- referrer : String readonly。
- referrerPolicy : String readonly。
- signal : AbortSignal readonly。
- url : String readonly。
Request 实例对象的属性，大部分就是它的构造函数第二个参数配置对象的属性。
（1）`body`
`body`属性返回 HTTP 请求的数据体，它的值是一个 ReadableStream 对象或 null（`GET`或`HEAD`请求时没有数据体）。
```javascript
const request = new Request('/myEndpoint', {
method: "POST",
body: "Hello world",
});
request.body; // ReadableStream 对象
```
注意，Firefox 不支持该属性。
（2）`bodyused`
`bodyUsed`属性是一个布尔值，表示`body`是否已经被读取了。
（3）`cache`
`cache`属性是一个只读字符串，表示请求的缓存模式，可能的值有 default、force-cache、no-cache、no-store、only-if-cached、reload。
（4）`credentials`
`credentials`属性是一个只读字符串，表示跨域请求时是否携带其他域的 cookie。可能的值有 omit（不携带）、 include（携带）、same-origin（只携带同源 cookie）。
（5）`destination`
`destination`属性是一个字符串，表示请求内容的类型，可能的值有 ''、'audio'、'audioworklet'、'document'、'embed'、'font'、'frame'、'iframe'、'image'、'manifest'、'object'、'paintworklet'、 'report'、'script'、'sharedworker'、'style'、'track'、'video'、'worker'、'xslt' 等。
（6）`headers`
`headers`属性是一个只读的 Headers 实例对象，表示请求的数据头。
（7）`integrity`
`integrity`属性表示所请求资源的完整度的验证值。
（8）`method`
`method`属性是一个只读字符串，表示请求的方法（GET、POST 等）。
（9）`mode`
`mode`属性是一个只读字符串，用来验证是否可以有效地发出跨域请求，可能的值有 same-origin、no-cors、cors。
（10）`redirect`
`redirect`属性是一个只读字符串，表示重定向时的处理模式，可能的值有 follow、error、manual。
（11）`referrer`
`referrer`属性是一个只读字符串，表示请求的引荐 URL。
（12）`referrerPolicy`
`referrerPolicy`属性是一个只读字符串，决定了`referrer`属性是否要包含在请求里面的处理政策。
（13）`signal`
`signal`是一个只读属性，包含与当前请求相对应的中断信号 AbortSignal 对象。
（14）`url`
`url`是一个只读字符串，包含了当前请求的字符串。
```javascript
const myRequest = new Request('flowers.jpg');
const myURL = myRequest.url;
```
## 实例方法
### 取出数据体
### 取出数据体的方法
- arrayBuffer()：返回一个 Promise 对象，将 Request 的数据体作为 ArrayBuffer 对象返回。
- blob()：返回一个 Promise 对象，将 Request 的数据体作为 Blob 对象返回。
@@ -66,11 +156,22 @@ new Request(request: Request, [init: Object]): Request
- text()：返回一个 Promise 对象，将 Request 的数据体作为字符串返回。
- formData()：返回一个 Promise 对象，将 Request 的数据体作为表单数据 FormData 对象返回。
`.formData()`方法返回一个 Promise 对象，最终得到的是一个 FormData 表单对象，里面是用键值对表示的各种表单元素。
下面是`json()`方法的一个示例。
该方法很少使用，因为需要拦截发给服务器的请求的场景不多，一般用在 Service Worker。它需要拦截和处理网络请求，修改表单数据，然后将修改后的表单数据发送到服务器。
```javascript
const obj = { hello: "world" };
下面是 Service Worker 拦截表单提交请求，并使用`.formData()`方修改表单数据的例子。
const request = new Request("/myEndpoint", {
method: "POST",
body: JSON.stringify(obj),
});
request.json().then((data) => {
// 处理 JSON 数据
});
```
`.formData()`方法返回一个 Promise 对象，最终得到的是一个 FormData 表单对象，里面是用键值对表示的各种表单元素。该方法很少使用，因为需要拦截发给服务器的请求的场景不多，一般用在 Service Worker 拦截和处理网络请求，以修改表单数据，然后再发送到服务器。
```javascript
self.addEventListener('fetch', event => {
@@ -103,3 +204,8 @@ async function handleFormSubmission(request) {
`clone()`用来复制 HTTP 请求对象。
```javascript
const myRequest = new Request('flowers.jpg');
const newRequest = myRequest.clone();
```

8
docs/response.md
View File

@@ -20,15 +20,15 @@ new Response(body, options)
它带有两个参数，都是可选的。
第一个参数`body`是一个对象，代表服务器返回的数据体，必须是下面类型之一：ArrayBuffer、ArrayBufferView、Blob、FormData、ReadableStream、String、URLSearchParams。
第一个参数`body`代表服务器返回的数据体，必须是下面类型之一：ArrayBuffer、ArrayBufferView、Blob、FormData、ReadableStream、String、URLSearchParams。也就是说，它可以是对象或字符串。
第二个参数`init`是一个对象，代表服务器返回的数据头，类型描述如下。
```javascript
{
status : Number
statusText : String
headers : Object
status: Number
statusText: String
headers: Object
}
```