Public Surface Grading

更新时间：2026-04-30

本文档基于当前 orion-error 0.8.x 代码，给公开 surface 做分级整理。

目标不是继续删除 API，而是固定下面四类边界：

1. 主路径 API
2. 观察面 API
3. 测试 / 适配器入口
4. 兼容保留 API

如果后续要继续提升到 9+，这份分级表应作为 public API review 的参考基线。

1. 主路径 API

这些 API 构成当前推荐主路径，应长期稳定保留：

• StructError<R>

• OperationContext::doing(...)

• OperationContext::at(...)

• with_context(...)

• with_source(...)

• StructErrorBuilder::source(...)

• report()

• render()

• identity_snapshot()

• exposure(...)

• source_err(...)

• conv_err()

• cli::print_error(...)

特征：

• README / tutorial / docs 主文档会优先描述它们
• 新业务代码默认优先使用它们
• 不应再为相同任务引入并列“主路径”

2. 观察面 API

这些 API 有明确价值，但更适合诊断、测试、观测、辅助断言：

• source_frames()
• root_cause_frame()
• source_payload()
• source_payload_kind()
• action_main()
• locator_main()
• target_path()
• render_redacted(...)
• render_user_debug()
• render_user_debug_redacted(...)

特征：

• 它们不是主传播 / 主构造入口
• 应在文档里明确属于 observation / diagnostics surface
• 不应在 quick start 中抢占主路径叙事位

3. 测试 / 适配器入口

这些 API 主要服务测试、schema 校验、中间层适配或协议拼装：

• ErrorProtocolSnapshot::from_report_skeleton(...)
• dev::prelude::*
• dev::testing::*
• interop::*
• runtime::source::*

特征：

• 允许公开存在
• 但应明确不是正常业务主路径
• 文档中应把它们描述成 secondary path
• 其中 dev::prelude::* 应保持在对象级检查面，不再扩成 frame 级宽导出

4. 兼容保留 API

这些字段或投影仍然有现实兼容价值，但名字本身带有历史包袱：

• context / snapshot frame 中的 target

当前统一口径：

• runtime 主语义应优先理解为 action / locator / path segments
• target 继续存在，主要作为 compat projection
• path 是稳定导出的路径投影

5. 当前结论

当前 orion-error 的主要结构问题已经不是“大量兼容 API 混在主路径里”，而是：

• 少量 compat projection 字段仍公开存在
• 少量 observation / secondary path 仍需要靠文档说明降级

这意味着下一阶段如果要继续打磨：

• 不应再优先做内部模型重写
• 应优先做 public surface review 与分级锁定

6. 后续建议

如果进入下一个版本线，可以按这个顺序评估：

1. 是否继续保留 frame 中的 target
2. 是否需要继续缩窄 dev::prelude::*
3. 是否要给 observation / adapter API 增加更明确的模块或命名提示

在没有明确版本策略前，当前更合理的做法是：

• 保持主路径稳定
• 保持观察面可用
• 用文档和测试锁住 secondary / compat 的定位