外观
给客户端设计后端接口，哪些约定不能省？
标准回答
接口契约应说明请求字段、返回字段、错误、权限、重试和版本兼容。调用方不只需要一个 URL，还需要知道超时后能不能重试、哪个字段表示正在处理、哪个表示最终成功。
- 服务端核验用户身份与设备访问权限，不能只相信客户端传来的 userId 或 deviceId。
- 长任务可采用提交加查询或推送；分页、超时、取消与幂等规则保持一致。
- 使用明确错误码和 requestId 关联日志，新增字段尽量保持旧客户端可用。
通俗例子
客户端提交设备诊断任务，服务端返回 taskId 和 queued；随后查询得到 running、succeeded 或 failed。客户端按任务状态展示，而不会把第一次 HTTP 请求成功误当成诊断完成。
深入解释
**接口契约包括哪些约定：**除了字段类型，还要说明单位、必填条件、身份与设备权限、状态含义、错误、超时和重试。调用方依靠这些约定决定下一步。
**为什么长任务适合有 taskId：**提交动作完成后，后台任务可能仍在执行。taskId 让客户端稍后查询或订阅进度，也让断线重连后可以找回同一个任务，避免重新创建。
易混淆点
前端隐藏一个按钮不能代替服务端授权；成功状态也不能全都塞进一段自由文本。
参考资料
内容来源
- Android · AI Agent 知识手册 · 原条目
job-C05