文档中心

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

开发指南

DWeb 框架开发指南，包括项目创建、开发流程、构建部署等。

项目创建

使用 CLI 创建项目

Code
# 交互式创建项目（会提示输入项目名称和配置选项）
deno run -A jsr:@dreamer/dweb/init

# 指定项目名称（跳过名称输入，直接使用提供的名称）
deno run -A jsr:@dreamer/dweb/init my-app

**创建过程说明：**

  1. 项目名称输入：如果未提供项目名称，会提示输入（只允许字母、数字、连字符和下划线）
  2. 应用模式选择：单应用模式（默认）- 适合简单的单页面应用或 API 服务；多应用模式 - 适合需要多个独立应用的场景（如前端 + 后端）
  3. Tailwind CSS 版本选择：V4（推荐）- 最新版本，性能更好；V3 - 稳定版本，兼容性更好
  4. 渲染模式选择：SSR（服务端渲染）- 所有页面在服务端渲染，SEO 友好；CSR（客户端渲染）- 所有页面在客户端渲染，交互性强；Hybrid（混合渲染）（默认）- 根据路由自动选择渲染方式

项目结构

创建的项目结构如下：

Code
my-app/
├── routes/              # 路由目录
│   ├── index.tsx        # 首页
│   ├── about.tsx        # 关于页面
│   └── api/             # API 路由（默认在 routes/api，可通过 apiDir 配置）
│       └── users.ts
├── components/          # 组件目录
├── assets/              # 静态资源
├── public/              # 公共文件
├── dweb.config.ts       # 配置文件
├── deno.json            # Deno 配置
└── main.ts              # 入口文件（可选）

入口文件 (main.ts)

**注意：main.ts 文件是可选的，不是必须的。** 框架可以通过 CLI 命令（deno task dev 或 deno task start）自动启动服务器，无需手动创建入口文件。

如果你需要自定义应用配置（如添加中间件、插件等），可以创建 main.ts 文件：

Code
// main.ts（可选）
import { cors, createApp, staticFiles } from "@dreamer/dweb";

const app = createApp();

// 配置中间件
app.use(cors({
  origin: "*",
  methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
  allowedHeaders: ["Content-Type", "Authorization"],
}));

// 配置静态文件服务
app.use(staticFiles({
  dir: "assets",
  prefix: "/assets",
  maxAge: 86400, // 缓存 1 天
}));

// 导出应用实例
export default app;

**使用说明：**

  • 如果存在 main.ts 文件，框架会自动加载并应用其中的配置
  • 如果不存在 main.ts 文件，框架会使用 dweb.config.ts 中的配置
  • main.ts 主要用于需要编程式配置的场景，如动态添加中间件或插件
  • 在多应用模式下，每个应用可以有自己的 main.ts 文件（位于应用目录下）

开发流程

启动开发服务器

**单应用模式**

Code
# 启动开发服务器（默认端口 3000）
deno task dev

# 或使用 CLI 命令
deno run -A src/cli.ts dev

# 指定端口（通过配置文件或环境变量）
# 在 dweb.config.ts 中配置：
# server: { port: 8080 }

**多应用模式**

Code
# 单应用模式
deno task dev

# 多应用模式
deno run -A src/cli.ts dev:app-name

**开发服务器特性：**

  • 自动热更新（HMR）：修改代码后自动重新加载
  • 自动路由扫描：自动发现 routes/ 目录下的路由文件
  • 自动加载中间件和插件：从 main.ts 或配置文件中加载
  • 错误提示：详细的错误信息和堆栈跟踪

热更新 (HMR)

开发服务器支持热更新，修改代码后自动刷新：

  • 服务端组件：自动重新加载
  • 客户端组件：通过 WebSocket 推送更新
  • 样式文件：自动重新编译

开发工具

代码格式化

Code
# 格式化所有文件
deno fmt

# 格式化指定文件或目录
deno fmt src/
deno fmt routes/index.tsx

# 检查格式（不修改文件）
deno fmt --check

代码检查

Code
# 检查所有文件
deno lint

# 检查指定文件或目录
deno lint src/
deno lint routes/

# 自动修复可修复的问题
deno lint --fix

类型检查

Code
# 检查所有 TypeScript 文件
deno check

# 检查指定文件或目录
deno check src/
deno check routes/

# 检查特定文件
deno check main.ts

构建

构建生产版本

Code
# 单应用模式
deno task build

# 多应用模式
deno run -A src/cli.ts build:app-name

构建配置

在 dweb.config.ts 中配置构建选项：

Code
export default defineConfig({
  build: {
    // 输出目录
    outDir: "dist",

    // 是否生成 source map（用于调试）
    sourcemap: true,

    // 是否压缩代码
    minify: true,

    // 目标 JavaScript 版本
    target: "es2022",
  },
});

部署

生产服务器

Code
# 单应用模式
deno task start

# 使用环境变量指定环境
DENO_ENV=production deno task start

# 多应用模式
deno run -A src/cli.ts start:app-name

**生产服务器特性：**

  • 优化的性能：代码已编译和压缩
  • 静态资源缓存：配置的缓存策略生效
  • 错误处理：生产环境友好的错误信息
  • 日志记录：可配置的日志级别和输出

Docker 部署

Code
# 构建镜像
docker build -t dweb-app .

# 运行容器
docker run -p 3000:3000 dweb-app

详细说明请参考 Docker 文档。

调试

使用 Deno 调试器

Deno 内置了调试器支持，可以使用 Chrome DevTools 进行调试。

**启动调试服务器**

Code
# 方式1：使用 CLI 命令（推荐）
deno run --inspect-brk -A src/cli.ts dev

# 方式2：指定调试端口
deno run --inspect=127.0.0.1:9229 -A src/cli.ts dev

**VS Code 调试配置**

创建 .vscode/launch.json 配置：

Code
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Deno: Debug",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "deno",
      "runtimeArgs": ["run", "--inspect-brk", "-A", "src/cli.ts", "dev"],
      "outputCapture": "std",
      "port": 9229
    }
  ]
}

测试

运行测试

Code
# 运行所有测试
deno test

# 运行特定测试文件
deno test tests/unit/server.test.ts

# 运行匹配模式的测试
deno test --filter "server"

# 带覆盖率
deno test --coverage=coverage/

# 查看覆盖率报告
deno coverage coverage/

编写测试示例

Code
// tests/unit/server.test.ts
import { assertEquals } from "@std/assert";
import { Server } from "@dreamer/dweb";

Deno.test("Server should start on specified port", async () => {
  const server = new Server();
  server.setHandler(async (req, res) => {
    res.text("Hello");
  });

  await server.start(3000);

  // 测试请求
  const response = await fetch("http://localhost:3000");
  const text = await response.text();

  assertEquals(text, "Hello");

  await server.close();
});

环境变量

开发环境

创建 .env.development：

Code
# .env.development
PORT=3000
DB_HOST=localhost
DB_NAME=mydb_dev

# .env.production
PORT=3000
DB_HOST=prod-db.example.com
DB_NAME=mydb

使用环境变量

Code
// dweb.config.ts
export default defineConfig({
  server: {
    port: parseInt(Deno.env.get("PORT") || "3000"),
  },
  database: {
    connection: {
      host: Deno.env.get("DB_HOST") || "localhost",
      database: Deno.env.get("DB_NAME") || "mydb",
    },
  },
});

常见问题

端口被占用

Code
# 查找占用端口的进程
lsof -i :3000

# 或修改配置
export default defineConfig({
  server: {
    port: 8080,
  },
});

模块导入错误

确保 deno.json 中配置了正确的导入映射：

Code
{
  "imports": {
    "@dreamer/dweb": "jsr:@dreamer/dweb@^1.0.0"
  }
}

最佳实践

  1. 使用 TypeScript：充分利用类型检查
  2. 代码格式化：保持代码风格一致
  3. 错误处理：使用 try-catch 处理异步错误
  4. 日志记录：使用框架提供的日志功能
  5. 环境变量：敏感信息使用环境变量
  6. 测试覆盖：编写单元测试和集成测试
  7. 性能监控：使用性能监控插件

相关文档