request-iframe 0.0.2 → 0.0.4

package/README.CN.md

@@ -34,6 +34,13 @@
   - [追踪模式](#追踪模式)
   - [多语言支持](#多语言支持)
 - [API 参考](#api-参考)
+- [React Hooks](#react-hooks)
+  - [useClient](#useclienttargetfnorref-options-deps)
+  - [useServer](#useserveroptions-deps)
+  - [useServerHandler](#useserverhandlerserver-path-handler-deps)
+  - [useServerHandlerMap](#useserverhandlermapserver-map-deps)
+  - [完整示例](#完整示例)
+  - [最佳实践](#最佳实践)
 - [错误处理](#错误处理)
 - [FAQ](#faq)
 - [开发](#开发)
@@ -67,7 +74,7 @@
 - ⏱️ **智能超时** - 三阶段超时（连接/同步/异步），自动识别长任务
 - 📦 **TypeScript** - 完整的类型定义和智能提示
 - 🔒 **消息隔离** - secretKey 机制避免多实例消息串线
-- 📁 **文件传输** - 支持 base64 编码的文件发送
+- 📁 **文件传输** - 支持文件通过流方式传输（Client→Server）
 - 🌊 **流式传输** - 支持大文件分块传输，支持异步迭代器
 - 🌍 **多语言** - 错误消息可自定义，便于国际化
 - ✅ **协议版本** - 内置版本控制，便于升级兼容
@@ -167,7 +174,7 @@ request-iframe 采用三阶段超时策略，智能适应不同场景：
 
 ```typescript
 client.send('/api/getData', data, {
-  ackTimeout: 500,        // 阶段1：等待 ACK 的超时时间（默认 500ms）
+  ackTimeout: 1000,       // 阶段1：等待 ACK 的超时时间（默认 1000ms）
   timeout: 5000,          // 阶段2：请求超时时间（默认 5s）
   asyncTimeout: 120000    // 阶段3：异步请求超时时间（默认 120s）
 });
@@ -207,7 +214,7 @@ client.send('/api/getData', data, {
 
 | 阶段 | 超时时间 | 场景 |
 |------|----------|------|
-| ackTimeout | 较短（500ms） | 快速检测 Server 是否在线，避免长时间等待不可达的 iframe |
+| ackTimeout | 较短（1000ms） | 快速检测 Server 是否在线，避免长时间等待不可达的 iframe。从 500ms 增加到 1000ms，以适应性能较差的环境或浏览器繁忙的场景 |
 | timeout | 中等（5s） | 适用于简单的同步处理，如读取数据、参数校验等 |
 | asyncTimeout | 较长（120s） | 适用于复杂异步操作，如文件处理、批量操作、第三方 API 调用等 |
 
@@ -245,7 +252,8 @@ client.send('/api/getData', data, {
 const client = requestIframeClient(iframe, { secretKey: 'main-app' });
 
 // 获取子应用的用户信息
-const userInfo = await client.send('/api/user/info', {});
+const userInfoResponse = await client.send('/api/user/info', {});
+console.log(userInfoResponse.data); // 用户信息数据
 
 // 通知子应用更新数据
 await client.send('/api/data/refresh', { timestamp: Date.now() });
@@ -289,7 +297,8 @@ server.on('/api/data', async (req, res) => {
 
 // 父页面（跨域）
 const client = requestIframeClient(iframe, { secretKey: 'data-api' });
-const data = await client.send('/api/data', {}); // 成功获取跨域数据
+const response = await client.send('/api/data', {});
+const data = response.data; // 成功获取跨域数据
 ```
 
 ### 文件预览和下载
@@ -311,8 +320,8 @@ server.on('/api/processFile', async (req, res) => {
 
 // 父页面：下载文件
 const response = await client.send('/api/processFile', { fileId: '123' });
-if (response.fileData) {
-  downloadFile(response.fileData);
+if (response.data instanceof File || response.data instanceof Blob) {
+  downloadFile(response.data);
 }
 ```
 
@@ -498,10 +507,12 @@ server.on('/api/logout', (req, res) => {
 await client.send('/api/login', { username: 'tom', password: '123' });
 
 // Client 端：后续请求 /api/getUserInfo（自动携带 authToken 和 userId）
-const userInfo = await client.send('/api/getUserInfo', {});
+const userInfoResponse = await client.send('/api/getUserInfo', {});
+const userInfo = userInfoResponse.data;
 
 // Client 端：请求根路径（只携带 userId，因为 authToken 的 path 是 /api）
-const rootData = await client.send('/other', {});
+const rootResponse = await client.send('/other', {});
+const rootData = rootResponse.data;
 ```
 
 #### Client Cookie 管理 API
@@ -576,22 +587,48 @@ server.on('/api/download', async (req, res) => {
 
 // Client 端接收
 const response = await client.send('/api/download', {});
-if (response.fileData) {
-  const { content, mimeType, fileName } = response.fileData;
+if (response.data instanceof File || response.data instanceof Blob) {
+  const file = response.data instanceof File ? response.data : null;
+  const fileName = file?.name || 'download';
   
-  // content 是 base64 编码的字符串
-  const binaryString = atob(content);
-  const blob = new Blob([binaryString], { type: mimeType });
-  
-  // 下载文件
-  const url = URL.createObjectURL(blob);
+  // 直接使用 File/Blob 下载文件
+  const url = URL.createObjectURL(response.data);
   const a = document.createElement('a');
   a.href = url;
-  a.download = fileName || 'download';
+  a.download = fileName;
   a.click();
+  URL.revokeObjectURL(url);
 }
 ```
 
+#### Client → Server（Client 向 Server 发送文件）
+
+Client 端发送文件**仅走流式**。使用 `sendFile()`（或直接 `send(path, file)`）；Server 端在 `autoResolve: true`（默认）时会把文件自动解析成 `File/Blob` 放到 `req.body`，当 `autoResolve: false` 时则通过 `req.stream` / `req.body` 暴露为 `IframeFileReadableStream`。
+
+```typescript
+// Client 端：发送文件（stream，autoResolve 默认 true）
+const file = new File(['Hello Upload'], 'upload.txt', { type: 'text/plain' });
+const response = await client.send('/api/upload', file);
+
+// 或显式使用 sendFile
+const blob = new Blob(['binary data'], { type: 'application/octet-stream' });
+const response2 = await client.sendFile('/api/upload', blob, {
+  fileName: 'data.bin',
+  mimeType: 'application/octet-stream',
+  autoResolve: true // 可选，默认 true：Server 在 req.body 里拿到 File/Blob
+});
+
+// Server 端：接收文件（autoResolve true → req.body 是 File/Blob）
+server.on('/api/upload', async (req, res) => {
+  const blob = req.body as Blob; // 如果 client 发送的是 File，这里也可能是 File
+  const text = await blob.text();
+  console.log('Received file content:', text);
+  res.send({ success: true, size: blob.size });
+});
+```
+
+**提示**：当 `client.send()` 的 `body` 是 `File/Blob` 时，会自动分发到 `client.sendFile()`（走流式）。`autoResolve` 为 true（默认）时 Server 拿到 `req.body`（File/Blob），为 false 时拿到 `req.stream` / `req.body`（`IframeFileReadableStream`）。
+
 ### 流式传输（Stream）
 
 对于大文件或需要分块传输的场景，可以使用流式传输：
@@ -601,7 +638,7 @@ import {
   IframeWritableStream, 
   IframeFileWritableStream,
   isIframeReadableStream,
-  isIframeFileStream 
+  isIframeFileReadableStream 
 } from 'request-iframe';
 
 // Server 端：使用迭代器发送数据流
@@ -685,7 +722,7 @@ if (isIframeReadableStream(response.stream)) {
 // Client 端：接收文件流
 const fileResponse = await client.send('/api/fileStream', {});
 
-if (isIframeFileStream(fileResponse.stream)) {
+if (isIframeFileReadableStream(fileResponse.stream)) {
   // 读取为 Blob
   const blob = await fileResponse.stream.readAsBlob();
   
@@ -707,9 +744,9 @@ if (isIframeFileStream(fileResponse.stream)) {
 | 类型 | 说明 |
 |------|------|
 | `IframeWritableStream` | 服务端可写流，用于发送普通数据 |
-| `IframeFileWritableStream` | 服务端文件可写流，自动处理 base64 编码 |
+| `IframeFileWritableStream` | 服务端文件可写流（文件流） |
 | `IframeReadableStream` | 客户端可读流，用于接收普通数据 |
-| `IframeFileReadableStream` | 客户端文件可读流，自动处理 base64 解码 |
+| `IframeFileReadableStream` | 客户端文件可读流（文件流） |
 
 **流选项：**
 
@@ -804,7 +841,7 @@ setMessages({
 | `target` | `HTMLIFrameElement \| Window` | 目标 iframe 元素或 window 对象 |
 | `options.secretKey` | `string` | 消息隔离标识（可选） |
 | `options.trace` | `boolean` | 是否开启追踪模式（可选） |
-| `options.ackTimeout` | `number` | 全局默认 ACK 确认超时（ms），默认 500 |
+| `options.ackTimeout` | `number` | 全局默认 ACK 确认超时（ms），默认 1000 |
 | `options.timeout` | `number` | 全局默认请求超时（ms），默认 5000 |
 | `options.asyncTimeout` | `number` | 全局默认异步超时（ms），默认 120000 |
 
@@ -837,7 +874,7 @@ await client.send('/api/longTask', {}, {
 |------|------|------|
 | `options.secretKey` | `string` | 消息隔离标识（可选） |
 | `options.trace` | `boolean` | 是否开启追踪模式（可选） |
-| `options.ackTimeout` | `number` | 等待客户端确认超时（ms），默认 5000 |
+| `options.ackTimeout` | `number` | 等待客户端确认超时（ms），默认 1000 |
 
 **返回值：** `RequestIframeServer`
 
@@ -845,15 +882,17 @@ await client.send('/api/longTask', {}, {
 
 #### client.send(path, body?, options?)
 
-发送请求。
+发送请求。会根据 body 类型自动分发到 `sendFile()` 或 `sendStream()`：
+- `File/Blob` → `sendFile()`
+- `IframeWritableStream` → `sendStream()`
 
 **参数：**
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
 | `path` | `string` | 请求路径 |
-| `body` | `object` | 请求数据（可选） |
-| `options.ackTimeout` | `number` | ACK 确认超时（ms），默认 500 |
+| `body` | `any` | 请求数据（可选）。可以是普通对象、File、Blob、或 IframeWritableStream；会自动分发：File/Blob → `sendFile()`，IframeWritableStream → `sendStream()` |
+| `options.ackTimeout` | `number` | ACK 确认超时（ms），默认 1000 |
 | `options.timeout` | `number` | 请求超时（ms），默认 5000 |
 | `options.asyncTimeout` | `number` | 异步超时（ms），默认 120000 |
 | `options.headers` | `object` | 请求 headers（可选） |
@@ -864,20 +903,78 @@ await client.send('/api/longTask', {}, {
 
 ```typescript
 interface Response<T = any> {
-  data: T;                    // 响应数据
+  data: T;                    // 响应数据（自动解析的文件流为 File/Blob）
   status: number;             // 状态码
   statusText: string;         // 状态文本
   requestId: string;          // 请求 ID
   headers?: Record<string, string | string[]>;  // 响应 headers（Set-Cookie 为数组）
-  fileData?: {                // 文件数据（如果有）
-    content: string;          // base64 编码内容
-    mimeType?: string;
-    fileName?: string;
-  };
   stream?: IIframeReadableStream<T>;  // 流响应（如果有）
 }
 ```
 
+**示例：**
+
+```typescript
+// 发送普通对象（自动 Content-Type: application/json）
+await client.send('/api/data', { name: 'test' });
+
+// 发送字符串（自动 Content-Type: text/plain）
+await client.send('/api/text', 'Hello');
+
+// 发送 File/Blob（自动分发到 sendFile）
+const file = new File(['content'], 'test.txt');
+await client.send('/api/upload', file);
+
+// 发送流（自动分发到 sendStream）
+const stream = new IframeWritableStream({ iterator: async function* () { yield 'data'; } });
+await client.send('/api/uploadStream', stream);
+```
+
+#### client.sendFile(path, content, options?)
+
+发送文件作为请求体（通过流传输；当 `autoResolve` 为 true 时，Server 在 `req.body` 中拿到 File/Blob）。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `path` | `string` | 请求路径 |
+| `content` | `string \| Blob \| File` | 文件内容 |
+| `options.mimeType` | `string` | MIME 类型（可选，优先使用 content.type） |
+| `options.fileName` | `string` | 文件名（可选） |
+| `options.autoResolve` | `boolean` | 为 true（默认）时 Server 在 `req.body` 中拿到 File/Blob；为 false 时 Server 在 `req.stream` / `req.body` 中拿到 `IframeFileReadableStream` |
+| `options.ackTimeout` | `number` | ACK 确认超时（ms），默认 1000 |
+| `options.timeout` | `number` | 请求超时（ms），默认 5000 |
+| `options.asyncTimeout` | `number` | 异步超时（ms），默认 120000 |
+| `options.headers` | `object` | 请求 headers（可选） |
+| `options.cookies` | `object` | 请求 cookies（可选） |
+| `options.requestId` | `string` | 自定义请求 ID（可选） |
+
+**返回值：** `Promise<Response>`
+
+**说明：** 文件通过流发送。`autoResolve` 为 true（默认）时 Server 收到 `req.body`（File/Blob）；为 false 时 Server 收到 `req.stream` / `req.body`（`IframeFileReadableStream`）。
+
+#### client.sendStream(path, stream, options?)
+
+发送流作为请求体（Server 端收到可读流）。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `path` | `string` | 请求路径 |
+| `stream` | `IframeWritableStream` | 要发送的可写流 |
+| `options.ackTimeout` | `number` | ACK 确认超时（ms），默认 1000 |
+| `options.timeout` | `number` | 请求超时（ms），默认 5000 |
+| `options.asyncTimeout` | `number` | 异步超时（ms），默认 120000 |
+| `options.headers` | `object` | 请求 headers（可选） |
+| `options.cookies` | `object` | 请求 cookies（可选） |
+| `options.requestId` | `string` | 自定义请求 ID（可选） |
+
+**返回值：** `Promise<Response>`
+
+**说明：** Server 端的流在 `req.stream`（`IIframeReadableStream`）中，可用 `for await (const chunk of req.stream)` 迭代读取。
+
 #### client.isConnect()
 
 检测 Server 是否可达。
@@ -950,6 +1047,39 @@ client.interceptors.response.use(onFulfilled, onRejected?);
 type ServerHandler = (req: ServerRequest, res: ServerResponse) => any | Promise<any>;
 ```
 
+**ServerRequest 接口：**
+
+```typescript
+interface ServerRequest {
+  body: any;                          // 请求 body（普通数据；或 autoResolve=true 时的 File/Blob）
+  stream?: IIframeReadableStream;     // 请求流（sendStream；或 sendFile 且 autoResolve=false）
+  headers: Record<string, string>;    // 请求 headers
+  cookies: Record<string, string>;    // 请求 cookies
+  path: string;                       // 请求路径（实际请求路径）
+  params: Record<string, string>;     // 路由参数（由 server.on 注册的路径模式解析得出，如 /api/users/:id）
+  requestId: string;                  // 请求 ID
+  origin: string;                     // 来源 origin
+  source: Window;                     // 来源 window
+  res: ServerResponse;                // 关联的 Response 对象
+}
+```
+
+**说明：**
+- Client 通过 `sendFile()`（或 `send(path, file)`）发送文件时：文件通过流传输；`autoResolve` 为 true（默认）时 Server 在 `req.body` 中拿到 File/Blob；为 false 时在 `req.stream` / `req.body` 中拿到 `IframeFileReadableStream`。
+- Client 通过 `sendStream()` 发送流时：Server 在 `req.stream` 中拿到 `IIframeReadableStream`，可用 `for await` 迭代读取。
+- **路径参数（类似 Express）**：支持 `/api/users/:id` 形式的路由参数，解析结果在 `req.params` 中。
+
+```typescript
+server.on('/api/users/:id', (req, res) => {
+  res.send({ userId: req.params.id });
+});
+
+server.on('/api/users/:userId/posts/:postId', (req, res) => {
+  const { userId, postId } = req.params;
+  res.send({ userId, postId });
+});
+```
+
 #### server.off(path)
 
 移除路由处理器。
@@ -984,14 +1114,271 @@ server.use(['/a', '/b'], (req, res, next) => { ... });
 
 销毁 Server 实例，移除所有监听器。
 
-### ServerRequest 对象
+---
+
+## React Hooks
+
+request-iframe 提供了 React hooks，方便在 React 应用中使用。从 `request-iframe/react` 导入 hooks：
+
+```typescript
+import { useClient, useServer, useServerHandler, useServerHandlerMap } from 'request-iframe/react';
+```
+
+### useClient(targetFnOrRef, options?, deps?)
+
+用于使用 request-iframe client 的 React hook。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `targetFnOrRef` | `(() => HTMLIFrameElement \| Window \| null) \| RefObject<HTMLIFrameElement \| Window>` | 返回 iframe 元素或 Window 对象的函数，或 React ref 对象 |
+| `options` | `RequestIframeClientOptions` | Client 选项（可选） |
+| `deps` | `readonly unknown[]` | 依赖数组（可选，当依赖变化时重新创建 client） |
+
+**返回值：** `RequestIframeClient | null`
+
+**示例：**
+
+```tsx
+import { useClient } from 'request-iframe/react';
+import { useRef } from 'react';
+
+const MyComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(iframeRef, { secretKey: 'my-app' });
+
+  const handleClick = async () => {
+    if (client) {
+      const response = await client.send('/api/data', { id: 1 });
+      console.log(response.data);
+    }
+  };
+
+  return (
+    <div>
+      <iframe ref={iframeRef} src="/iframe.html" />
+      <button onClick={handleClick}>发送请求</button>
+    </div>
+  );
+};
+```
+
+**使用函数而不是 ref：**
+
+```tsx
+const MyComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(() => iframeRef.current, { secretKey: 'my-app' });
+  // ...
+};
+```
+
+### useServer(options?, deps?)
+
+用于使用 request-iframe server 的 React hook。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `options` | `RequestIframeServerOptions` | Server 选项（可选） |
+| `deps` | `readonly unknown[]` | 依赖数组（可选，当依赖变化时重新创建 server） |
+
+**返回值：** `RequestIframeServer | null`
+
+**示例：**
+
+```tsx
+import { useServer } from 'request-iframe/react';
+
+const MyComponent = () => {
+  const server = useServer({ secretKey: 'my-app' });
+
+  useEffect(() => {
+    if (!server) return;
+
+    const off = server.on('/api/data', (req, res) => {
+      res.send({ data: 'Hello' });
+    });
+
+    return off; // 组件卸载时清理
+  }, [server]);
+
+  return <div>Server 组件</div>;
+};
+```
+
+### useServerHandler(server, path, handler, deps?)
+
+用于注册单个 server handler 的 React hook，自动处理清理和闭包问题。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `server` | `RequestIframeServer \| null` | Server 实例（来自 `useServer`） |
+| `path` | `string` | 路由路径 |
+| `handler` | `ServerHandler` | 处理函数 |
+| `deps` | `readonly unknown[]` | 依赖数组（可选，当依赖变化时重新注册） |
+
+**示例：**
+
+```tsx
+import { useServer, useServerHandler } from 'request-iframe/react';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const server = useServer();
+  const [userId, setUserId] = useState(1);
+
+  // Handler 自动使用最新的 userId 值
+  useServerHandler(server, '/api/user', (req, res) => {
+    res.send({ userId, data: 'Hello' });
+  }, [userId]); // 当 userId 变化时重新注册
+
+  return <div>Server 组件</div>;
+};
+```
+
+**关键特性：**
+- 自动处理闭包问题 - 始终使用依赖项的最新值
+- 组件卸载或依赖变化时自动取消注册 handler
+- 无需手动管理 handler 的注册/清理
+
+### useServerHandlerMap(server, map, deps?)
+
+用于批量注册多个 server handlers 的 React hook，自动处理清理。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `server` | `RequestIframeServer \| null` | Server 实例（来自 `useServer`） |
+| `map` | `Record<string, ServerHandler>` | 路由路径和处理函数的映射 |
+| `deps` | `readonly unknown[]` | 依赖数组（可选，当依赖变化时重新注册） |
+
+**示例：**
+
+```tsx
+import { useServer, useServerHandlerMap } from 'request-iframe/react';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const server = useServer();
+  const [userId, setUserId] = useState(1);
+
+  // 一次性注册多个 handlers
+  useServerHandlerMap(server, {
+    '/api/user': (req, res) => {
+      res.send({ userId, data: '用户数据' });
+    },
+    '/api/posts': (req, res) => {
+      res.send({ userId, data: '文章数据' });
+    }
+  }, [userId]); // 当 userId 变化时重新注册所有 handlers
+
+  return <div>Server 组件</div>;
+};
+```
+
+**关键特性：**
+- 批量注册多个 handlers
+- 自动处理闭包问题 - 始终使用依赖项的最新值
+- 组件卸载或依赖变化时自动取消注册所有 handlers
+- 高效 - 仅在 map 的键变化时重新注册
+
+### 完整示例
+
+以下是一个完整的示例，展示如何在真实应用中使用 React hooks：
+
+```tsx
+import { useClient, useServer, useServerHandler } from 'request-iframe/react';
+import { useRef, useState } from 'react';
+
+// 父组件（Client）
+const ParentComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(iframeRef, { secretKey: 'my-app' });
+  const [data, setData] = useState(null);
+
+  const fetchData = async () => {
+    if (!client) return;
+    
+    try {
+      const response = await client.send('/api/data', { id: 1 });
+      setData(response.data);
+    } catch (error) {
+      console.error('请求失败:', error);
+    }
+  };
+
+  return (
+    <div>
+      <iframe ref={iframeRef} src="/iframe.html" />
+      <button onClick={fetchData}>获取数据</button>
+      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+    </div>
+  );
+};
+
+// Iframe 组件（Server）
+const IframeComponent = () => {
+  const server = useServer({ secretKey: 'my-app' });
+  const [userId, setUserId] = useState(1);
+
+  // 注册 handler，自动清理
+  useServerHandler(server, '/api/data', async (req, res) => {
+    // Handler 始终使用最新的 userId 值
+    const userData = await fetchUserData(userId);
+    res.send(userData);
+  }, [userId]);
+
+  return (
+    <div>
+      <p>用户 ID: {userId}</p>
+      <button onClick={() => setUserId(userId + 1)}>增加</button>
+    </div>
+  );
+};
+```
+
+### 最佳实践
+
+1. **始终检查 null**：Client 和 server hooks 在初始时或目标不可用时可能返回 `null`：
+   ```tsx
+   const client = useClient(iframeRef);
+   if (!client) return null; // 处理 null 情况
+   ```
+
+2. **使用依赖数组**：向 hooks 传递依赖项，确保 handlers 使用最新值：
+   ```tsx
+   useServerHandler(server, '/api/data', (req, res) => {
+     res.send({ userId }); // 始终使用最新的 userId
+   }, [userId]); // 当 userId 变化时重新注册
+   ```
+
+3. **自动清理**：Hooks 在组件卸载时自动清理，但你也可以手动取消注册：
+   ```tsx
+   useEffect(() => {
+     if (!server) return;
+     const off = server.on('/api/data', handler);
+     return off; // 手动清理（可选，hooks 会自动处理）
+   }, [server]);
+   ```
+
+---
+
+## 错误处理
 
 ```typescript
 interface ServerRequest {
-  body: any;                          // 请求 body
+  body: any;                          // 请求 body（普通数据；或 autoResolve=true 时的 File/Blob）
+  stream?: IIframeReadableStream;     // 请求流（sendStream；或 sendFile 且 autoResolve=false）
   headers: Record<string, string>;    // 请求 headers
   cookies: Record<string, string>;    // 请求 cookies
-  path: string;                       // 请求路径
+  path: string;                       // 请求路径（实际请求路径）
+  params: Record<string, string>;     // 路由参数（由 server.on 注册的路径模式解析得出，如 /api/users/:id）
   requestId: string;                  // 请求 ID
   origin: string;                     // 来源 origin
   source: Window;                     // 来源 window
@@ -999,6 +1386,22 @@ interface ServerRequest {
 }
 ```
 
+**路径参数（类似 Express）**：
+
+支持使用 `:param` 形式声明路由参数，解析结果在 `req.params` 中。
+
+```typescript
+server.on('/api/users/:id', (req, res) => {
+  // 请求 /api/users/123 时：req.params.id === '123'
+  res.send({ userId: req.params.id });
+});
+
+server.on('/api/users/:userId/posts/:postId', (req, res) => {
+  const { userId, postId } = req.params;
+  res.send({ userId, postId });
+});
+```
+
 ### ServerResponse 对象
 
 ```typescript