feat: 引入分层配置生命周期，支持变量引用和 JSON Schema 校验
- 新增 src/server/config/ 模块（types、issues、variables、normalizer、schema）
- 配置布局从 server.host/server.port 切换为 server.listen.host/server.listen.port
- 移除 HOST/PORT 隐式环境变量覆盖，改为 YAML 显式 ${KEY} 变量引用
- 支持 ${KEY}、${KEY|default}、${KEY|}、$${KEY} 变量语法
- 使用 @sinclair/typebox + ajv 实现运行时严格契约校验和 JSON Schema 导出
- 新增 scripts/generate-config-schema.ts 和 config.schema.json
- 新增 bun run schema / schema:check 命令，check 先执行 schema:check
- 更新 README.md 和 DEVELOPMENT.md 匹配新配置体系
- 新增变量解析、schema 校验和 schema 同步测试
This commit is contained in:
64
README.md
64
README.md
@@ -77,7 +77,9 @@ bun run dev
|
||||
| `bun run lint` | ESLint 代码风格检查 |
|
||||
| `bun run format` | Prettier 代码格式化 |
|
||||
| `bun run typecheck` | TypeScript 类型检查 |
|
||||
| `bun run check` | 完整质量检查：typecheck + lint + test |
|
||||
| `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） |
|
||||
@@ -89,7 +91,8 @@ bun run dev
|
||||
|
||||
```text
|
||||
.
|
||||
├── config.example.yaml # 配置文件示例
|
||||
├── config.example.yaml # 配置文件示例（server.listen 布局 + 显式变量引用）
|
||||
├── config.schema.json # 配置文件 JSON Schema（由 bun run schema 生成）
|
||||
├── bunfig.toml # Bun 配置（测试预加载等）
|
||||
├── tsconfig.json # TypeScript 配置
|
||||
├── vite.config.ts # Vite 构建配置（代码分包、代理）
|
||||
@@ -100,13 +103,15 @@ bun run dev
|
||||
├── 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 配置加载
|
||||
│ │ ├── config.ts # CLI 参数解析 + YAML 配置加载 facade
|
||||
│ │ ├── config/ # 配置解析模块（types、issues、variables、normalizer、schema）
|
||||
│ │ ├── dev.ts # 开发模式入口
|
||||
│ │ ├── main.ts # 生产模式入口
|
||||
│ │ ├── server.ts # HTTP 服务器（Bun.serve routes 声明式路由）
|
||||
@@ -145,31 +150,54 @@ bun run dev
|
||||
|
||||
## 配置
|
||||
|
||||
项目使用 YAML 配置文件，支持环境变量覆盖。
|
||||
项目使用 YAML 配置文件，支持通过 JSON Schema 编辑器提示和显式变量引用。
|
||||
|
||||
### 配置文件
|
||||
|
||||
复制 `config.example.yaml` 为 `config.yaml`（或任意名称），根据需要修改：
|
||||
|
||||
```yaml
|
||||
# yaml-language-server: $schema=./config.schema.json
|
||||
server:
|
||||
host: "127.0.0.1"
|
||||
port: 3000
|
||||
listen:
|
||||
host: "${HOST|127.0.0.1}"
|
||||
port: ${PORT|3000}
|
||||
```
|
||||
|
||||
### 环境变量覆盖
|
||||
配置文件唯一合法布局为 `server.listen.host` 和 `server.listen.port`。
|
||||
|
||||
| 环境变量 | 对应配置字段 | 默认值 |
|
||||
| -------- | ------------- | ----------- |
|
||||
| `HOST` | `server.host` | `127.0.0.1` |
|
||||
| `PORT` | `server.port` | `3000` |
|
||||
### 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。
|
||||
|
||||
### 配置优先级
|
||||
|
||||
```
|
||||
环境变量 > YAML 配置文件 > 代码默认值
|
||||
variables 字段 > 环境变量 > 默认值 > unresolved 报错
|
||||
```
|
||||
|
||||
环境变量**不会隐式覆盖**配置，只有通过 `${KEY}` 显式引用时才生效。
|
||||
|
||||
### 使用自定义配置
|
||||
|
||||
```bash
|
||||
@@ -187,11 +215,13 @@ bun run dev custom-config.yaml
|
||||
|
||||
### 后端
|
||||
|
||||
| 技术 | 说明 |
|
||||
| -------------------------------------------- | ---------------------------- |
|
||||
| `Bun.serve` | HTTP 服务器，声明式路由匹配 |
|
||||
| `Bun.YAML` | YAML 配置文件解析 |
|
||||
| [es-toolkit](https://es-toolkit.slash.page/) | 高性能工具库（推荐优先使用） |
|
||||
| 技术 | 说明 |
|
||||
| ------------------------------------------------------------ | ---------------------------- |
|
||||
| `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/) | 高性能工具库（推荐优先使用） |
|
||||
|
||||
### 前端
|
||||
|
||||
|
||||
Reference in New Issue
Block a user