Node.js / 系统课时

统一接口响应结构

统一接口响应结构

统一响应结构的目标不是给每个接口套一层复杂包装,而是让客户端始终知道“业务数据在哪里、错误怎样识别、分页信息放哪里”。本节给出一套可直接用于 Node.js REST API 的成功、失败和分页格式,并用可运行代码验证输出。

学习目标

  • 设计一致的成功、失败与分页响应格式
  • 区分 HTTP 状态码、机器错误码与人类可读消息
  • 在 Node.js 中集中生成响应对象,减少各路由自行拼装

先固定成功与失败外形

成功响应建议把业务数据放在 data,失败响应把稳定错误码放在 error.code。这样客户端不用猜某个接口返回 result、另一个接口返回 payload,也不会把错误消息字符串当作程序分支条件。

成功示例:

json
{
  "data": {
    "id": 42,
    "name": "Ada"
  }
}

失败示例:

json
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User 42 was not found"
  }
}

code 面向程序,应保持稳定;message 面向开发者或最终用户,可以按语言或场景调整。不要让客户端通过比较 "用户不存在" 这类文本来判断错误类型。

分页响应保留 data 和 meta

分页列表仍然把业务记录放在 data,分页参数放在 meta。例如每页 25 条、当前第 2 页、总计 63 条时,总页数是 3,客户端可以直接根据 page 和 totalPages 控制翻页。

json
{
  "data": [
    { "id": 26, "name": "User 26" },
    { "id": 27, "name": "User 27" }
  ],
  "meta": {
    "page": 2,
    "pageSize": 25,
    "totalItems": 63,
    "totalPages": 3
  }
}

实际接口即使当前页只有 2 条示例数据,pageSize 仍表示请求或约定的页容量,而不是当前数组长度。若服务端限制最大页容量为 100,应在参数校验阶段把 pageSize > 100 拒绝或截断,并在接口文档中固定规则。

错误码同时给机器和人看

HTTP 状态码说明协议层结果,error.code 说明业务层类别,两者不要互相替代。以下组合足以覆盖常见用户接口。

HTTP 状态 error.code 典型场景
400 VALIDATION_FAILED 字段缺失、格式非法
404 USER_NOT_FOUND 用户 ID 不存在
409 EMAIL_ALREADY_EXISTS 唯一字段冲突
500 INTERNAL_ERROR 未预期的服务端错误

错误详情需要定位字段时,可以增加 error.details,例如 { "field": "email", "reason": "invalid_format" }。不要把数据库异常文本、堆栈或 SQL 直接返回给客户端,它们既不稳定,也可能泄漏实现细节。

在 Node.js 中集中生成响应

下面脚本适用于 Node.js 18+。它把成功、失败和分页结构集中到三个函数,路由层只需要传入数据和必要元信息,避免每个处理函数都手写对象形状。

js
function ok(data, meta) {
  return meta ? { data, meta } : { data };
}

function fail(code, message, details) {
  const error = { code, message };
  if (details) error.details = details;
  return { error };
}

function page(data, pageNumber, pageSize, totalItems) {
  return ok(data, {
    page: pageNumber,
    pageSize,
    totalItems,
    totalPages: Math.ceil(totalItems / pageSize)
  });
}

// 路由层可以把这些对象交给 res.end(JSON.stringify(...))。
console.log(JSON.stringify(ok({ id: 42, name: 'Ada' })));
console.log(JSON.stringify(fail('USER_NOT_FOUND', 'User 42 was not found')));
console.log(JSON.stringify(page([{ id: 26 }], 2, 25, 63)));

预期输出:

text
{"data":{"id":42,"name":"Ada"}}
{"error":{"code":"USER_NOT_FOUND","message":"User 42 was not found"}}
{"data":[{"id":26}],"meta":{"page":2,"pageSize":25,"totalItems":63,"totalPages":3}}

这三个函数只负责响应体形状;HTTP 状态码仍应由路由或控制器设置。例如查不到用户时,响应体使用 fail(...),同时 HTTP 状态必须是 404。

保持 HTTP 状态码与业务结构一致

最容易出现的问题是“HTTP 永远 200,再靠正文里的字段判断成功”。例如 200 + { "success": false, "error": "not found" } 会让代理、监控和通用客户端误以为请求成功。正确做法是 404 + { "error": { "code": "USER_NOT_FOUND", ... } }。

另一个常见问题是成功接口混用 { data }、{ result }、裸数组三种格式。选定规范后,应把序列化集中在共享函数或中间件中,并用接口测试至少检查三件事:状态码正确、顶层字段正确、错误码稳定。分页接口再额外检查 totalPages = Math.ceil(totalItems / pageSize) 是否与数据总量一致。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

统一接口响应结构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通