Skip to content
welthyPublic

About

A tool that use to check the cost of one turn of AI chat

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Cost Usage

Express v5 + Socket.IO v4 服务端 + React v19 + Vite v6 前端全栈项目。前后端分离部署,通过 HTTP REST API 和 WebSocket 双向通信。

技术栈

后端(根目录)

技术 版本 用途
Node.js ≥18 运行时
TypeScript ^5.7 类型安全(strict 模式)
Express ^5.2 HTTP 框架,提供 REST API
Socket.IO ^4.8 WebSocket 实时双向通信
tsx ^4.19 开发热重载(watch 模式)

前端(client/ 目录)

技术 版本 用途
React ^19.1 UI 框架
TypeScript ~5.7 类型安全
Vite ^6.3 构建工具 + 开发服务器
socket.io-client ^4.8 WebSocket 客户端

项目结构

cost_usage/
├── package.json              # 后端根配置
├── tsconfig.json             # 后端 TS 配置
├── .gitignore
├── README.md
├── src/                      # 后端源码
│   ├── server.ts             # 入口:创建 http.Server + listen
│   ├── app.ts                # Express 应用组装(不调用 listen)
│   ├── config/
│   │   └── index.ts          # 集中配置(端口、CORS)
│   ├── routes/
│   │   ├── index.ts          # 路由汇总
│   │   └── health.ts         # GET /api/health 健康检查
│   ├── socket/
│   │   └── index.ts          # Socket.IO 初始化 + 事件注册
│   └── types/
│       └── socket.ts         # Socket.IO 四接口类型定义
└── client/                   # 前端(独立模块)
    ├── package.json          # 前端独立依赖
    ├── tsconfig.json         # 前端 TS 配置(ESM + JSX)
    ├── vite.config.ts        # Vite 配置 + 代理规则
    ├── index.html            # Vite 入口 HTML
    └── src/
        ├── main.tsx          # React 入口
        ├── App.tsx           # 根组件
        ├── App.css
        ├── index.css
        └── vite-env.d.ts     # Vite 类型声明

架构

┌──────────────────────────────────────────────────────┐
│                    开发环境                           │
│                                                      │
│   ┌──────────┐        ┌──────────────┐               │
│   │ 浏览器    │  :5173 │ Vite Dev     │               │
│   │          ├───────►│ Server       │               │
│   │          │        │ (React HMR)  │               │
│   └──────────┘        └───┬────┬─────┘               │
│        ▲                  │    │                     │
│        │ 静态资源          │    │ /api/*              │
│        │ (React 页面)      │    │ /socket.io/*        │
│        │                  │    │ (proxy 转发)        │
│        └──────────────────┘    │                     │
│                                ▼                     │
│                        ┌──────────────┐              │
│                        │ http.Server   │ :3000       │
│                        │ (Express +    │              │
│                        │  Socket.IO)   │              │
│                        └──────────────┘              │
└──────────────────────────────────────────────────────┘

核心设计:

  • 后端 app.ts 只负责组装 Express(中间件 + 路由),绝不调用 listen()
  • server.ts 创建共享的 http.Server,把 Express 和 Socket.IO 都挂上去,统一 listen()
  • 前端 client/ 是独立的 npm 项目,有自己的 package.json、tsconfig.json 和构建链
  • 开发时 Vite dev server(:5173)通过 proxy 把 /api 和 /socket.io 请求转发到后端(:3000),前端代码直接用相对路径,零 CORS 配置
  • 前后端通过 HTTP REST API + WebSocket 通信,天然解耦

运行项目

1. 安装依赖

# 后端
npm install

# 前端
cd client && npm install

2. 开发模式

需要两个终端分别启动后端和前端:

# 终端 1:启动后端(端口 3000,tsx watch 热重载)
npm run dev

# 终端 2:启动前端(端口 5173,Vite HMR 热更新)
cd client && npm run dev

浏览器访问 **http://localhost:5173**,页面会自动:

  • 通过 REST 调用 /api/health 检查后端健康状态
  • 通过 WebSocket 发送 ping,接收 pong 回执

3. 生产构建

# 后端编译
npm run build        # tsc → dist/
npm start            # node dist/server.js

# 前端编译(输出到 client/dist/)
cd client && npm run build

生产部署时,可将 client/dist/ 中的静态文件交由 Express 托管,或部署到 CDN。

API 接口

健康检查

GET /api/health

响应:

{ "status": "ok", "timestamp": "2026-08-11T02:04:40.095Z" }

Socket.IO 事件

客户端 → 服务端

事件 载荷 说明
ping 无 服务端通过 ACK 回调返回 "pong"
// 客户端示例
socket.emit('ping', (response) => {
  console.log(response); // "pong"
});

服务端 → 客户端

事件 说明
pong 预留主动推送
notification 预留通知事件

扩展指南

添加后端的 REST 路由

  1. 在 src/routes/ 下创建新文件(如 user.ts):
import { Router } from 'express';
const router = Router();

router.get('/users', async (req, res) => {
  res.json([{ id: 1, name: 'Alice' }]);
});

export default router;
  1. 在 src/routes/index.ts 中挂载:
import userRouter from './user';
router.use(userRouter);

添加后端的 Socket.IO 事件

在 src/socket/index.ts 的 io.on('connection', ...) 回调中添加处理逻辑,同时更新 src/types/socket.ts 的 ClientToServerEvents / ServerToClientEvents 接口。

添加前端页面

在 client/src/ 下创建新组件,如 client/src/pages/Dashboard.tsx,然后在 App.tsx 中引入路由或直接渲染。

注意: 前端请求后端 API 时使用相对路径(如 fetch('/api/health')),开发时 Vite proxy 自动转发到后端,生产时需根据部署方式调整。

Express v5 注意事项

v4 写法 v5 写法
/* 通配符 /{*splat},req.params.splat 是数组
res.json(obj, status) res.status(status).json(obj)
res.redirect(url, status) res.redirect(status, url)(参数顺序互换)
异步 handler 需 .catch(next) 原生支持,自动转发 rejected promise
req.query 可赋值 是 getter,不可赋值
express.urlencoded() 默认 extended: true 默认 extended: false,需显式传入

常用命令速查

位置 命令 说明
根目录 npm run dev 后端开发(热重载,:3000)
根目录 npm run build 后端编译(tsc → dist/)
根目录 npm start 后端生产启动
client/ npm run dev 前端开发(HMR,:5173)
client/ npm run build 前端构建(→ client/dist/)
client/ npm run preview 预览前端构建产物

About

A tool that use to check the cost of one turn of AI chat

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages