227 lines
9.6 KiB
Markdown
227 lines
9.6 KiB
Markdown
# my-app
|
||
|
||
（替换为你的项目介绍）
|
||
|
||
Bun 全栈应用模板，基于 Bun + React + TDesign 的前后端一体化开发框架。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
git clone <your-repo-url> my-project
|
||
cd my-project
|
||
bun install
|
||
bun run dev
|
||
```
|
||
|
||
访问 http://127.0.0.1:5173 查看应用。
|
||
|
||
## 使用此模板
|
||
|
||
### 1. 克隆模板
|
||
|
||
```bash
|
||
git clone <template-repo-url> my-project
|
||
cd my-project
|
||
rm -rf .git && git init
|
||
```
|
||
|
||
### 2. 配置应用信息
|
||
|
||
编辑 `src/shared/app.ts`，修改应用元信息：
|
||
|
||
```typescript
|
||
export const APP = {
|
||
name: "your-app", // 机器标识（kebab-case）
|
||
title: "Your App", // 人类可读标题
|
||
subtitle: "你的副标题", // 副标题
|
||
description: "应用描述", // SEO meta 描述
|
||
} as const;
|
||
```
|
||
|
||
同时修改 `package.json` 的 `name` 字段保持一致，`version` 字段管理应用版本号。
|
||
|
||
> **注意**：localStorage key 已从 `"my-app.theme.preference"` 变更为 `"theme.preference"`。如果从旧版本升级，用户的主题偏好设置将丢失，需重新选择。
|
||
|
||
### 3. 清理 OpenSpec 历史
|
||
|
||
删除模板自带的 OpenSpec 变更历史，保留框架配置：
|
||
|
||
```bash
|
||
rm -rf openspec/specs/*
|
||
rm -rf openspec/changes/*
|
||
```
|
||
|
||
> `openspec/config.yaml` 和 `openspec/schemas/fast-drive/` 需要保留，其中包含项目开发规范配置与自定义 OpenSpec workflow schema。
|
||
|
||
### 4. 安装依赖
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
### 5. 开始开发
|
||
|
||
```bash
|
||
bun run dev
|
||
```
|
||
|
||
## 项目管理
|
||
|
||
| 命令 | 说明 |
|
||
| ----------------------- | ---------------------------------------------------------- |
|
||
| `bun run dev` | 启动开发模式（并行启动后端 + 前端 Vite 开发服务器） |
|
||
| `bun run dev:server` | 仅启动后端开发服务（`--watch` 热重载） |
|
||
| `bun run dev:web` | 仅启动前端 Vite 开发服务器 |
|
||
| `bun run build` | 生产构建（Vite 打包前端 → Bun compile 生成独立可执行文件） |
|
||
| `bun test` | 运行全部测试 |
|
||
| `bun run lint` | ESLint 代码风格检查 |
|
||
| `bun run format` | Prettier 代码格式化 |
|
||
| `bun run typecheck` | TypeScript 类型检查 |
|
||
| `bun run check` | 完整质量检查：typecheck + lint + test |
|
||
| `bun run verify` | 验证构建流程：check + build |
|
||
| `bun run clean` | 清理构建产物和临时文件 |
|
||
| `bun run version:patch` | 升迁 patch 版本（x.y.Z） |
|
||
| `bun run version:minor` | 升迁 minor 版本（x.Y.0） |
|
||
| `bun run version:major` | 升迁 major 版本（X.0.0） |
|
||
| `bun run version:set` | 显式设置版本号 |
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
.
|
||
├── config.example.yaml # 配置文件示例
|
||
├── bunfig.toml # Bun 配置（测试预加载等）
|
||
├── tsconfig.json # TypeScript 配置
|
||
├── vite.config.ts # Vite 构建配置（代码分包、代理）
|
||
├── eslint.config.js # ESLint 统一配置
|
||
├── .prettierrc.json # Prettier 格式化配置
|
||
├── commitlint.config.js # Commitlint 提交规范配置
|
||
├── .lintstagedrc.json # lint-staged 暂存区检查配置
|
||
├── scripts/
|
||
│ ├── dev.ts # 开发启动脚本（并行启动 API + Vite）
|
||
│ ├── build.ts # 生产构建脚本（Vite → 代码生成 → Bun compile，含版本号注入）
|
||
│ ├── bump-version-logic.ts # 纯版本管理逻辑（parse、validate、bump、format）
|
||
│ ├── bump-version.ts # 版本升迁 CLI 脚本
|
||
│ └── clean.ts # 清理脚本
|
||
├── src/
|
||
│ ├── server/ # 后端代码
|
||
│ │ ├── bootstrap.ts # 统一启动引导（配置加载 → 服务启动 → 优雅关闭）
|
||
│ │ ├── config.ts # CLI 参数解析 + YAML 配置加载
|
||
│ │ ├── dev.ts # 开发模式入口
|
||
│ │ ├── main.ts # 生产模式入口
|
||
│ │ ├── server.ts # HTTP 服务器（Bun.serve routes 声明式路由）
|
||
│ │ ├── helpers.ts # 共享响应工具（健康检查、JSON 响应）
|
||
│ │ ├── middleware.ts # API 参数校验中间件
|
||
│ │ ├── static.ts # 静态资源服务
|
||
│ │ └── routes/ # API 路由处理器
|
||
│ │ └── meta.ts # 应用元信息端点（GET /api/meta）
|
||
│ │ version.ts # 版本号读取
|
||
│ ├── shared/
|
||
│ │ ├── api.ts # 前后端共享 TypeScript 类型定义
|
||
│ │ └── app.ts # 应用全局常量（name、title、subtitle、description）
|
||
│ └── web/ # 前端代码
|
||
│ ├── index.html # HTML 入口
|
||
│ ├── main.tsx # React 入口（BrowserRouter + QueryClient + ErrorBoundary）
|
||
│ ├── app.tsx # 根组件（Admin 布局：Header + Sidebar + Content + 版本号展示）
|
||
│ ├── routes.tsx # 路由配置
|
||
│ ├── styles.css # 全局样式
|
||
│ ├── css.d.ts # CSS 模块类型声明
|
||
│ ├── pages/ # 页面组件
|
||
│ │ ├── dashboard/ # 仪表盘页
|
||
│ │ ├── users/ # 用户管理页
|
||
│ │ ├── settings/ # 系统设置页
|
||
│ │ └── 404/ # 404 页面
|
||
│ ├── components/ # UI 组件
|
||
│ │ ├── ErrorBoundary.tsx
|
||
│ │ └── Sidebar/ # 侧边栏组件
|
||
│ ├── hooks/ # React Hooks
|
||
│ ├── utils/ # 前端工具函数
|
||
│ ├── menu.tsx # 菜单配置
|
||
│ └── routes.tsx # 路由配置
|
||
├── tests/ # 测试文件（镜像 src 目录结构）
|
||
├── openspec/ # OpenSpec 规格、变更与 fast-drive workflow schema
|
||
└── docs/ # 项目文档
|
||
```
|
||
|
||
## 配置
|
||
|
||
项目使用 YAML 配置文件，支持环境变量覆盖。
|
||
|
||
### 配置文件
|
||
|
||
复制 `config.example.yaml` 为 `config.yaml`（或任意名称），根据需要修改：
|
||
|
||
```yaml
|
||
server:
|
||
host: "127.0.0.1"
|
||
port: 3000
|
||
```
|
||
|
||
### 环境变量覆盖
|
||
|
||
| 环境变量 | 对应配置字段 | 默认值 |
|
||
| -------- | ------------- | ----------- |
|
||
| `HOST` | `server.host` | `127.0.0.1` |
|
||
| `PORT` | `server.port` | `3000` |
|
||
|
||
### 配置优先级
|
||
|
||
```
|
||
环境变量 > YAML 配置文件 > 代码默认值
|
||
```
|
||
|
||
### 使用自定义配置
|
||
|
||
```bash
|
||
bun run dev custom-config.yaml
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
### 运行时
|
||
|
||
| 技术 | 说明 |
|
||
| --------------------------------------------- | ---------------------------------------------- |
|
||
| [Bun](https://bun.sh) | JavaScript/TypeScript 运行时、包管理器、打包器 |
|
||
| [TypeScript](https://www.typescriptlang.org/) | 类型安全的 JavaScript 超集 |
|
||
|
||
### 后端
|
||
|
||
| 技术 | 说明 |
|
||
| -------------------------------------------- | ---------------------------- |
|
||
| `Bun.serve` | HTTP 服务器，声明式路由匹配 |
|
||
| `Bun.YAML` | YAML 配置文件解析 |
|
||
| [es-toolkit](https://es-toolkit.slash.page/) | 高性能工具库（推荐优先使用） |
|
||
|
||
### 前端
|
||
|
||
| 技术 | 说明 |
|
||
| --------------------------------------------------- | ------------------------ |
|
||
| [React 19](https://react.dev/) | UI 组件框架 |
|
||
| [React Router](https://reactrouter.com/) | SPA 路由与页面导航 |
|
||
| [TDesign React](https://tdesign.tencent.com/react/) | 企业级 UI 组件库 |
|
||
| [@tanstack/react-query](https://tanstack.com/query) | 服务端状态管理与数据获取 |
|
||
| [Recharts](https://recharts.org/) | 图表可视化（推荐使用） |
|
||
| [Vite](https://vitejs.dev/) | 前端构建工具 |
|
||
|
||
### 工程化
|
||
|
||
| 技术 | 说明 |
|
||
| ------------------------------------------ | ---------------- |
|
||
| [ESLint](https://eslint.org/) | 代码规范检查 |
|
||
| [Prettier](https://prettier.io/) | 代码格式化 |
|
||
| [Husky](https://typicode.github.io/husky/) | Git hooks 管理 |
|
||
| [Commitlint](https://commitlint.js.org/) | Git 提交消息校验 |
|
||
|
||
### 测试
|
||
|
||
| 技术 | 说明 |
|
||
| ----------------------------------------------------------- | ---------------- |
|
||
| [bun:test](https://bun.sh/docs/cli/test) | Bun 内置测试框架 |
|
||
| [@testing-library/react](https://testing-library.com/react) | React 组件测试 |
|
||
| [jsdom](https://github.com/jsdom/jsdom) | DOM 环境模拟 |
|
||
|
||
## 开源协议
|
||
|
||
MIT
|