Gateway Checker

基于 Bun + TypeScript 的前后端一体化 demo。开发期使用 Vite + React 提供前端 HMR，后端由 Bun 提供 API；生产期先构建前端静态资源，再将前端资源和 Bun 后端打包为单个 executable。

项目结构

src/
  server/       Bun 后端运行时、API、静态资源 fallback
  shared/       前后端共享 TypeScript 类型
  web/          Vite + React 前端 demo
scripts/        开发、构建和 smoke test 脚本
tests/          Bun test 测试
openspec/       OpenSpec 变更与规格文档

开发命令

bun install
bun run dev

bun run dev 会同时启动：

• Bun 后端：默认 http://127.0.0.1:3000
• Vite 前端：默认 http://127.0.0.1:5173

开发期请打开 Vite 前端地址。前端通过相对路径 /api/demo 调用后端，Vite 会把 /api/* 代理到 Bun 后端，因此浏览器不需要 CORS 配置。

也可以分别运行：

bun run dev:server
bun run dev:web

Demo 验证

开发期打开 http://127.0.0.1:5173，页面应显示 /api/demo 返回的后端 message、Bun 版本、平台和响应时间。

直接验证 API：

curl http://127.0.0.1:3000/api/demo
curl http://127.0.0.1:3000/health

构建 executable

bun run build

构建流程：

• 运行 vite build，输出前端资源到 dist/web
• 生成临时 .build/static-assets.ts，用 Bun file import 嵌入 Vite 产物
• 运行 Bun.build({ compile })，输出 dist/gateway-checker

运行 executable：

./dist/gateway-checker

生产期默认访问 http://127.0.0.1:3000。同一个 executable 会服务 /api/demo、/health、/assets/* 和前端 SPA fallback。

运行参数

默认配置：

• HOST=127.0.0.1
• PORT=3000

可以通过环境变量或 CLI 参数覆盖：

PORT=4000 ./dist/gateway-checker
./dist/gateway-checker --host 0.0.0.0 --port 4000

测试

bun run typecheck
bun test
bun run build
bun run test:smoke

test:smoke 会启动生成的 executable，并检查 /api/demo、/health、前端根路径、静态资源和 SPA fallback。

前后端边界

前端只通过 HTTP 调用后端，默认 API 路径为相对 /api/*。共享类型放在 src/shared，前端不得 import src/server 的运行时实现。

这保证了当前可以单文件部署，也保留未来将前端拆到 CDN 或独立静态站点的路径。

已知限制

当前 demo 不包含数据库、认证、SSR、React Router 或 UI 组件库。单 executable 是按目标平台构建的产物，不是一个文件同时覆盖 macOS、Linux 和 Windows。