面向前端体验的 API 设计

API 是产品体验的一部分

前端体验经常被 API 形状影响。字段是否稳定、错误是否可解释、分页是否清晰，都会决定界面实现是否简单。

后端接口不是把数据库暴露出去，而是为一个用户场景提供稳定契约。

返回前端需要的语义

如果前端每次都要组合多个字段才能判断状态，说明接口可能缺少业务语义。

错误信息要可处理

错误响应至少应该包含机器可读的 code 和人类可读的 message。前端可以根据 code 决定交互，根据 message 辅助展示。

分页和筛选要稳定

列表接口要明确排序规则。否则用户翻页时很容易出现重复或遗漏，尤其是数据持续变化的场景。

小结

面向前端体验设计 API，本质是在减少两端的误解。契约越清晰，界面越容易保持稳定。