133 lines
3.8 KiB
Markdown
133 lines
3.8 KiB
Markdown
# Gateway Checker
|
||
|
||
基于 Bun + TypeScript 的前后端一体化 demo。开发期使用 Vite + React 提供前端 HMR，后端由 Bun 提供 API；生产期先构建前端静态资源，再将前端资源和 Bun 后端打包为单个 executable。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
src/
|
||
server/ Bun 后端运行时、API、静态资源 fallback
|
||
shared/ 前后端共享 TypeScript 类型
|
||
web/ Vite + React 前端 demo
|
||
scripts/ 开发、构建和 smoke test 脚本
|
||
tests/ Bun test 测试
|
||
openspec/ OpenSpec 变更与规格文档
|
||
```
|
||
|
||
## 开发命令
|
||
|
||
```bash
|
||
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 配置。
|
||
|
||
全栈开发命令使用 `PORT` 作为后端端口覆盖来源，并将同一端口传给 Vite proxy：
|
||
|
||
```bash
|
||
PORT=4000 bun run dev
|
||
```
|
||
|
||
也可以分别运行：
|
||
|
||
```bash
|
||
bun run dev:server
|
||
bun run dev:web
|
||
```
|
||
|
||
分别运行时，若后端不是默认 `3000` 端口，需要为 Vite 指定同一个后端端口：
|
||
|
||
```bash
|
||
PORT=4000 bun run dev:server
|
||
BACKEND_PORT=4000 bun run dev:web
|
||
```
|
||
|
||
## 代码质量
|
||
|
||
```bash
|
||
bun run lint
|
||
bun run format:check
|
||
bun run format
|
||
bun run check
|
||
```
|
||
|
||
- `lint` 使用 ESLint 检查 TypeScript、React Hooks 和前后端边界。
|
||
- `format:check` 使用 Prettier 检查代码格式。
|
||
- `format` 使用 Prettier 重写受管理文件格式。
|
||
- `check` 依次运行 `typecheck`、`lint`、`format:check` 和单元测试，适合日常开发期间快速验证。
|
||
|
||
Prettier 不格式化 `openspec/`、`dist/`、`.build/`、`node_modules/`、`bun.lock` 和临时构建产物。
|
||
|
||
## Demo 验证
|
||
|
||
开发期打开 `http://127.0.0.1:5173`，页面应显示 `/api/demo` 返回的后端 message、Bun 版本、平台和响应时间。
|
||
|
||
直接验证 API：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:3000/api/demo
|
||
curl http://127.0.0.1:3000/health
|
||
```
|
||
|
||
## 构建 executable
|
||
|
||
```bash
|
||
bun run build
|
||
```
|
||
|
||
构建流程：
|
||
|
||
- 运行 `vite build`，输出前端资源到 `dist/web`
|
||
- 生成临时 `.build/static-assets.ts`，用 Bun file import 嵌入 Vite 产物
|
||
- 生成临时 `.build/server-entry.ts`，作为生产 executable 的 server 入口
|
||
- 运行 `Bun.build({ compile })`，输出 `dist/gateway-checker`
|
||
|
||
运行 executable：
|
||
|
||
```bash
|
||
./dist/gateway-checker
|
||
```
|
||
|
||
生产期默认访问 `http://127.0.0.1:3000`。同一个 executable 会服务 `/api/demo`、`/health`、`/assets/*` 和前端 SPA fallback。
|
||
|
||
## 运行参数
|
||
|
||
默认配置：
|
||
|
||
- `HOST=127.0.0.1`
|
||
- `PORT=3000`
|
||
|
||
可以通过环境变量或 CLI 参数覆盖：
|
||
|
||
```bash
|
||
PORT=4000 ./dist/gateway-checker
|
||
./dist/gateway-checker --host 0.0.0.0 --port 4000
|
||
```
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
bun run check
|
||
bun run verify
|
||
```
|
||
|
||
- `check` 适合日常开发，包含类型检查、lint、格式检查和单元测试。
|
||
- `verify` 适合提交前或发布前，先运行 `check`，再重新构建生产 executable 并运行 smoke test。
|
||
- `test:smoke` 会启动生成的 executable，并检查 `/api/demo`、`/health`、前端根路径、静态资源、未知 API、未知静态资源、生产模式、缓存响应头、低风险安全响应头和 SPA fallback。
|
||
|
||
## 前后端边界
|
||
|
||
前端只通过 HTTP 调用后端，默认 API 路径为相对 `/api/*`。共享类型放在 `src/shared`，前端不得 import `src/server` 的运行时实现。
|
||
|
||
这保证了当前可以单文件部署，也保留未来将前端拆到 CDN 或独立静态站点的路径。
|
||
|
||
## 已知限制
|
||
|
||
当前 demo 不包含数据库、认证、SSR、React Router 或 UI 组件库。单 executable 是按目标平台构建的产物，不是一个文件同时覆盖 macOS、Linux 和 Windows。
|