lanyuanxiaoyao/bun-app-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 引入分层文档体系，删除 DEVELOPMENT.md

Browse Source 
建立 docs/user/ 和 docs/development/ 分层文档结构：
- docs/README.md 文档总路由、归属矩阵、影响分析规则
- docs/user/ 模板使用、配置、部署、故障排查
- docs/development/ 架构、后端、前端、构建发布开发规范
- README.md 轻量化为项目入口和索引
- 删除 DEVELOPMENT.md，内容拆分至专题文档
- 更新 openspec/config.yaml 首读入口和文档影响分析规则
- 修正 docs/prompts/README.md 过时引用和边界说明
This commit is contained in:
兰缘小妖
2026-05-25 19:09:08 +08:00
parent 0d08c914de
commit 763d814543
15 changed files with 941 additions and 1159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

311
README.md
View File

@@ -18,305 +18,26 @@ bun run dev config.yaml
## 使用此模板
### 1. 克隆模板
从零创建新项目：[使用模板](docs/user/usage.md)
```bash
git clone <template-repo-url> my-project
cd my-project
rm -rf .git && git init
```
## 文档导航
### 2. 配置应用信息
| 文档 | 内容 |
| -------------------------------------- | ---------------------------------- |
| [docs/README.md](docs/README.md) | 文档总览、归属矩阵、影响分析规则 |
| [docs/user/](docs/user/) | 模板使用、配置、部署、故障排查 |
| [docs/development/](docs/development/) | 架构、后端、前端、构建发布开发规范 |
| [docs/prompts/](docs/prompts/) | AI 提示词资产（不属于常规文档流） |
编辑 `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. 准备配置文件
```bash
cp config.example.yaml config.yaml
```
按需编辑 `config.yaml` 中的监听地址、日志、存储路径等配置。
### 4. 清理 OpenSpec 历史
删除模板自带的 OpenSpec 变更历史，保留框架配置：
```bash
rm -rf openspec/specs/*
rm -rf openspec/changes/*
```
> `openspec/config.yaml` 和 `openspec/schemas/fast-drive/` 需要保留，其中包含项目开发规范配置与自定义 OpenSpec workflow schema。
### 5. 安装依赖
```bash
bun install
```
### 6. 开始开发
```bash
bun run dev config.yaml
```
## 项目管理
| 命令 | 说明 |
| ----------------------- | ------------------------------------------------------------------- |
| `bun run dev <config>` | 启动开发模式（并行启动后端 + 前端 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 schema` | 生成 config.schema.json |
| `bun run schema:check` | 校验 config.schema.json 是否同步 |
| `bun run check` | 完整质量检查：schema: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
.
├── data/ # 运行时数据目录（日志等）
├── config.example.yaml # 配置文件示例（server.listen 布局 + 显式变量引用）
├── config.schema.json # 配置文件 JSON Schema（由 bun run schema 生成）
├── 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，含版本号注入）
│ ├── generate-config-schema.ts # 配置 JSON Schema 生成与同步校验脚本
│ ├── bump-version-logic.ts # 纯版本管理逻辑（parse、validate、bump、format）
│ ├── bump-version.ts # 版本升迁 CLI 脚本
│ └── clean.ts # 清理脚本
├── src/
│ ├── server/ # 后端代码
│ │ ├── bootstrap.ts # 统一启动引导（配置加载 → 服务启动 → 优雅关闭）
│ │ ├── config.ts # CLI 参数解析 + YAML 配置加载 facade
│ │ ├── config/ # 配置解析模块（types、issues、variables、normalizer、schema）
│ │ ├── dev.ts # 开发模式入口
│ │ ├── main.ts # 生产模式入口
│ │ ├── server.ts # HTTP 服务器（Bun.serve routes 声明式路由）
│ │ ├── helpers.ts # 共享响应工具（健康检查、JSON 响应）
│ │ ├── logger.ts # 结构化日志（基于 pino + pino-roll）
│ │ ├── 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 配置文件，配置文件为**必传参数**，支持通过 JSON Schema 编辑器提示和显式变量引用。配置中的相对路径均基于配置文件所在目录解析，绝对路径保持不变。
### 配置文件
复制 `config.example.yaml` 为 `config.yaml`（或任意名称），根据需要修改：
```yaml
# yaml-language-server: $schema=./config.schema.json
server:
listen:
host: "${HOST|127.0.0.1}"
port: ${PORT|3000}
storage:
dataDir: ./data
logging:
level: info
console:
level: info
file:
level: info
path: "./logs/${APP.name}.log"
rotation:
size: 50MB
frequency: daily
maxFiles: 14
```
### 配置字段说明
#### server.listen
| 字段 | 类型 | 说明 |
| ---- | ------ | -------------------------- |
| host | string | 监听地址，默认 `127.0.0.1` |
| port | number | 监听端口，默认 `3000` |
#### server.storage
| 字段 | 类型 | 说明 |
| ------- | ------ | --------------------------------------------------------- |
| dataDir | string | 数据目录，默认 `./data`，相对路径基于配置文件所在目录解析 |
#### server.logging
| 字段 | 类型 | 说明 |
| ----- | ------ | ------------------------------------------------------------------------------------ |
| level | string | 全局日志级别（`trace` / `debug` / `info` / `warn` / `error` / `fatal`），默认 `info` |
##### server.logging.console
| 字段 | 类型 | 说明 |
| ----- | ------ | --------------------------------------------------- |
| level | string | 控制台日志级别，未设置时继承 `server.logging.level` |
##### server.logging.file
| 字段 | 类型 | 说明 |
| ----- | ------ | --------------------------------------------------- |
| level | string | 文件日志级别，未设置时继承 `server.logging.level` |
| path | string | 日志文件路径，默认 `<dataDir>/logs/${APP.name}.log` |
##### server.logging.file.rotation
| 字段 | 类型 | 说明 |
| --------- | ------ | ----------------------------------------------------------- |
| size | string | 按大小轮转，支持 `B` / `KB` / `MB` / `GB` 单位，默认 `50MB` |
| frequency | string | 按时间轮转（`hourly` / `daily` / `weekly`），默认 `daily` |
| maxFiles | number | 最大归档文件数，默认 `14` |
### JSON Schema
根目录 `config.schema.json` 为配置文件的 JSON Schema，支持 IDE 自动补全和校验。通过 `# yaml-language-server: $schema=./config.schema.json` 注释启用。
```bash
bun run schema # 重新生成 config.schema.json
bun run schema:check # 校验 schema 是否同步
```
### 变量语法
YAML 配置中支持显式变量引用：
| 语法 | 说明 |
| --------------- | ------------------------------ |
| `${KEY}` | 引用变量，未定义时报错 |
| `${KEY\|value}` | 引用变量，未定义时使用默认值 |
| `${KEY\|}` | 引用变量，未定义时使用空字符串 |
| `$${KEY}` | 转义，输出 `${KEY}` 原文字面量 |
变量解析优先级：`variables 字段` → `process.env` → `默认值` → `unresolved 报错`
完整变量引用（整个值只有 `${...}`）保留原始类型：`${PORT|3000}` 解析为 number `3000`。部分拼接统一转为 string。
### 配置优先级
```
variables 字段 > 环境变量 > 默认值 > unresolved 报错
```
环境变量**不会隐式覆盖**配置，只有通过 `${KEY}` 显式引用时才生效。
### 使用自定义配置
```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 配置文件解析 |
| [@sinclair/typebox](https://github.com/sinclairzx81/typebox) | JSON Schema 类型构建器 |
| [Ajv](https://ajv.js.org/) | JSON Schema 运行时校验 |
| [es-toolkit](https://es-toolkit.slash.page/) | 高性能工具库（推荐优先使用） |
| [pino](https://getpino.io/) | 结构化日志库 |
| [pino-pretty](https://github.com/pinojs/pino-pretty) | 开发环境日志美化输出 |
| [pino-roll](https://github.com/feugy/pino-roll) | 日志文件轮转 |
### 前端
| 技术 | 说明 |
| --------------------------------------------------- | ------------------------ |
| [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 环境模拟 |
| 命令 | 说明 |
| ---------------------- | ------------ |
| `bun run dev <config>` | 启动开发模式 |
| `bun run build` | 生产构建 |
| `bun test` | 运行测试 |
| `bun run check` | 完整质量检查 |
| `bun run verify` | 验证构建流程 |
## 开源协议