服务端API设计规范：让办公系统更高效协作

为什么API设计影响日常办公效率

在公司用的OA系统里，点击“提交报销”后，页面几秒内就显示“已提交”，还能同步到财务待办列表。这种流畅体验背后，靠的是服务端API设计是否合理。如果接口命名混乱、返回数据不统一，前端开发得不断适配，bug频出，最终拖累整个办公流程。

比如某次升级审批模块，原本返回status: 1代表通过，新接口却改成approved: true，前端没及时调整，导致几十条申请卡在“处理中”。这类问题，本质上都是缺乏统一的API设计规范。

统一命名规则，减少沟通成本

接口路径别玩文字游戏。获取员工列表就用/api/v1/employees，不要今天写/getUsers，明天变成/fetchStaff。动词交给HTTP方法：查用GET，增用POST，改用PUT，删用DELETE。

版本号建议放在路径开头，比如/api/v1/，方便后续兼容老客户端。别等业务跑起来了再改接口，那时候牵一发动全身。

返回结构要稳定，前端才不抓狂

不管请求成功还是失败，外层结构保持一致：

{
  "code": 0,
  "message": "success",
  "data": {}
}

成功时code为0，data放实际数据；失败时code给具体错误码，message写清楚原因。前端根据code统一处理弹窗提示，不用每个接口单独写逻辑。

字段命名坚持小驼峰

数据库可能用下划线，比如user_name，但API输出一律转成小驼峰：userName。团队里有人用Java，有人写JavaScript，字段风格统一，解析起来少出错。

时间字段统一用ISO格式字符串，比如createTime: "2023-11-05T08:30:00Z"，避免前端拿到时间戳还要猜是秒还是毫秒。

分页和筛选参数标准化

列表接口难免要翻页。约定好通用参数名，比如page=1&size=20&keyword=张三。别一个接口叫pageNo，另一个叫pageNum，测试写自动化脚本时容易混淆。

筛选条件尽量用前缀归类，比如dateFrom=2023-11-01&dateTo=2023-11-30，比传两个孤立参数更清晰。

错误码别随意定义

401是未登录，403是没权限，404是路径错了，这些HTTP状态码该用就得用。业务层面的错误，比如“余额不足”“审批人不能为空”，在返回体的code里定义具体数字，比如1001、1002，文档里写明白对应场景。客服查日志时，一看错误码就知道问题出在哪。

文档及时更新，别让新人踩坑

用Swagger或YAPI把接口文档挂出来，路径、参数、返回示例都写全。有次新同事接入考勤系统，发现文档里写的返回字段和实际不一样，调试半天才发现是接口改了但文档没同步。这种低级问题，直接影响项目上线进度。

规范不是为了束缚开发，而是让团队协作像搭积木一样顺畅。每个接口都按规矩来，系统越复杂，越能省下无数沟通和返工的时间。