DiAL/openspec/specs/bun-fullstack-routing/spec.md at 88f4119a4ec7315ae05a82fc528928b3b2683ed1

Files

lanyuanxiaoyao d6a77b2c6e feat: 迁移前端构建从 Bun fullstack 到 Vite

前端性能问题根因在于 Bun bundler 无法有效 code split、CSS
tree-shake 和产出优化的前端资源。经多轮 Bun 原生优化尝试
均无明显效果后，决定将前端构建迁回 Vite。

主要变更：

- 前端构建：从 Bun HTML import bundling 切换为 Vite build
  （Rolldown code splitting、vendor chunk、CSS 优化）
- 开发模式：从 Bun fullstack 单进程 HMR 切换为 Vite dev
  server + Bun API server 双进程（:5173 + :3000）
- 生产构建：三步流水线（Vite build → code generation →
  Bun compile），通过 `import with { type: "file" }` 嵌入前端资源
- 静态资源服务：从 Bun HTML import manifest 切换为自定义
  serveStaticAsset 函数，支持 SPA fallback 和正确的 Cache-Control
- Server 接口：BootstrapOptions 和 StartServerOptions 增加
  staticAssets? 可选参数
- 文档更新：DEVELOPMENT.md 和 README.md 反映新的开发模式，
  主 specs 同步 delta 变更

新增能力：
- static-asset-embedding: 构建时资源扫描与 code generation、
  运行时静态资源服务
- vite-frontend-bundling: Vite 构建配置、code splitting 策略、
  CSS 处理

2026-05-15 11:26:46 +08:00

2.4 KiB

Raw Blame History

Purpose

定义基于 Bun.serve routes 对象的全栈声明式路由注册、路径参数、HTTP method 声明和 fallback 行为。

Requirements

Requirement: 声明式路由注册

系统 SHALL 使用 Bun.serve 的 routes 对象以声明式方式注册 API 端点路由，非 API 请求由 fetch fallback 处理。

Scenario: API 端点路由注册

WHEN server 启动时
THEN 系统 SHALL 将所有 API 端点以 method handler 对象形式注册到 routes 对象

Scenario: 非 API 请求处理

WHEN 请求路径不匹配任何 routes 中注册的路由
THEN fetch fallback SHALL 将请求交给静态资源服务处理（production）或返回提示文本（development）

Requirement: 路径参数支持

系统 SHALL 使用 routes 对象的 :param 语法声明路径参数，替代手动 regex 匹配。

Scenario: 带路径参数的 API 路由

WHEN 客户端请求 /api/targets/123/history
THEN 系统 SHALL 通过 routes 中注册的 /api/targets/:id/history 匹配，并通过 req.params.id 获取参数值 "123"

Scenario: 路径参数类型

WHEN route handler 接收到路径参数
THEN 参数值 SHALL 为字符串类型，handler 负责进行类型转换和校验

Requirement: HTTP Method 声明

系统 SHALL 在 routes 对象中为每个 API 端点以 per-method handler 形式声明支持的 HTTP method；未匹配 method 的 API 请求 SHALL 落入 /api/* 通配符并返回 JSON 404。

Scenario: 单 method 端点

WHEN API 端点只支持 GET 方法
THEN 该端点 SHALL 以 { GET(req) { ... } } 形式注册

Scenario: 不支持的 method 请求

WHEN 客户端使用未声明的 method 请求 API 端点
THEN /api/* 通配符 SHALL 返回 JSON 格式的 404 错误响应

Requirement: Fetch Fallback 处理

系统 SHALL 使用 fetch handler 作为非 API 请求的入口，负责静态资源服务和 SPA fallback。

Scenario: Production 模式 fetch fallback

WHEN production 模式下请求未匹配 routes 中的 API 路由
THEN fetch handler SHALL 调用 serveStaticAsset 返回对应静态资源或 SPA fallback

Scenario: Development 模式 fetch fallback

WHEN development 模式下请求未匹配 routes 中的 API 路由
THEN fetch handler SHALL 返回提示文本，引导开发者通过 Vite dev server 访问前端

2.4 KiB Raw Blame History Unescape Escape