DiAL/openspec/specs/bun-fullstack-routing/spec.md

Purpose

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

Requirements

Requirement: 声明式路由注册

系统 SHALL 使用 Bun.serve 的 routes 对象以声明式方式注册所有 HTTP 路由，包括 HTML 页面路由和 API 端点路由。

Scenario: HTML 页面路由注册

• WHEN server 启动时
• THEN 系统 SHALL 通过 HTML import 将前端入口注册到 routes 对象的 "/*" 通配符路径

Scenario: API 端点路由注册

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

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 作为兜底，理论上不应被触发（所有路径都被 routes 通配符覆盖）。

Scenario: 未匹配的 API 路由

• WHEN 请求路径以 /api/ 开头但未在具体 API 路由中注册
• THEN /api/* 通配符 SHALL 返回 JSON 格式的 404 错误响应

Scenario: 未匹配的非 API 路由

• WHEN 请求路径不以 /api/ 开头且未在具体路由中注册
• THEN "/*": homepage 通配符 SHALL 返回前端入口 HTML 文档（带 HMR 注入）