@doubao-apps/create 0.0.29 → 0.0.30

package/dist/template-starter/references/reference/open-api/07-/347/275/221/347/273/234.md

@@ -0,0 +1,468 @@
+# Open API: 网络
+
+网络请求与 WebSocket。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [request](#request) | 发起网络请求。<br><br>返回 statusCode、header 和 data。 |
+| [connectSocket](#connectsocket) | 创建一个 WebSocket 连接，并返回可操作该连接的 SocketTask。<br><br>- 返回 SocketTask 不代表连接已经成功，连接成功以 onOpen 为准。 - send 必须接收对象参数，并把要发送的内容放在 data 字段中。 - 如果 protocols 非空，需要服务端支持并返回匹配的子协议。 - 多次调用会创建多条连接，旧连接不会自动关闭；不再使用时应主动调用 close。 - 连接失败、发送失败或关闭失败会通过 SocketTask.onError 通知。 |
+
+## API 详情
+
+<a id="request"></a>
+### request()
+
+> **request**(`params`): `Promise`\<[`RequestResponse`](#requestresponse)\>
+
+发起网络请求。
+
+#### Parameters
+
+• **params**: [`RequestParams`](#requestparams)
+
+请求参数，字段见 [RequestParams](#requestparams)。
+
+#### Returns
+
+`Promise`\<[`RequestResponse`](#requestresponse)\>
+
+返回一个 Promise，解析为 [RequestResponse](#requestresponse)。
+
+#### Remarks
+
+返回 statusCode、header 和 data。
+
+#### Example
+
+```typescript
+import { request } from '@doubao-apps/framework/api';
+
+const result = await request({
+  url: 'https://postman-echo.com/post',
+  method: 'POST',
+  dataType: 'json',
+  header: { 'content-type': 'application/json' },
+  data: { hello: 'world' }
+});
+
+console.log(result.statusCode, result.data);
+```
+
+<a id="connectsocket"></a>
+### connectSocket()
+
+> **connectSocket**(`params`): [`SocketTask`](#sockettask)
+
+创建一个 WebSocket 连接，并返回可操作该连接的 [SocketTask](#sockettask)。
+
+该 API 会同步返回 `SocketTask`，但连接创建本身是异步过程。调用方应先在返回的
+`SocketTask` 上注册事件回调，再等待 `onOpen` 表示连接可用。后续发送消息使用
+`SocketTask.send`，关闭连接使用 `SocketTask.close`。
+
+#### Parameters
+
+• **params**: [`ConnectSocketParams`](#connectsocketparams)
+
+创建连接所需参数，字段见 [ConnectSocketParams](#connectsocketparams)。
+
+#### Returns
+
+[`SocketTask`](#sockettask)
+
+当前 WebSocket 连接对应的 [SocketTask](#sockettask)。
+
+#### Remarks
+
+- 返回 `SocketTask` 不代表连接已经成功，连接成功以 `onOpen` 为准。
+- `send` 必须接收对象参数，并把要发送的内容放在 `data` 字段中。
+- 如果 `protocols` 非空，需要服务端支持并返回匹配的子协议。
+- 多次调用会创建多条连接，旧连接不会自动关闭；不再使用时应主动调用 `close`。
+- 连接失败、发送失败或关闭失败会通过 `SocketTask.onError` 通知。
+
+#### Example
+
+```typescript
+import { connectSocket } from '@doubao-apps/framework/api';
+
+const socketTask = connectSocket({
+  url: 'wss://example.com/socket',
+  header: { authorization: 'Bearer token' },
+  protocols: ['chat.v1']
+});
+
+socketTask.onOpen(() => {
+  socketTask.send({ data: 'hello' });
+});
+
+socketTask.onMessage((event) => {
+  console.log(event.data);
+});
+
+socketTask.onClose((event) => {
+  console.log(event.code, event.reason);
+});
+
+socketTask.onError((event) => {
+  console.error(event.errMsg);
+});
+```
+
+## 相关类型
+
+<a id="requestparams"></a>
+### RequestParams
+
+网络请求参数。
+
+#### Properties
+
+##### data?
+
+> `optional` **data**: `string` \| `Record`\<`string`, `any`\> \| `ArrayBuffer`
+
+请求体数据。
+
+传给服务器的数据最终会是 `String` 或 `ArrayBuffer`：
+- 若 `data` 是 `string` 或 `ArrayBuffer`，直接使用；
+- 若 `header['content-type']` 是 `application/x-www-form-urlencoded`，会被编码为 query string，例如：`encodeURIComponent(k)=encodeURIComponent(v)`；
+- 若 `header['content-type']` 是 `application/json`，会执行 JSON 序列化；
+- 若 `data` 是普通对象且未命中上述类型，也会执行 JSON 序列化；
+- 其他类型会调用 `toString()`
+
+##### dataType?
+
+> `optional` **dataType**: `"string"` \| `"json"`
+
+期望返回的数据格式。
+- `json`: 尝试按 JSON 解析；
+- `string`: 按字符串返回。
+
+###### Default
+
+```ts
+"json"
+```
+
+##### header?
+
+> `optional` **header**: `Record`\<`string`, `string`\>
+
+请求 Header。
+
+###### Default
+
+```ts
+{"content-type": "application/json"}
+```
+
+##### method?
+
+> `optional` **method**: [`RequestMethod`](#requestmethod)
+
+请求方法。
+
+###### Default
+
+```ts
+"GET"
+```
+
+##### url
+
+> **url**: `string`
+
+请求地址，需为完整的 **HTTPS** URL。
+
+<a id="requestresponse"></a>
+### RequestResponse
+
+网络请求返回结果。
+
+#### Properties
+
+##### data?
+
+> `optional` **data**: `string` \| `Record`\<`string`, `any`\> \| `ArrayBuffer`
+
+响应数据，类型由 `dataType` 决定。
+
+##### header
+
+> **header**: `Record`\<`string`, `string`\>
+
+HTTP 响应头。
+
+##### statusCode
+
+> **statusCode**: `number`
+
+HTTP 状态码。
+
+<a id="requestmethod"></a>
+### RequestMethod
+
+> **RequestMethod**: `"GET"` \| `"POST"` \| `"PUT"` \| `"DELETE"` \| `"HEAD"` \| `"OPTIONS"` \| `"TRACE"` \| `"CONNECT"`
+
+<a id="connectsocketparams"></a>
+### ConnectSocketParams
+
+创建 WebSocket 连接的参数。
+
+`connectSocket` 会把这些参数透传给宿主侧创建连接。连接创建请求发出后，
+调用方会立即拿到一个 [SocketTask](#sockettask)，后续连接成功、失败、收到消息和关闭状态
+都通过 `SocketTask` 上注册的事件回调通知。
+
+#### Remarks
+
+- `url` 应填写完整的 WebSocket 地址。线上环境通常要求使用 `wss://` 协议，并由宿主侧按当前应用配置校验合法域名和证书。
+- `header` 用于补充握手请求头，`referer` 等由宿主管控的字段不会被业务代码覆盖。
+- `protocols` 非空时，服务端需要在握手响应中选择并返回匹配的子协议，否则连接可能失败。
+- 同一个页面多次调用会创建多个独立连接，已创建的旧连接不会因为新连接自动关闭。
+
+#### Properties
+
+##### header?
+
+> `optional` **header**: `Record`\<`string`, `string`\>
+
+WebSocket 握手阶段携带的 HTTP Header。
+
+适合放置业务自定义 Header，例如鉴权 token、trace id、客户端能力标识等。
+`referer` 由宿主侧统一生成和管理，不应依赖该字段被业务传入值覆盖。
+
+##### protocols?
+
+> `optional` **protocols**: `string`[]
+
+WebSocket 子协议数组。
+
+会作为握手请求中的 `Sec-WebSocket-Protocol` 候选值传给服务端。
+如果传入非空数组，服务端需要选择其中一个协议并在握手响应中返回；
+服务端不支持或不返回匹配协议时，连接可能被宿主判定为创建失败。
+
+##### url
+
+> **url**: `string`
+
+WebSocket 连接地址。
+
+需要包含协议、域名、路径和可选 query，例如 `wss://example.com/socket?room=1`。
+如果地址为空或不是字符串，本 API 会返回 `readyState` 为 `undefined` 的 [SocketTask](#sockettask)，
+并异步触发 `onError`。
+
+<a id="sockettask"></a>
+<a id="sockettaskcloseparams"></a>
+<a id="send"></a>
+<a id="sockettasksendparams"></a>
+<a id="close-1"></a>
+### SocketTask
+
+通过 [connectSocket](#connectsocket) 获取的 WebSocket 任务实例。
+
+`SocketTask` 表示单条 WebSocket 连接的控制对象。它负责发送数据、关闭连接，
+并通过事件回调接收连接状态、服务端消息和错误通知。`connectSocket` 返回时连接
+仍可能处于创建中，调用方应先注册 `onOpen`、`onError`、`onClose`、`onMessage`
+等回调，再根据 `onOpen` 事件发送业务数据。
+
+#### Methods
+
+##### close()
+
+> **close**(`params`?): `void`
+
+关闭 WebSocket 连接。
+
+调用后会尝试向宿主侧发起关闭动作，并把 `readyState` 置为 `SocketTask.CLOSING`。
+最终关闭完成时触发 `onClose`；关闭动作失败时触发 `onError`。
+
+###### Parameters
+
+• **params?**: [`SocketTaskCloseParams`](#sockettaskcloseparams)
+
+###### Returns
+
+`void`
+
+##### onClose()
+
+> **onClose**(`callback`): `void`
+
+监听 WebSocket 与服务器连接断开的事件。
+
+主动关闭、服务端关闭、宿主侧回收连接都可能触发该回调。
+回调触发后当前任务会从内部连接表移除。
+
+###### Parameters
+
+• **callback**
+
+###### Returns
+
+`void`
+
+##### onError()
+
+> **onError**(`callback`): `void`
+
+监听 WebSocket 发生错误的事件。
+
+连接创建、发送、关闭或底层通道出现异常时触发。
+该回调只表示发生错误，不等同于连接一定已经关闭；是否关闭应结合 `readyState`
+或后续 `onClose` 事件判断。
+
+###### Parameters
+
+• **callback**
+
+###### Returns
+
+`void`
+
+##### onMessage()
+
+> **onMessage**(`callback`): `void`
+
+监听 WebSocket 接收到服务器发送信息的事件。
+
+服务端每下发一条消息都会触发一次回调。消息内容通过 `event.data` 返回，
+类型可能是 `string` 或 `ArrayBuffer`。
+
+###### Parameters
+
+• **callback**
+
+###### Returns
+
+`void`
+
+##### onOpen()
+
+> **onOpen**(`callback`): `void`
+
+监听 WebSocket 连接服务器成功的事件。
+
+可以注册多个回调。连接成功后触发回调，并携带握手响应 Header、协议类型等信息。
+通常应在该回调中或之后调用 [SocketTask.send](#send)。
+
+###### Parameters
+
+• **callback**
+
+###### Returns
+
+`void`
+
+##### send()
+
+> **send**(`params`): `void`
+
+通过 WebSocket 连接发送数据。
+
+该方法只发起发送动作，不返回发送结果。建议在 `readyState === SocketTask.OPEN`
+或收到 `onOpen` 事件后调用；如果连接未就绪、数据编码失败或宿主侧发送失败，
+会触发 `onError`。
+
+###### Parameters
+
+• **params**: [`SocketTaskSendParams`](#sockettasksendparams)
+
+###### Returns
+
+`void`
+
+#### Properties
+
+##### CLOSED
+
+> `readonly` **CLOSED**: `3`
+
+表示 Socket 连接已关闭。
+
+进入该状态后，该任务不会再收到新的消息，也不应继续调用 `send`。
+
+##### CLOSING
+
+> `readonly` **CLOSING**: `2`
+
+表示 Socket 连接关闭中。
+
+调用 [SocketTask.close](#close-1) 后、本地等待宿主侧完成关闭流程时通常处于该状态。
+
+##### CONNECTING
+
+> `readonly` **CONNECTING**: `0`
+
+表示 Socket 正在连接。
+
+`connectSocket` 刚返回且宿主尚未完成握手时通常处于该状态。
+
+##### OPEN
+
+> `readonly` **OPEN**: `1`
+
+表示 Socket 连接已经打开。
+
+进入该状态后可以调用 [SocketTask.send](#send) 发送数据。
+
+##### readyState
+
+> `readonly` **readyState**: `undefined` \| `number`
+
+当前 Socket 连接状态 code。
+
+可与 `CONNECTING`、`OPEN`、`CLOSING`、`CLOSED` 常量比较。
+如果因为参数错误等原因导致连接请求没有被宿主成功创建，则为 `undefined`。
+
+<a id="sockettaskcloseparams"></a>
+### SocketTaskCloseParams
+
+[SocketTask.close](#close-1) 的参数。
+
+`close` 用于主动关闭当前 WebSocket 连接。调用后 `readyState` 会先进入
+`SocketTask.CLOSING`，最终关闭结果通过 `onClose` 或 `onError` 回调通知。
+
+#### Properties
+
+##### code?
+
+> `optional` **code**: `number`
+
+关闭连接状态码。
+
+不传时由宿主侧按正常关闭处理，通常等价于 `1000`。
+常见值包括：
+- `1000`: 正常关闭；
+- `1001`: 因页面进入后台、宿主回收连接等原因关闭。
+
+##### reason?
+
+> `optional` **reason**: `string`
+
+连接被关闭的原因。
+
+该字段会随关闭帧传递给服务端，是否被服务端记录或回传取决于服务端实现。
+
+<a id="sockettasksendparams"></a>
+### SocketTaskSendParams
+
+[SocketTask.send](#send) 的参数。
+
+`send` 只负责向已打开的 WebSocket 连接写入一条消息，不返回 Promise。
+发送失败、连接未就绪或底层通道异常时，会通过同一个 `SocketTask` 的 `onError` 回调通知。
+
+#### Properties
+
+##### data
+
+> **data**: `string` \| `ArrayBuffer`
+
+需要发送给服务端的数据。
+
+- 传入 `string` 时按文本消息发送；
+- 传入 `ArrayBuffer` 时按二进制消息发送，内部会编码后交给宿主侧处理。
+
+建议只在 `onOpen` 回调触发后调用 `send`，此时 `readyState` 通常为 `SocketTask.OPEN`。