Node.js / 系统课时
统一接口响应结构
统一接口响应结构
统一响应结构的目标不是给每个接口套一层复杂包装,而是让客户端始终知道“业务数据在哪里、错误怎样识别、分页信息放哪里”。本节给出一套可直接用于 Node.js REST API 的成功、失败和分页格式,并用可运行代码验证输出。
学习目标
- 设计一致的成功、失败与分页响应格式
- 区分 HTTP 状态码、机器错误码与人类可读消息
- 在 Node.js 中集中生成响应对象,减少各路由自行拼装
先固定成功与失败外形
成功响应建议把业务数据放在 data,失败响应把稳定错误码放在 error.code。这样客户端不用猜某个接口返回 result、另一个接口返回 payload,也不会把错误消息字符串当作程序分支条件。
成功示例:
{
"data": {
"id": 42,
"name": "Ada"
}
}失败示例:
{
"error": {
"code": "USER_NOT_FOUND",
"message": "User 42 was not found"
}
}code 面向程序,应保持稳定;message 面向开发者或最终用户,可以按语言或场景调整。不要让客户端通过比较 "用户不存在" 这类文本来判断错误类型。
分页响应保留 data 和 meta
分页列表仍然把业务记录放在 data,分页参数放在 meta。例如每页 25 条、当前第 2 页、总计 63 条时,总页数是 3,客户端可以直接根据 page 和 totalPages 控制翻页。
{
"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+。它把成功、失败和分页结构集中到三个函数,路由层只需要传入数据和必要元信息,避免每个处理函数都手写对象形状。
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)));预期输出:
{"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) 是否与数据总量一致。