2.8 KiB
2.8 KiB
Purpose
定义 Bun 全栈应用运行时的 HTTP server、API 命名空间、健康检查、生产静态资源服务和 SPA fallback 行为。
Requirements
Requirement: Bun HTTP 运行时
系统 SHALL 运行一个 Bun HTTP server，由单个进程提供后端 API、健康检查、生产静态资源和 SPA fallback 行为。
Scenario: 启动运行时服务器
- WHEN server 进程成功启动
- THEN 它 SHALL 监听配置的 host 和 port，并记录实际 server URL
Scenario: 提供运行时配置
- WHEN 通过支持的运行时配置提供 host 或 port
- THEN server SHALL 使用该值，且不需要重新构建
Requirement: API 路由命名空间
系统 MUST 将 /api/* 保留给后端 API 路由。
Scenario: API 路由匹配
- WHEN 请求匹配已注册的
/api/*路由 - THEN Bun server SHALL 返回 API handler 的响应
Scenario: API 路由未命中
- WHEN 请求访问未注册的
/api/*路由 - THEN Bun server MUST 返回 JSON 404 响应，而不是前端 HTML 文档
Requirement: Demo API 端点
系统 SHALL 暴露 /api/demo 作为稳定 demo 端点，用于证明前后端集成可用。
Scenario: Demo API 成功响应
- WHEN 客户端请求
/api/demo - THEN Bun server SHALL 返回包含可读 message 和 runtime metadata 的 JSON 响应
Scenario: Demo API 内容类型
- WHEN 客户端请求
/api/demo - THEN Bun server SHALL 返回 JSON content type 的响应
Requirement: 健康检查端点
系统 SHALL 在前端 SPA fallback 之外暴露健康检查端点。
Scenario: 健康检查成功
- WHEN 客户端请求
/health - THEN Bun server SHALL 返回成功的、机器可读的健康检查响应
Requirement: 生产静态资源服务
系统 SHALL 在生产模式下由 Bun runtime 服务 Vite 生产资源。
Scenario: 请求构建后的资源
- WHEN 客户端请求构建后的前端资源，例如
/assets/app.js - THEN Bun server SHALL 返回该资源并带有适当的 content type
Scenario: 请求前端根路径
- WHEN 客户端请求
/ - THEN Bun server SHALL 返回前端入口 HTML 文档
Scenario: 生产 demo 页面调用 API
- WHEN 客户端从生产 Bun runtime 打开前端页面
- THEN demo 页面 SHALL 能够从同源调用
/api/demo并展示后端响应
Requirement: SPA fallback 行为
系统 SHALL 在生产环境中为非 API、非静态资源的前端路由返回前端入口 HTML 文档。
Scenario: 刷新前端路由
- WHEN 客户端请求前端路由，例如
/dashboard - THEN Bun server SHALL 返回前端入口 HTML 文档
Scenario: 保留 API 错误语义
- WHEN 客户端请求未知的
/api/*路由 - THEN Bun server MUST NOT 返回前端入口 HTML 文档