# DiAL 开发文档 本文档面向 DiAL 项目的开发者，介绍项目结构、构建流程、测试、代码规范等内容。 用户使用说明请参阅 [README.md](README.md)。 ## 项目结构 ```text src/ server/ app.ts Bun HTTP 路由入口（路由分发 + API 汇聚） config.ts CLI 参数解析 dev.ts 开发期启动入口 server.ts HTTP server 启动 helpers.ts 共享响应格式化工具（jsonResponse、createHeaders 等） middleware.ts API 参数校验中间件（guardGetHead、validateTargetId 等） static.ts 静态资源服务 与 SPA fallback routes/ API 路由 handler（按端点拆分） health.ts GET /health summary.ts GET /api/summary targets.ts GET /api/targets history.ts GET /api/targets/:id/history trend.ts GET /api/targets/:id/trend checker/ types.ts 类型定义 config-loader.ts YAML 配置解析与校验 store.ts SQLite 数据存储 fetcher.ts HTTP 拨测执行 command-runner.ts 命令行拨测执行 size.ts 大小单位解析 engine.ts 调度引擎（按 interval 分组的 es-toolkit groupBy + Semaphore 并发控制） expect/ http.ts HTTP 响应断言 command.ts 命令行输出断言 body.ts HTTP body 断言（JSONPath/XPath/CSS，类型判断使用 es-toolkit） failure.ts 失败信息类型 shared/ api.ts 前后端共享 TypeScript 类型 web/ Vite + React 前端 Dashboard components/ UI 组件（表格、分组、Drawer、状态条等） constants/ 常量定义（列配置、类型映射、排序/筛选/颜色阈值函数） hooks/ TanStack Query 数据层（useTargetDetail 集成轮询/条件查询） utils/ 前端工具函数 scripts/ 开发、构建和 smoke test 脚本 tests/ Bun test 测试 openspec/ OpenSpec 变更与规格文档 ``` ## 构建 executable ```bash bun run build ``` 构建流程： 1. 运行 `vite build`，输出前端资源到 `dist/web` 2. 生成临时 `.build/static-assets.ts`，嵌入 Vite 产物 3. 生成临时 `.build/server-entry.ts`，作为生产入口 4. 运行 `Bun.build({ compile })`，输出 `dist/dial-server` 运行 executable： ```bash ./dist/dial-server probes.yaml ``` ## 代码质量 ```bash bun run lint bun run format:check bun run format bun run check ``` - `check` 依次运行 `typecheck`、`lint`、`format:check` 和单元测试。 ## 测试 ```bash bun run check bun run verify ``` - `check` 适合日常开发，包含类型检查、lint、格式检查和单元测试。 - `verify` 先运行 `check`，再重新构建生产 executable 并运行 smoke test。 ## 前后端边界 前端只通过 HTTP 调用后端，API 路径为 `/api/*`。共享类型放在 `src/shared`，前端不得 import `src/server` 的运行时实现。 ## 后端开发指引 ### 架构概览 ``` 启动流程: dev.ts → readRuntimeConfig(cli args) → loadConfig(yaml) → ProbeStore(db) → ProbeEngine(store, targets) → startServer(store) 运行时: 定时器(tick) → ProbeEngine.probeGroup() → HTTP: fetcher.ts / Command: command-runner.ts → expect/*.ts 校验 → store.insertCheckResult() HTTP 请求: Request → app.ts(路由分发) → routes/*.ts(handler) → middleware.ts(参数校验) → helpers.ts(响应格式化) → Response ``` ### 库使用优先级 后端代码开发遵循严格的库选择顺序： | 优先级 | 来源 | 典型用途 | | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Bun 内置 API | `Bun.serve`、`bun:sqlite`、`Bun.spawn`、`Bun.file`、`Bun.YAML` | | 2 | es-toolkit | 类型判断（`isPlainObject`/`isNil`/`isEmptyObject`）、深度比较（`isEqual`）、错误判断（`isError`）、并发控制（`Semaphore`）、集合操作（`groupBy`） | | 3 | 标准 Web API | `Object.fromEntries`、`Headers`、`fetch`、`AbortController` | | 4 | 主流三方库 | cheerio（HTML 解析）、xpath + @xmldom/xmldom（XML 解析） | | 5 | 自行实现 | 仅在以上都无法满足时（如 `parseDuration`、`parseSize`、`evaluateJsonPath` 等专项逻辑） | ### API 路由开发 路由文件位于 `src/server/routes/`，每个端点一个文件。handler 函数签名统一为： ```typescript export function handleXxx(params, store: ProbeStore, method: string, mode: RuntimeMode): Response; ``` **请求处理流程**： 1. `app.ts` 的 `createFetchHandler` 作为总入口，根据 URL pattern 匹配路由 2. API 路由统一经过 `guardGetHead` 做方法检查（仅允许 GET/HEAD） 3. 各 handler 内部通过 `middleware.ts` 提供的 `validateTargetId`、`validateTimeRange`、`validatePagination` 做参数校验 4. 校验函数返回 `Response` 表示校验失败（直接返回），返回数据对象表示通过 5. 业务逻辑通过 `store` 查询数据，用 `helpers.ts` 的 `jsonResponse`、`mapCheckResult`、`formatDuration` 等格式化输出 **新增路由步骤**： 1. 在 `src/server/routes/` 下创建 `.ts` 2. 实现 handler 函数并 export 3. 在 `app.ts` 的 `handleApiRoute` 中注册路径匹配和调用 4. 在 `tests/server/app.test.ts` 中添加对应测试 ### 共享工具 - **`helpers.ts`**：跨路由共用的响应工具函数（`jsonResponse`、`createHeaders`、`createApiError`、`mapCheckResult`、`formatDuration`、`createHealthResponse`） - **`middleware.ts`**：API 参数校验函数（`guardGetHead`、`validateTargetId`、`validateTimeRange`、`validatePagination`） - **`static.ts`**：生产模式下的静态资源服务与 SPA fallback ### 类型定义规范 - **共享类型**以 `src/shared/api.ts` 为唯一源头，前后端共同引用 - 前端不得 `import src/server/` 下的任何文件 - **严格联合类型**优先于宽类型：如 `phase: "status" | "duration" | ...` 而非 `phase: string` - **后端内部扩展**：`checker/types.ts` 中 `CheckResult` 通过 `extends` 共享版本的 `ApiCheckResult` 增加 `targetName` 等内部字段 - 存储层类型（`StoredTarget`、`StoredCheckResult`）独立定义，与 API 类型分离 ### 数据存储规范 基于 `bun:sqlite`，WAL 模式运行，数据库文件位于配置的 `dataDir` 下。 **Statement 使用规范**： | 场景 | 方式 | 原因 | | -------------- | -------------------------------------- | ---------------------------------------- | | 单次读/写 | `this.db.query(sql).get()/all()/run()` | bun:sqlite 内置 statement 缓存，自动复用 | | 事务内多次复用 | `this.db.prepare(sql)` 缓存为局部变量 | 事务闭包中需要持有引用 | **查询优化**： - 避免 N+1 查询：批量场景优先用单次 SQL 聚合（GROUP BY、子查询 JOIN）+ 内存组装 - 新增批量查询方法时必须编写对应单元测试 - `getSummary()` 和 `GET /api/targets` 的响应组装已通过 `getLatestChecksMap` + `getAllTargetStats` 实现批量查询 **Schema**： - `targets` 表：name（UNIQUE）、type、target（展示摘要）、config（JSON）、interval_ms、timeout_ms、expect（JSON）、grp - `check_results` 表：target_id（FK CASCADE）、timestamp、matched（0/1）、duration_ms、status_detail、failure（JSON） - 复合索引：`(target_id, timestamp)` ### 拨测引擎 - **调度**：`ProbeEngine` 用 `es-toolkit/groupBy` 按 interval 分组，每组独立 `setInterval` 定时触发 - **并发控制**：`es-toolkit/Semaphore` 限制全局最大并发数（`maxConcurrentChecks`），`acquire()` 阻塞等待 - **Runner 选择**：`engine.runCheck()` 按 `target.type` 分发到 `runHttpCheck` 或 `runCommandCheck` - **超时控制**：HTTP 用 `AbortController`，Command 用 `setTimeout` + `proc.kill()` - **结果写入**：检查结果通过 `store.insertCheckResult()` 写入 SQLite，engine 通过 `targetNameToId` 缓存 name→id 映射 ### expect 断言系统 两层模型：**观测值收集** → **规则校验**。 **HTTP 校验流程**： ``` runHttpCheck → 收集观测(statusCode/headers/body/durationMs) → checkHttpExpect → status → duration → headers → body(可选) → 首个失败即停止，返回 CheckFailure ``` **Command 校验流程**： ``` runCommandCheck → 收集观测(exitCode/stdout/stderr/durationMs) → checkCommandExpect → exitCode → duration → stdout → stderr → 首个失败即停止 ``` **Body 规则类型**： - `contains`：文本包含匹配 - `regex`：正则表达式匹配 - `json`：JSONPath 提取 + 操作符比较（使用 `es-toolkit/isPlainObject` 区分纯值和操作符） - `css`：cheerio CSS 选择器 + 操作符比较 - `xpath`：XPath 节点提取 + 操作符比较 **操作符**：`equals`（深度比较，`es-toolkit/isEqual`）、`contains`、`match`（正则）、`empty`（`isNil`+`isEmptyObject`）、`exists`、`gte`/`lte`/`gt`/`lt` ### 错误模式 - **API 错误**：`{ error: "描述", status: }`，状态码 400/404/405/503 - **CheckFailure**：`{ kind: "error"|"mismatch", phase, path, expected?, actual?, message }` - **错误处理**：expect 校验失败记录首个失败原因；网络/超时/进程崩溃统一为 `kind:"error"` - **日志**：解析失败等非致命异常用 `console.warn`，启动失败用 `console.error` + `process.exit(1)` ### 测试规范 - 测试文件与源文件对应：`tests/server/checker/store.test.ts` ↔ `src/server/checker/store.ts` - 使用 `bun:test` 框架（`describe`/`test`/`expect`），测试数据库用临时目录 + `tmpdir()` - 新增 store 方法必须编写单元测试；新增 API 端点必须在 `app.test.ts` 中添加集成测试 - 测试后清理：`afterAll` 中 `store.close()` + `rm(tempDir, { recursive: true })` ## 前端样式规范 前端基于 TDesign React 构建UI，样式开发遵循以下优先级（从高到低）： 1. **使用 TDesign 组件**：布局、间距、排版优先使用 TDesign 组件（如 Space、Divider、Typography） 2. **使用 TDesign 组件 props**：通过组件的 props 参数控制外观（如 `theme`、`variant`、`size`） 3. **使用 TDesign CSS tokens**：颜色、间距、字体等使用 `--td-*` CSS 变量（如 `--td-success-color`、`--td-comp-margin-xxl`） 4. **在 styles.css 中定义 CSS 类**：无法通过上述方式满足的样式需求，集中定义在 `styles.css` 中 5. **自行开发组件**：仅在 TDesign 无法满足需求时自行开发 **红线**： - **严禁在组件中使用 `style` 属性内联调整样式** - **严禁通过 CSS 覆盖 TDesign 组件内部类名**（如 `.t-tab-panel`），如需定制使用组件的 `className` prop - **严禁使用 `!important`** - 颜色统一使用 TDesign CSS tokens（`--td-success-color`、`--td-error-color`、`--td-warning-color` 等），不使用硬编码色值 ## 已知限制 当前不做告警通知、数据自动清理、拨测目标动态增删、认证鉴权和分布式部署。Command 类型拨测不支持 Windows 环境。