图算法服务接口：错误类型要让调用方能行动

图算法服务接口错误类型要让调用方能行动图算法接口首先要说明图是有向还是无向、允许哪些权重、节点 ID 的范围以及不可达如何表示。空图不该 panic它可以返回空结果或参数错误取决于业务定义。不要无条件深拷贝整个图。深拷贝能隔离并发修改却可能在大图上造成明显成本。更常见的做法是调用方传入不可变快照或在构建阶段复制并明确所有权。var ErrNegativeEdge errors.New(存在负权边) func shortestPath(g Graph, start int) (Result, error) { if !g.HasNode(start) { return Result{}, ErrUnknownStart } if g.HasNegativeEdge() { return Result{}, ErrNegativeEdge } return dijkstra(g, start) }Dijkstra 遇到负边应拒绝负权环是 Bellman-Ford 等算法才需要检测的条件。错误应分为输入无效、不可达、取消与内部故障调用方据此选择提示、重试或告警。测试覆盖空图、孤立点、重复边、零权边、负边和并发读取的所有权约定。接口说明比“永远不出错”的承诺更有用。先约定结果而不是让调用方猜“不可达”不等同于内部错误。结果可以用单独的Reachable字段表示也可以返回明确的ErrUnreachable选择后要保持一致。不要用一个看似很大的距离值代替不可达因为真实路径代价可能恰好接近该值调用方也容易忘记判断。节点编号也应在入口处校验。若图实现允许稀疏 ID数组下标不能直接当作节点 ID 使用若只支持连续编号接口文档应明确范围。把这些检查留给算法内部往往会在深层循环里变成难定位的越界错误。所有权决定是否能并发读当调用方在算法运行期间修改邻接表即使算法本身没有写入也可能读到不一致数据。深拷贝能避免这个问题但不一定适合每次查询。更可控的做法是构建完成后把图视为不可变更新时创建新版本并切换引用。这样读取方不需要锁版本切换的边界也更清楚。验证时除正确性样例外可并发读取同一快照并在另一个版本上做更新确认旧请求始终读取旧快照。负边用例应验证函数在执行 Dijkstra 前就返回ErrNegativeEdge而不是计算出一个看似合理但错误的结果。3. 把资源上限放进接口约定图很大时算法的内存和运行时间也属于调用约定。服务端可以限制节点数、边数和单次查询的时间超出时返回可识别的资源错误而不是让 worker 一直占着 CPU。限制值要结合部署资源和业务场景设定文档中说明即可不必把它包装成算法本身的能力。如果调用方确实需要处理超大图可以提供离线任务或分批查询的入口。不要让同步接口偷偷转成长时间后台工作否则取消、重试和结果一致性都会变得含糊。评审时用接近上限的图跑一次检查超时后内存是否释放、日志是否能区分输入过大与算法错误。4. 结果格式要适合后续处理最短路接口如果只返回一个距离数组调用方要自己推断路径、不可达和版本信息。根据用途可以返回距离、前驱节点和图版本不需要路径时也不要强制构造它避免无谓内存。字段的含义保持稳定客户端升级才不会因为一个零值猜错结果。对路径过长的情况也要有边界。返回过多节点会放大网络传输和日志成本可以提供最大长度或只返回摘要并用明确标志说明发生了截断。错误和部分结果不能混在一个模糊的空数组里。