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

feat: 引入运行时日志体系和存储配置，配置文件改为必填

Browse Source 
- 新增 pino/pino-pretty/pino-roll 依赖，实现结构化日志（console pretty + file JSONL rolling）
- 新增 Logger 接口及 PinoLoggerWrapper/ConsoleFallbackLogger/NoopLogger/MemoryLogger 实现
- 新增 src/pino-roll.d.ts 类型声明
- 新增 server.storage.dataDir 配置（默认 ./data，相对路径基于配置文件目录）
- 新增 server.logging 配置（level/console/file/rotation，支持变量引用）
- 配置文件从可选改为必填，parseRuntimeArgs 无参数时抛错
- bootstrap 创建 logger、确保 dataDir、shutdown flush、失败路径 fallback
- startServer 接收 logger 并输出结构化监听日志
- ESLint 新增 no-restricted-syntax 禁止 src/server 直接 console.*（排除 logger.ts）
- 更新 config.example.yaml、README.md、DEVELOPMENT.md 同步配置和日志文档
- 完善测试覆盖：logger、config、schema、bootstrap 共 150 个测试通过
This commit is contained in:
兰缘小妖
2026-05-25 14:44:37 +08:00
parent c592f2b97c
commit 60d50afad1
22 changed files with 1658 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
README.md
View File

@@ -9,8 +9,9 @@ Bun 全栈应用模板，基于 Bun + React + TDesign 的前后端一体化开
```bash
git clone <your-repo-url> my-project
cd my-project
cp config.example.yaml config.yaml
bun install
bun run dev
bun run dev config.yaml
```
访问 http://127.0.0.1:5173 查看应用。
@@ -42,7 +43,15 @@ export const APP = {
> **注意**：localStorage key 已从 `"my-app.theme.preference"` 变更为 `"theme.preference"`。如果从旧版本升级，用户的主题偏好设置将丢失，需重新选择。
### 3. 清理 OpenSpec 历史
### 3. 准备配置文件
```bash
cp config.example.yaml config.yaml
```
按需编辑 `config.yaml` 中的监听地址、日志、存储路径等配置。
### 4. 清理 OpenSpec 历史
删除模板自带的 OpenSpec 变更历史，保留框架配置：
@@ -53,44 +62,45 @@ rm -rf openspec/changes/*
> `openspec/config.yaml` 和 `openspec/schemas/fast-drive/` 需要保留，其中包含项目开发规范配置与自定义 OpenSpec workflow schema。
### 4. 安装依赖
### 5. 安装依赖
```bash
bun install
```
### 5. 开始开发
### 6. 开始开发
```bash
bun run dev
bun run dev config.yaml
```
## 项目管理
| 命令 | 说明 |
| ----------------------- | ---------------------------------------------------------- |
| `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 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` | 显式设置版本号 |
| 命令 | 说明 |
| ----------------------- | ------------------------------------------------------------------- |
| `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 配置（测试预加载等）
@@ -116,11 +126,12 @@ bun run dev
│ │ ├── main.ts # 生产模式入口
│ │ ├── server.ts # HTTP 服务器（Bun.serve routes 声明式路由）
│ │ ├── helpers.ts # 共享响应工具（健康检查、JSON 响应）
│ │ ├── middleware.ts # API 参数校验中间件
│ │ ├── logger.ts # 结构化日志（基于 pino + pino-roll）
│ │ ├── middleware.ts # API 参数校验中间件
│ │ ├── static.ts # 静态资源服务
│ │ └── routes/ # API 路由处理器
│ │ └── meta.ts # 应用元信息端点（GET /api/meta）
│ │ version.ts # 版本号读取
│ │ └── routes/ # API 路由处理器
│ │ ├── meta.ts # 应用元信息端点（GET /api/meta）
│ │ └── version.ts # 版本号读取
│ ├── shared/
│ │ ├── api.ts # 前后端共享 TypeScript 类型定义
│ │ └── app.ts # 应用全局常量（name、title、subtitle、description）
@@ -150,7 +161,7 @@ bun run dev
## 配置
项目使用 YAML 配置文件，支持通过 JSON Schema 编辑器提示和显式变量引用。
项目使用 YAML 配置文件，配置文件为**必传参数**，支持通过 JSON Schema 编辑器提示和显式变量引用。配置中的相对路径均基于配置文件所在目录解析，绝对路径保持不变。
### 配置文件
@@ -162,9 +173,62 @@ 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` 和 `server.listen.port`。
### 配置字段说明
#### 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
@@ -222,6 +286,9 @@ bun run dev custom-config.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) | 日志文件轮转 |
### 前端