接口错误应说明失败发生在哪类环节、该请求是否已生效,以及下一步由谁处理。返回状态、业务错误代码和可追踪编号需要共同约定,教师看到的是简明操作建议,技术人员获得定位信息。不能把所有异常都提示为请重试,也不应在用户页面暴露密钥或内部配置。
按处理方式划分错误类别
身份无效、人员未匹配、字段缺失、权限不足和服务暂不可用,需要不同处理。错误分类应帮助调用方决定刷新身份、修正数据、申请授权还是稍后处理,而不只是提供一串没有解释的编号。
同样重要的是说明当前请求是否已经保存。对于提交状态不确定的情况,应提供查询或核验路径,避免调用方重新生成记录。技术失败与教学业务状态也需分开,例如待教师复核并不等于接口故障。
让用户提示与技术信息各有用途
学生或教师需要知道当前任务是否保留、能否离开以及应联系谁。提示应对应实际状态,不能在后台保存失败时仍显示成功,也不能要求使用者理解数据库错误才能继续操作。
技术日志保留关联编号、接口名称和必要原因,支持人员可据此查找完整记录。用户可见信息不应包含连接串、令牌或详细内部路径;反馈截图也只需包含定位所必需的内容。
验证错误、恢复和兼容处理
为主要错误准备测试样本,检查双方是否按约定识别代码并采取正确动作。新增错误类型时说明旧客户端如何处理未知值,不能因无法识别就默认成功或无限重试。
错误修复后用原业务记录核对是否完成,保留待处理和已解决状态。定期查看高频错误,判断是资料质量、接口约定还是使用说明问题,并把可预防的事项前移到输入校验或培训。
实施检查清单
- 错误类别对应明确处理动作。
- 失败响应说明记录是否已生效。
- 用户提示与技术定位信息分开。
- 未知错误和恢复流程经过核验。
常见问题
统一提示操作失败是否更简单?
开发上可能简单,但使用者无法判断下一步,支持人员也难定位。应提供适当分类与关联信息。
接口出现错误是否都应该自动重试?
不应。资料缺失和权限问题需要先修正,只有满足约定条件的暂时错误才适合自动重试。