DiAL/DEVELOPMENT.md

DiAL 开发文档

本文档面向 DiAL 项目的开发者，介绍项目结构、构建流程、测试、代码规范等内容。

用户使用说明请参阅 README.md。

项目结构

src/
  server/
    app.ts          Bun HTTP 路由（API + 静态资源 + SPA fallback）
    config.ts       CLI 参数解析
    dev.ts          开发期启动入口
    server.ts       HTTP server 启动
    checker/
      types.ts          类型定义
      config-loader.ts  YAML 配置解析与校验
      store.ts          SQLite 数据存储
      fetcher.ts        HTTP 拨测执行
      command-runner.ts 命令行拨测执行
      size.ts           大小单位解析
      engine.ts         调度引擎（按 interval 分组、组内并发）
      expect/
        http.ts         HTTP 响应断言
        command.ts      命令行输出断言
        body.ts         HTTP body 断言（JSONPath/XPath/CSS）
        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

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：

./dist/dial-server probes.yaml

代码质量

bun run lint
bun run format:check
bun run format
bun run check

• check 依次运行 typecheck、lint、format:check 和单元测试。

测试

bun run check
bun run verify

• check 适合日常开发，包含类型检查、lint、格式检查和单元测试。
• verify 先运行 check，再重新构建生产 executable 并运行 smoke test。

前后端边界

前端只通过 HTTP 调用后端，API 路径为 /api/*。共享类型放在 src/shared，前端不得 import src/server 的运行时实现。

前端样式规范

前端基于 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 环境。