4.5 KiB

Raw Blame History

错误与容差策略

本文件记录跨 crate 的错误表达与数值容差约定。单个 crate 的错误枚举见其 error.rs 的文档。

错误表达

领域错误

每个有领域特定失败的 crate 定义自己的错误类型，命名与结构一致：

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum FooErrorKind {
    /// 每个变体描述一个调用方可能想要区分的具体条件。
    ReversedInterval,
    DuplicateResource,
    // ...
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FooError {
    kind: FooErrorKind,
    detail: Option<String>,
}

impl FooError {
    pub fn new(kind: FooErrorKind) -> Self;
    pub fn with_detail(self, detail: impl Into<String>) -> Self;
    pub fn kind(&self) -> FooErrorKind;
    pub fn detail(&self) -> Option<&str>;
}

impl fmt::Display for FooError { /* "kind" 或 "kind: detail" */ }
impl core::error::Error for FooError {}

约定：

ErrorKind 标注 #[non_exhaustive]，这样新增一个失败类别不会破坏下游的匹配。当前 15 个 ErrorKind 全部标注。
kind 可精确匹配，detail 供人阅读。 调用方按 kind 写恢复逻辑，把 detail 记入日志。detail 不参与匹配，因此其措辞可自由改动。
Display 输出 kind，有 detail 时追加 ": detail"。 这样日志行总是以类别开头。
实现 core::error::Error，以便错误可以嵌套为 source。当前 15 个错误类型全部实现。
不返回裸 String 或 Box<dyn Error> 作为公共错误。 前者无法匹配，后者丢失类别。私有辅助函数内部可以传 String 作为原因文本，但公开边界必须是枚举。apsis-scheduler 的 precedence_floor 是这种内部用法的实例：它私有的 String 最终填入公开的 TaskState::Infeasible { reason }。

通用错误

apsis-core::Error 与 ErrorKind 是通用兜底类型，携带粗粒度类别（InvalidInput、NotFound 等）。它不是各层的统一错误表面：没有任何层使用它，因为通用类别丢失了调用方需要的区分（InvalidInput 无法区分 "区间反向"与"重复标识"）。

它保留在这里有两个理由：给一个失败没有有趣结构的函数一个现成的返回类型；以及给工作区一个可扩展的兜底形状。新代码若失败有领域含义，应定义领域错误。

失败与"无值"的区分

Option 表示"没有值"是正常结果，不是错误。例如某个时刻在覆盖区间之外（Ephemeris::state_at 返回 None）、某个角度的正切无定义。
Result 表示操作因可诊断的原因失败。例如区间反向、资源重复、超出模型定义域。

判断标准：调用方是否需要知道为什么。若只需要知道"没有"，用 Option；若需要区分失败原因并据此恢复，用 Result。

数值容差

迭代收敛容差

迭代求解（开普勒方程、章动级数、射线追踪）用 crate 内的私有常量控制收敛：

crate	常量	值	含义
`apsis-kepler`	`TOLERANCE`	`1e-14`	偏近点角牛顿迭代的步长
`apsis-sgp4`	`KEPLER_TOLERANCE`	`1e-12`	开普勒方程迭代残差

这些值在浮点精度与迭代次数之间折中：取到接近 f64 的机器精度，同时保证迭代在有限步内收敛（各有对应的 MAX_ITERATIONS）。

对拍容差

对拍脚本的容差按物理量设定，而不是统一的数值：

量	容差
位置	< 1e-3 km
速度	< 1e-6 km/s
时间	< 1e-6 s
覆盖几何角度	1e-12 rad
覆盖面积、占比	相对 1e-12

容差设在"远高于观测到的偏差（通常在浮点精度量级），远低于模型本身的精度"之间。这样既能捕获半径写错、单位漏换算这类错误，又不会因最后一位浮点差异而误报。详见 validation/README.md 的容差表。

精确比较

不需要容差时应避免引入：整数索引、计数、布尔标志用精确相等；角度归约（wrap_to_pi）在边界上用半开区间，不引入 epsilon。浮点比较仅在量本身是连续近似时使用。

检查

各 crate 测试覆盖其错误的每个 kind，包括构造失败与恢复路径。
对拍脚本以退出码表达结果：0 通过、1 超差、2 缺输入。
cargo clippy -- -D warnings 保证没有 unwrap/expect 漏进库代码（工作区约定库代码不使用它们）。

4.5 KiB Raw Blame History Unescape Escape