refactor: 后端架构加固 — 泛型化、批量查询、bootstrap 统一、路径修复与 pageSize 上限
- CheckerDefinition 泛型化，HTTP/Command checker 移除 resolved target 断言 - 新增 ProbeStore.getAllRecentSamples 消除 targets 路由 N+1 查询 - 统一 getAllTargetStats 与 getTargetStats 的 availability 精度 - Engine rejected 结果写入 internal error 记录，提升可观测性 - 新增 bootstrap.ts 统一 dev/production 启动序列 - dataDir 相对路径改为基于配置文件目录解析 - validatePagination 增加 pageSize 上限 200 校验 - 修复 ErrorBoundary override 标记 - 更新 README/DEVELOPMENT 文档，新增完整测试覆盖
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-13
|
||||
121
openspec/changes/backend-architecture-hardening/design.md
Normal file
121
openspec/changes/backend-architecture-hardening/design.md
Normal file
@@ -0,0 +1,121 @@
|
||||
## Context
|
||||
|
||||
DiAL 后端是基于 Bun 的拨测服务，当前有 2 个 checker 类型（http、command），target 规模预计增长到 100，checker 类型预计超过 5 种。
|
||||
|
||||
现状问题：
|
||||
1. `GET /api/targets` 对每个 target 单独查询 `getRecentSamples`，产生 N+3 次 SQL 查询
|
||||
2. `ProbeEngine.probeGroup` 中 rejected 结果仅 `console.warn`，前端无法感知异常
|
||||
3. `dev.ts` 和 `scripts/build.ts` 生成的 entry 各自维护相同的启动序列
|
||||
4. `config-loader.ts` 中 `dataDir` 未基于 `configDir` 解析，相对路径依赖进程 cwd
|
||||
5. `validatePagination` 无 pageSize 上限，可被滥用
|
||||
6. `CheckerDefinition` 接口方法参数为 `ResolvedTargetBase`，checker 内部需手动 `as` 断言
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 消除 targets 路由的 N+1 查询，支撑 100 target 规模
|
||||
- Engine 异常可观测：rejected 结果写入数据库，前端可见
|
||||
- 启动逻辑单一来源，降低维护成本
|
||||
- 修复 dataDir 路径解析 bug
|
||||
- API 防御性：pageSize 上限
|
||||
- CheckerDefinition 泛型化，checker 开发者获得编译期类型安全
|
||||
|
||||
**Non-Goals:**
|
||||
- 不做配置热更新
|
||||
- 不做 API 认证/鉴权
|
||||
- 不做通知/告警系统
|
||||
- 不改变 `ResolvedTargetBase` 的 index signature（registry 层仍用类型擦除）
|
||||
- 不改变前端行为
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: 批量查询 recentSamples 使用 window function
|
||||
|
||||
**选择**：在 `ProbeStore` 中新增 `getAllRecentSamples(limit: number)` 方法，使用 SQLite window function `ROW_NUMBER() OVER (PARTITION BY target_id ORDER BY timestamp DESC)` 一次查询所有 target 的最近 N 条采样。
|
||||
|
||||
**替代方案**：
|
||||
- UNION ALL 拼接每个 target 的子查询 → SQL 长度随 target 数线性增长，不可控
|
||||
- 应用层批量（一次查全部再内存分组）→ 数据量大时内存开销高
|
||||
|
||||
**理由**：window function 是 SQLite 3.25+ 原生支持的特性，Bun 内置的 SQLite 版本满足要求。单次查询，SQL 固定长度，性能最优。
|
||||
|
||||
### Decision 2: Engine rejected 写入 internal error 记录
|
||||
|
||||
**选择**：在 `probeGroup` 中，对 `rejected` 的结果构造一条 `matched: false`、`failure: { kind: "error", phase: "internal", path: "engine", message: reason }` 的 check_result 写入 store。
|
||||
|
||||
**替代方案**：
|
||||
- 单独的错误日志表 → 增加 schema 复杂度，前端需要额外查询
|
||||
- 仅保留 console.warn → 现状，不可观测
|
||||
|
||||
**理由**：复用现有 check_results 表和 failure 结构，前端无需改动即可展示异常状态。`phase: "internal"` 区分于正常的 checker 执行失败。通过 `Promise.allSettled` 的索引关联回 target 数组，确保能获取 targetName。
|
||||
|
||||
### Decision 3: 抽取 bootstrap.ts
|
||||
|
||||
**选择**：新增 `src/server/bootstrap.ts`，导出 `bootstrap(options: BootstrapOptions)` 函数，封装完整启动序列：loadConfig → ProbeStore → syncTargets → ProbeEngine → startServer → 注册 shutdown handler。
|
||||
|
||||
**接口设计**：
|
||||
```typescript
|
||||
interface BootstrapOptions {
|
||||
configPath: string;
|
||||
mode: RuntimeMode;
|
||||
staticAssets?: StaticAssets;
|
||||
}
|
||||
```
|
||||
|
||||
`dev.ts` 调用 `bootstrap({ configPath, mode: "development" })`。
|
||||
`build.ts` 生成的 entry 调用 `bootstrap({ configPath, mode: "production", staticAssets })`。
|
||||
|
||||
**替代方案**：
|
||||
- 保持两处重复 → 维护负担随启动逻辑复杂化线性增长
|
||||
|
||||
### Decision 4: dataDir 基于 configDir 解析
|
||||
|
||||
**选择**：在 `config-loader.ts` 的 `loadConfig` 中，对 `dataDir` 使用 `resolve(configDir, dataDir)` 处理。如果 `dataDir` 是绝对路径，`resolve` 会直接返回绝对路径，不影响绝对路径用户。
|
||||
|
||||
**影响**：行为变更——之前相对路径基于 cwd，现在基于配置文件目录。由于项目未上线，无需向前兼容。
|
||||
|
||||
### Decision 5: pageSize 上限 200
|
||||
|
||||
**选择**：在 `middleware.ts` 的 `validatePagination` 中增加 `pageSize > 200` 的校验，返回 400。
|
||||
|
||||
**常量定义**：`MAX_PAGE_SIZE = 200`，定义在 `middleware.ts` 中。
|
||||
|
||||
**理由**：200 条/页对于拨测历史记录的展示场景足够。前端当前使用 20，不受影响。
|
||||
|
||||
### Decision 6: CheckerDefinition 泛型化
|
||||
|
||||
**选择**：
|
||||
|
||||
```typescript
|
||||
interface CheckerDefinition<TResolved extends ResolvedTargetBase = ResolvedTargetBase> {
|
||||
execute(target: TResolved, ctx: CheckerContext): Promise<CheckResult>;
|
||||
resolve(target: RawTargetConfig, context: ResolveContext): TResolved;
|
||||
serialize(target: TResolved): { config: string; target: string };
|
||||
validate(input: CheckerValidationInput): ConfigValidationIssue[];
|
||||
readonly configKey: string;
|
||||
readonly schemas: CheckerSchemas;
|
||||
readonly type: string;
|
||||
}
|
||||
```
|
||||
|
||||
- 默认泛型参数 `= ResolvedTargetBase` 保证 registry 等中间层无需指定泛型
|
||||
- `CheckerRegistry` 内部存储 `CheckerDefinition<ResolvedTargetBase>`（类型擦除）
|
||||
- 各 checker 实现 `implements CheckerDefinition<ResolvedHttpTarget>` 等具体类型
|
||||
- checker 内部 `execute`、`serialize` 方法直接接收具体类型，无需 `as` 断言
|
||||
|
||||
**替代方案**：
|
||||
- Discriminated union → 每加 checker 改 union，违背插件化设计
|
||||
- 维持现状 → 5+ checker 时 `as` 断言散落各处
|
||||
|
||||
**影响范围**：
|
||||
- `runner/types.ts`：接口加泛型参数
|
||||
- `runner/registry.ts`：内部 Map 类型为 `CheckerDefinition`（使用默认参数）
|
||||
- `http/execute.ts`、`command/execute.ts`：`implements CheckerDefinition<具体类型>`，移除方法内的 `as` 断言
|
||||
- `engine.ts`、`config-loader.ts`、`store.ts`：不变（依赖 base interface）
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **window function 兼容性** → Bun 内置 SQLite >= 3.25，已验证支持。如果未来需要外部 SQLite，需确认版本。
|
||||
- **Engine rejected 写入依赖索引关联** → 通过 `Promise.allSettled` 的索引关联回 target 数组获取 targetName。前提是 `probeGroup` 的 targets 数组与 `Promise.allSettled` 结果数组保持一一对应，当前实现满足此条件。
|
||||
- **bootstrap.ts 增加一层间接** → 启动流程从 2 处直接代码变为 1 处函数调用。复杂度不增加，只是位置移动。
|
||||
- **泛型擦除在 registry 层** → `registry.get()` 返回 `CheckerDefinition`（base 类型），engine 调用时仍是 base 类型。这是设计意图：中间层不感知具体 checker 类型。
|
||||
34
openspec/changes/backend-architecture-hardening/proposal.md
Normal file
34
openspec/changes/backend-architecture-hardening/proposal.md
Normal file
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
后端在 target 规模增长（预计到 100）和 checker 类型扩展（预计超过 5 种）的趋势下，存在查询性能瓶颈、可观测性盲区、启动逻辑重复、路径解析 bug 和类型安全不足等问题。本次变更集中修复这些架构短板，为后续扩展打好基础。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **targets 路由 N+1 查询优化**：`handleTargets` 中对每个 target 单独调用 `getRecentSamples` 改为批量查询，消除 N 次独立 SQL
|
||||
- **Engine rejected 结果持久化**：`probeGroup` 中 `Promise.allSettled` 的 rejected 结果写入 `matched: false` 的 check_result（failure 标记为 internal error），替代仅 `console.warn`
|
||||
- **启动逻辑统一**：抽取 `bootstrap.ts`，`dev.ts` 和 build 生成的 entry 共用同一启动序列，消除重复
|
||||
- **dataDir 相对路径修复**：`config-loader.ts` 中用 `resolve(configDir, dataDir)` 处理相对路径，确保从任意 cwd 启动时数据库位置一致
|
||||
- **validatePagination 加 pageSize 上限**：限制最大 pageSize 为 200，超出返回 400
|
||||
- **CheckerDefinition 泛型化**：为 `CheckerDefinition` 加泛型参数 `<TResolved extends ResolvedTargetBase>`，checker 内部获得完整类型安全，registry 用类型擦除保持解耦
|
||||
- **availability 精度统一**：`getAllTargetStats` 和 `getTargetStats` 的 availability 计算精度不一致，统一为相同的四舍五入策略
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `server-bootstrap`: 统一的服务启动引导流程，dev 和 production 共用
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `batch-data-queries`: 新增 `getAllRecentSamples` 批量采样查询，消除 targets 路由的 N+1 问题；修复 availability 精度不一致
|
||||
- `probe-engine`: Engine 对 rejected 结果写入 matched:false 记录而非静默丢弃
|
||||
- `probe-config`: dataDir 相对路径基于 configDir 解析
|
||||
- `probe-api`: validatePagination 增加 pageSize 上限校验
|
||||
- `checker-runner-abstraction`: CheckerDefinition 接口泛型化，checker 内部类型安全
|
||||
|
||||
## Impact
|
||||
|
||||
- **代码**：`src/server/` 下约 8 个文件变更，新增 `bootstrap.ts` 和 `store.ts` 的批量查询方法；另修复 `src/web/components/ErrorBoundary.tsx` 的 `override` 标记（typecheck 前置修复）
|
||||
- **API**：pageSize 超过 200 时返回 400（新增约束，当前前端未使用超大 pageSize）
|
||||
- **构建**：`scripts/build.ts` 生成的 entry 改为调用 bootstrap
|
||||
- **测试**：需新增/更新 engine、store、middleware、bootstrap 相关测试
|
||||
@@ -0,0 +1,44 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 批量查询所有目标的最近采样数据
|
||||
系统 SHALL 提供 `getAllRecentSamples(limit: number)` 方法，通过单次 SQL 查询获取所有 target 的最近 N 条采样数据，返回 `Map<number, Array<{ timestamp: string; duration_ms: number | null; matched: number }>>` 结构。
|
||||
|
||||
#### Scenario: 获取所有目标的最近采样
|
||||
- **WHEN** 调用 `getAllRecentSamples(30)`
|
||||
- **THEN** 系统 SHALL 通过单次 SQL 查询获取每个 target 最近 30 条记录，返回按 target_id 索引的 Map
|
||||
|
||||
#### Scenario: 目标无历史记录
|
||||
- **WHEN** 某 target 在 check_results 表中无任何记录
|
||||
- **THEN** 该 target_id 在返回的 Map 中 SHALL 不存在对应的 key
|
||||
|
||||
#### Scenario: 采样数据排序
|
||||
- **WHEN** 获取采样数据
|
||||
- **THEN** 每个 target 的记录 SHALL 按 timestamp 降序排列（最新在前）
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: targets 列表使用批量方法
|
||||
`handleTargets`（routes/targets.ts 中生成 TargetStatus[] 的逻辑）SHALL 使用 `getLatestChecksMap`、`getAllTargetStats` 和 `getAllRecentSamples` 替代逐目标查询，消除 N+1 查询。
|
||||
|
||||
#### Scenario: 目标列表使用批量查询
|
||||
- **WHEN** 处理 `GET /api/targets` 请求
|
||||
- **THEN** 系统 SHALL 分别调用 `getLatestChecksMap()`、`getAllTargetStats()`、`getAllRecentSamples(30)` 批量获取数据，在内存中组装 TargetStatus 数组，而非对每个 target 逐条查询数据库
|
||||
|
||||
#### Scenario: 目标无采样数据
|
||||
- **WHEN** 某 target 在 getAllRecentSamples 返回的 Map 中不存在
|
||||
- **THEN** 该 target 的 recentSamples SHALL 为空数组
|
||||
|
||||
### Requirement: 批量查询目标统计
|
||||
系统 SHALL 提供 `getAllTargetStats` 方法，通过单次 SQL GROUP BY 聚合查询获取所有 target 的拨测统计（totalChecks 和 availability）。availability 计算精度 SHALL 与 `getTargetStats` 一致，统一使用 `Math.round(value * 100) / 100` 保留两位小数。
|
||||
|
||||
#### Scenario: 获取所有目标的聚合统计
|
||||
- **WHEN** 调用 `getAllTargetStats()`
|
||||
- **THEN** 系统 SHALL 执行单次 GROUP BY 聚合查询，在内存中计算 availability 并返回 `Map<number, { totalChecks, availability }>`
|
||||
|
||||
#### Scenario: availability 精度
|
||||
- **WHEN** 计算 availability（upCount / totalChecks * 100）
|
||||
- **THEN** 结果 SHALL 使用 `Math.round(value * 100) / 100` 四舍五入保留两位小数，与 `getTargetStats` 方法一致
|
||||
|
||||
#### Scenario: 目标无历史记录
|
||||
- **WHEN** 某 target 在 check_results 表中无任何记录
|
||||
- **THEN** 该 target_id 在返回的 Map 中 SHALL 不存在对应的 key
|
||||
@@ -0,0 +1,47 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Checker 接口定义
|
||||
系统 SHALL 在 `src/server/checker/runner/types.ts` 中定义面向扩展的泛型 `CheckerDefinition<TResolved extends ResolvedTargetBase = ResolvedTargetBase>`，包含 `type`、`configKey`、TypeBox 配置契约、启动期语义校验、`resolve`、`execute`、`serialize` 成员。泛型参数 SHALL 约束 `execute` 和 `serialize` 方法的 target 参数类型，使 checker 实现内部获得编译期类型安全。默认泛型参数 `= ResolvedTargetBase` 保证中间层（registry、engine、config-loader）无需指定泛型。
|
||||
|
||||
#### Scenario: Checker 接口包含必要方法
|
||||
- **WHEN** 开发者实现一个新的 Checker
|
||||
- **THEN** 该实现 MUST 提供 `type`（字符串标识）、`configKey`（配置分组名）、TypeBox 配置契约、启动期语义校验、`resolve(target, context): TResolved`（解析配置并填充默认值）、`execute(target: TResolved, ctx)`（执行探测返回 CheckResult）和 `serialize(target: TResolved)`（返回 target 展示文本和 config JSON）
|
||||
|
||||
#### Scenario: CheckerContext 注入 signal
|
||||
- **WHEN** 引擎调用 `checker.execute(target, ctx)`
|
||||
- **THEN** `ctx.signal` SHALL 是一个由引擎创建的 `AbortSignal`，在超时或引擎关闭时 abort
|
||||
|
||||
#### Scenario: resolve 不承担通用契约校验
|
||||
- **WHEN** config-loader 调用 checker.resolve()
|
||||
- **THEN** checker.resolve() SHALL 假定配置已经通过 TypeBox/Ajv 契约校验和启动期语义校验，只负责默认值填充、路径解析和领域配置转换
|
||||
|
||||
#### Scenario: 接口方法使用泛型约束
|
||||
- **WHEN** 开发者查看 `CheckerDefinition<TResolved>` 接口签名
|
||||
- **THEN** `resolve` 的返回值 SHALL 为 `TResolved`；`execute` 的参数 SHALL 为 `TResolved`；`serialize` 的参数 SHALL 为 `TResolved`
|
||||
|
||||
#### Scenario: checker 实现无需手动断言
|
||||
- **WHEN** HttpChecker 实现 `CheckerDefinition<ResolvedHttpTarget>`
|
||||
- **THEN** `execute` 方法的 target 参数类型 SHALL 直接为 `ResolvedHttpTarget`，无需在方法内部使用 `as` 类型断言
|
||||
|
||||
#### Scenario: registry 使用默认泛型参数
|
||||
- **WHEN** CheckerRegistry 存储和返回 checker 实例
|
||||
- **THEN** registry 内部 SHALL 使用 `CheckerDefinition`（等价于 `CheckerDefinition<ResolvedTargetBase>`），实现类型擦除
|
||||
|
||||
### Requirement: CheckerRegistry 注册中心
|
||||
系统 SHALL 在 `src/server/checker/runner/registry.ts` 中提供 `CheckerRegistry` 类，支持 `register(checker)`、`get(type)` 和 `supportedTypes`。重复注册同一 type SHALL 抛出错误。registry 内部 SHALL 存储 `CheckerDefinition`（使用默认泛型参数），对外提供类型擦除后的接口。
|
||||
|
||||
#### Scenario: 注册并获取 Checker
|
||||
- **WHEN** 调用 `registry.register(new HttpChecker())` 后再调用 `registry.get("http")`
|
||||
- **THEN** 返回的 SHALL 是之前注册的 HttpChecker 实例（类型为 `CheckerDefinition`）
|
||||
|
||||
#### Scenario: 获取未注册的 type
|
||||
- **WHEN** 调用 `registry.get("unknown")` 且未注册对应 type 的 checker
|
||||
- **THEN** 系统 SHALL 抛出错误，提示不支持的 probe type
|
||||
|
||||
#### Scenario: 重复注册
|
||||
- **WHEN** 同一 type 值被重复 `register()`
|
||||
- **THEN** 系统 SHALL 抛出错误，提示该 type 已注册
|
||||
|
||||
#### Scenario: 查询支持的 type 列表
|
||||
- **WHEN** 注册了 "http" 和 "command" 两个 checker 后查询 `registry.supportedTypes`
|
||||
- **THEN** 返回的数组 SHALL 包含 `["http", "command"]`（按注册顺序）
|
||||
@@ -0,0 +1,32 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: API 错误处理
|
||||
系统 SHALL 对不存在的目标 ID、无效参数和超出范围的分页参数返回适当的 HTTP 错误响应。
|
||||
|
||||
#### Scenario: 查询不存在的目标
|
||||
- **WHEN** 客户端请求 `GET /api/targets/999/history`
|
||||
- **THEN** 系统 SHALL 返回 404 状态码和错误信息
|
||||
|
||||
#### Scenario: 无效的 from/to 参数
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/history?from=invalid`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: 无效的分页参数
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/history?from=ISO&to=ISO&page=abc`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: pageSize 超过上限
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/history?from=ISO&to=ISO&pageSize=201`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息，提示 pageSize 不能超过 200
|
||||
|
||||
#### Scenario: pageSize 等于上限
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/history?from=ISO&to=ISO&pageSize=200`
|
||||
- **THEN** 系统 SHALL 正常返回数据
|
||||
|
||||
#### Scenario: from 或 to 参数缺失
|
||||
- **WHEN** 客户端请求 `GET /api/targets/1/trend` 未提供 from 或 to 参数
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
|
||||
#### Scenario: 无效的目标 ID
|
||||
- **WHEN** 客户端请求 `GET /api/targets/abc/history`
|
||||
- **THEN** 系统 SHALL 返回 400 状态码和错误信息
|
||||
@@ -0,0 +1,16 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 数据目录路径解析
|
||||
配置加载流程 SHALL 将 `server.dataDir` 相对路径基于配置文件所在目录（configDir）解析为绝对路径。绝对路径 SHALL 保持不变。
|
||||
|
||||
#### Scenario: dataDir 为相对路径
|
||||
- **WHEN** 配置文件位于 `/opt/dial/probes.yaml`，且 `server.dataDir` 配置为 `./data`
|
||||
- **THEN** 系统 SHALL 将 dataDir 解析为 `/opt/dial/data`，而非依赖进程 cwd
|
||||
|
||||
#### Scenario: dataDir 为绝对路径
|
||||
- **WHEN** `server.dataDir` 配置为 `/var/lib/dial/data`
|
||||
- **THEN** 系统 SHALL 直接使用该绝对路径，不做额外解析
|
||||
|
||||
#### Scenario: dataDir 使用默认值
|
||||
- **WHEN** 未配置 `server.dataDir`（使用默认值 `./data`）
|
||||
- **THEN** 系统 SHALL 将默认值 `./data` 基于 configDir 解析为绝对路径
|
||||
@@ -0,0 +1,24 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 组内并发拨测
|
||||
系统 SHALL 在每次调度 tick 时并发执行同组内目标的检查，但实际同时运行的检查数 MUST 受全局 `runtime.maxConcurrentChecks` 限制。当某个目标的 checker 执行 rejected（非正常 CheckResult 返回，而是 Promise reject）时，系统 SHALL 将该异常记录为 `matched: false` 的 check_result，而非仅 console.warn。
|
||||
|
||||
#### Scenario: 同组目标并发执行
|
||||
- **WHEN** 调度器触发一次 tick，该组有 3 个目标，且全局并发余量至少为 3
|
||||
- **THEN** 系统 SHALL 同时执行 3 个 checker，而非顺序执行
|
||||
|
||||
#### Scenario: 单个目标失败不影响同组其他目标
|
||||
- **WHEN** 同组中某个目标的检查请求超时或失败（checker 正常返回 CheckResult）
|
||||
- **THEN** 其他目标的检查 SHALL 正常完成并记录结果
|
||||
|
||||
#### Scenario: 同组中某个目标的 checker 执行 rejected
|
||||
- **WHEN** 同组中某个目标的 checker 执行抛出未捕获异常（Promise rejected）
|
||||
- **THEN** 系统 SHALL 为该目标写入一条 `matched: false` 的 check_result，failure 为 `{ kind: "error", phase: "internal", path: "engine", message: <rejected reason> }`，其他目标的检查 SHALL 不受影响
|
||||
|
||||
#### Scenario: rejected 结果通过索引关联 targetName
|
||||
- **WHEN** checker 执行 rejected
|
||||
- **THEN** 系统 SHALL 通过 Promise.allSettled 的索引关联回 target 数组，获取对应的 targetName 用于写入 check_result
|
||||
|
||||
#### Scenario: 全局并发限制生效
|
||||
- **WHEN** 调度器同时触发 10 个目标且 runtime.maxConcurrentChecks 为 3
|
||||
- **THEN** 系统 MUST 同时最多运行 3 个检查，其余检查等待并发槽位释放
|
||||
@@ -0,0 +1,38 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 统一启动引导函数
|
||||
系统 SHALL 提供 `src/server/bootstrap.ts` 导出 `bootstrap(options: BootstrapOptions)` 函数，封装完整的服务启动序列：加载配置、创建 store、同步 targets、创建并启动 engine、启动 HTTP server、注册 shutdown handler。
|
||||
|
||||
#### Scenario: 开发模式启动
|
||||
- **WHEN** `dev.ts` 调用 `bootstrap({ configPath, mode: "development" })`
|
||||
- **THEN** 系统 SHALL 完成完整启动序列，不传入 staticAssets
|
||||
|
||||
#### Scenario: 生产模式启动
|
||||
- **WHEN** build entry 调用 `bootstrap({ configPath, mode: "production", staticAssets })`
|
||||
- **THEN** 系统 SHALL 完成完整启动序列，并将 staticAssets 传递给 startServer
|
||||
|
||||
#### Scenario: 启动失败处理
|
||||
- **WHEN** 启动过程中任何步骤抛出异常
|
||||
- **THEN** 系统 SHALL 输出错误信息并以非零退出码退出进程
|
||||
|
||||
#### Scenario: 优雅关机
|
||||
- **WHEN** 进程收到 SIGINT 或 SIGTERM 信号
|
||||
- **THEN** bootstrap 注册的 shutdown handler SHALL 调用 engine.stop() 和 store.close() 后退出
|
||||
|
||||
### Requirement: BootstrapOptions 接口
|
||||
`bootstrap` 函数 SHALL 接受 `BootstrapOptions` 参数，包含 `configPath: string`、`mode: RuntimeMode`、`staticAssets?: StaticAssets`。
|
||||
|
||||
#### Scenario: 最小配置
|
||||
- **WHEN** 仅传入 configPath 和 mode
|
||||
- **THEN** 系统 SHALL 正常启动，staticAssets 为 undefined
|
||||
|
||||
### Requirement: dev.ts 和 build entry 使用 bootstrap
|
||||
`dev.ts` 和 `scripts/build.ts` 生成的 server entry SHALL 调用 `bootstrap()` 而非各自维护启动序列。
|
||||
|
||||
#### Scenario: dev.ts 调用 bootstrap
|
||||
- **WHEN** 开发者运行 `bun run dev:server`
|
||||
- **THEN** `dev.ts` SHALL 调用 `bootstrap` 完成启动
|
||||
|
||||
#### Scenario: build entry 调用 bootstrap
|
||||
- **WHEN** 生产可执行文件启动
|
||||
- **THEN** 生成的 entry SHALL 调用 `bootstrap` 完成启动
|
||||
42
openspec/changes/backend-architecture-hardening/tasks.md
Normal file
42
openspec/changes/backend-architecture-hardening/tasks.md
Normal file
@@ -0,0 +1,42 @@
|
||||
## 1. CheckerDefinition 泛型化
|
||||
|
||||
- [x] 1.1 修改 `src/server/checker/runner/types.ts`：为 CheckerDefinition 接口添加泛型参数 `<TResolved extends ResolvedTargetBase = ResolvedTargetBase>`，约束 execute、resolve、serialize 方法的 target 参数类型
|
||||
- [x] 1.2 修改 `src/server/checker/runner/registry.ts`：内部 Map 类型使用 `CheckerDefinition`（默认泛型参数），确保类型擦除
|
||||
- [x] 1.3 修改 `src/server/checker/runner/http/execute.ts`：HttpChecker 实现 `CheckerDefinition<ResolvedHttpTarget>`，移除 execute/serialize 方法内的 `as ResolvedHttpTarget` 断言（resolve 方法内对 RawTargetConfig 的断言保留，泛型不覆盖输入参数窄化）
|
||||
- [x] 1.4 修改 `src/server/checker/runner/command/execute.ts`：CommandChecker 实现 `CheckerDefinition<ResolvedCommandTarget>`，移除 execute/serialize 方法内的 `as ResolvedCommandTarget` 断言（resolve 方法内对 RawTargetConfig 的断言保留）
|
||||
- [x] 1.5 修复 `src/web/components/ErrorBoundary.tsx` 的 `override` 标记（`noImplicitOverride` 规则要求的既有代码修复），运行 `bun run typecheck` 确认类型系统无错误
|
||||
|
||||
## 2. ProbeStore 批量查询优化
|
||||
|
||||
- [x] 2.1 在 `src/server/checker/store.ts` 中新增 `getAllRecentSamples(limit: number)` 方法，使用 `ROW_NUMBER() OVER (PARTITION BY target_id ORDER BY timestamp DESC)` 实现单次批量查询
|
||||
- [x] 2.2 修改 `src/server/checker/store.ts` 中 `getAllTargetStats` 的 availability 计算：将 `Math.round((row.upCount / row.totalChecks) * 10000) / 100` 改为 `Math.round((row.upCount / row.totalChecks) * 100 * 100) / 100`，与 `getTargetStats` 精度一致
|
||||
- [x] 2.3 修改 `src/server/routes/targets.ts`：`handleTargets` 使用 `store.getAllRecentSamples(30)` 替代循环调用 `store.getRecentSamples`
|
||||
- [x] 2.4 在 `tests/server/checker/store.test.ts` 中新增 `getAllRecentSamples` 的单元测试和 availability 精度一致性测试
|
||||
|
||||
## 3. Engine rejected 结果持久化
|
||||
|
||||
- [x] 3.1 修改 `src/server/checker/engine.ts`：`probeGroup` 中对 rejected 结果通过索引关联 target，构造 `matched: false`、`failure: { kind: "error", phase: "internal", path: "engine", message }` 的 check_result 写入 store
|
||||
- [x] 3.2 在 `tests/server/checker/engine.test.ts` 中新增 rejected 结果写入的测试用例
|
||||
|
||||
## 4. 启动逻辑统一
|
||||
|
||||
- [x] 4.1 新增 `src/server/bootstrap.ts`，导出 `bootstrap(options: BootstrapOptions)` 函数，封装 loadConfig → ProbeStore → syncTargets → ProbeEngine → startServer → shutdown handler 完整序列
|
||||
- [x] 4.2 修改 `src/server/dev.ts`：改为调用 `bootstrap({ configPath, mode: "development" })`
|
||||
- [x] 4.3 修改 `scripts/build.ts`：生成的 server entry 改为调用 `bootstrap({ configPath, mode: "production", staticAssets })`
|
||||
- [x] 4.4 在 `tests/server/` 中新增 bootstrap 相关测试
|
||||
|
||||
## 5. dataDir 路径修复
|
||||
|
||||
- [x] 5.1 修改 `src/server/checker/config-loader.ts`：对 dataDir 使用 `resolve(configDir, dataDir)` 处理相对路径
|
||||
- [x] 5.2 在 `tests/server/checker/config-loader.test.ts` 中新增 dataDir 路径解析的测试用例
|
||||
|
||||
## 6. pageSize 上限
|
||||
|
||||
- [x] 6.1 修改 `src/server/middleware.ts`：`validatePagination` 增加 `pageSize > 200` 的校验，返回 400
|
||||
- [x] 6.2 在 `tests/server/app.test.ts` 中新增 pageSize 超限的测试用例
|
||||
|
||||
## 7. 质量保障与文档
|
||||
|
||||
- [x] 7.1 运行 `bun run check`（schema:check + typecheck + lint + test）确认全部通过
|
||||
- [x] 7.2 运行 `bun run build` 确认构建成功
|
||||
- [x] 7.3 更新 DEVELOPMENT.md 中相关章节（bootstrap 启动流程、CheckerDefinition 泛型说明、pageSize 上限说明）
|
||||
Reference in New Issue
Block a user