文档中心

探索 DWeb 框架的无限可能，构建下一代高性能 Web 应用

RouteHandler (路由处理器)

DWeb 框架的路由处理器，负责处理页面路由、API 路由、模块请求等。

功能概述

Code
RouteHandler 是框架的核心组件，负责：

- 处理页面路由（SSR/CSR/Hybrid）
- 处理 API 路由
- 处理模块请求（/__modules/）
- 处理 GraphQL 请求
- 资源预加载（Prefetch）
- 热模块替换（HMR）支持

基本使用

Code
// RouteHandler 通常由 Application 类内部使用
import { Application } from "@dreamer/dweb";

const app = new Application("dweb.config.ts");
await app.initialize();
await app.start();

// RouteHandler 会自动处理所有请求

**注意：** `RouteHandler` 通常由 `Application` 类内部使用，不需要手动创建。如果需要自定义路由处理逻辑，可以通过中间件或插件来实现。

处理流程

页面路由处理

Code
页面路由处理流程：

1. 匹配路由
2. 加载页面模块
3. 执行 load 函数（数据加载）
4. 渲染页面组件（SSR）或返回客户端脚本（CSR）
5. 注入 HMR 脚本（开发模式）

**⚠️ 重要提示：**

⚠️ 重要提示： 页面组件和布局组件不能是异步函数（async function）。 如果需要进行异步操作，请在组件内部使用 useEffect 钩子处理， 或者使用 load 函数在服务端获取数据。 详细说明请参考路由约定文件文档。

API 路由处理

Code
API 路由处理流程：

1. 匹配 API 路由
2. 加载 API 模块
3. 创建 ApiContext（包含 req, res, app, cookie, session, params, query, routePath, url）
4. 根据 HTTP 方法或方法名调用对应处理函数
5. 返回响应

资源预加载

资源预加载（Prefetch）可以在用户访问前提前加载路由组件，提升用户体验。

Code
// 在 dweb.config.ts 中配置
export default {
  prefetch: {
    enabled: true,
    routes: ["*", "!/docs/*"],  // 预加载所有路由，但排除 docs 下的页面
    mode: "batch",              // 批量模式（一次请求，服务端打包返回所有匹配路由的数据）
    loading: false,             // 是否在预加载时显示全屏加载状态
  },
};

**配置说明：**

**`routes`**：支持通配符模式（`*`）和否定模式（`!`）

**`mode`**：`single`（逐个请求）或 `batch`（批量请求，默认）

**`loading`**：是否在预加载时显示全屏加载状态

API 参考

构造函数

Code
constructor(
  router: Router,
  cookieManager?: CookieManager,
  sessionManager?: SessionManager,
  config?: AppConfig,
  graphqlServer?: GraphQLServer
)

主要方法

handle(req, res)

处理请求的统一入口。

Code
await routeHandler.handle(req, res);

handlePageRoute(routeInfo, req, res)

处理页面路由。

Code
await routeHandler.handlePageRoute(routeInfo, req, res);

handleApiRoute(routeInfo, req, res)

处理 API 路由。

Code
await routeHandler.handleApiRoute(routeInfo, req, res);

handleModuleRequest(req, res)

处理模块请求（`/__modules/`）。

Code
await routeHandler.handleModuleRequest(req, res);

相关文档