统一响应格式、错误码与异常处理
🎯 引言
学完这篇文章,你能让接口的成功和失败格式保持一致,并用 Express 错误处理中间件集中处理异常。
🧾 先约定响应格式
成功时将结果放到 data:
{"data":{"id":1,"name":"小明"}}
失败时提供稳定的错误码与可读提示:
{"error":{"code":"NAME_TAKEN","message":"名字已被使用"}}
业务错误码用于区分同类 HTTP 状态下的具体原因。前端按 code 决定行为,message 用于展示。字段名称由项目约定,重点是接口之间保持一致。
🚦 预期业务失败直接返回
新建 error-app.mjs:
import express from 'express';
export const app = express();
app.use(express.json({ limit: '16kb' }));
下面模拟一个名字已被占用的接口分支:
app.post('/users', (req, res) => {
res.status(409).json({
error: { code: 'NAME_TAKEN', message: '名字已被使用' }
});
});
请求会得到 409 和约定的错误对象。实际项目应先检查数据库再决定是否走这个分支;这里固定返回失败,用来验证响应结构。
检查意外失败时的响应
添加一个故意失败的异步接口:
app.get('/failure', async (req, res) => {
throw new Error('模拟内部操作失败');
});
请求 /failure 会进入公共错误处理,客户端应得到 500 和通用提示。框架如何传递异步异常见 Express 错误处理,这里重点检查最终返回的状态和字段。
🔎 先确定要告诉客户端什么
JSON 写错、正文过大和服务器内部失败,需要返回不同提示。先把“判断错误”单独写成函数,再让错误中间件负责发送响应。
新建 error-handler.mjs,先记录两种请求正文错误:
const inputErrors = {
'entity.parse.failed': {
status: 400, code: 'INVALID_JSON', message: 'JSON 格式不正确'
},
'entity.too.large': {
status: 413, code: 'BODY_TOO_LARGE', message: '请求正文过大'
}
};
express.json() 读取正文失败时,会在错误的 type 属性中注明原因。entity.parse.failed 表示 JSON 格式错误;entity.too.large 表示正文超过前面设置的 16 KB。表中的 status 是 HTTP 状态码,code 和 message 是返回给客户端的内容。
接着在同一文件添加判断函数:
function getErrorResponse(error) {
const inputError = inputErrors[error.type];
if (inputError) return inputError;
console.error(error);
return {
status: 500, code: 'INTERNAL_ERROR', message: '服务暂时无法处理请求'
};
}
例如 JSON 写错时,它返回 status 为 400 的那条记录。找不到对应记录时,按内部异常处理:终端打印真实错误,客户端只收到通用提示,避免暴露数据库地址等内部信息。这个函数只决定返回内容,还没有发送响应。
📤 用错误中间件发送响应
错误中间件是 Express 在前面的处理发生异常后调用的函数。继续在同一文件导出它:
export function errorHandler(error, req, res, next) {
if (res.headersSent) return next(error);
const result = getErrorResponse(error);
res.status(result.status).json({
error: { code: result.code, message: result.message }
});
}
Express 通过四个参数识别错误中间件:error 是收到的异常,req 是当前请求,res 用来响应,next 用来将错误继续交给后面的处理。即使没有读取 req,也要保留这个参数位置。
getErrorResponse 决定内容后,res.status 设置 HTTP 状态,res.json 发送错误对象。例如 JSON 格式错误时,状态为 400,正文为:
{"error":{"code":"INVALID_JSON","message":"JSON 格式不正确"}}
为什么先检查 headersSent
res.headersSent 表示响应头是否已经发出。例如下载文件已经开始,中途读文件失败,此时不能重新设置状态码,再发送一份 JSON 错误。
所以遇到这种情况,return next(error) 将错误交给 Express 后续的错误处理;本例没有其他错误中间件,最终由框架默认处理关闭连接。return 让当前函数停止,避免继续发送 JSON。尚未开始响应时,才执行后面的正常错误响应。
🔗 放在所有路由之后
回到 error-app.mjs,在路由后添加:
import { errorHandler } from './error-handler.mjs';
app.use((req, res) => {
res.status(404).json({ error: { code: 'NOT_FOUND', message: '接口不存在' } });
});
app.use(errorHandler);
404 表示没有路由响应,它不属于自动抛出的异常,需要普通中间件处理。错误中间件放在后面,才能接收前面路由或解析过程产生的错误。
🧪 验证不同失败
新建启动文件:
import { app } from './error-app.mjs';
app.listen(3000, '127.0.0.1');
运行 node error-server.mjs,分别检查:
| 请求 | 预期状态 | error.code |
|---|---|---|
| POST /users,合法 JSON | 409 | NAME_TAKEN |
| POST /users,错误 JSON | 400 | INVALID_JSON |
| GET /failure | 500 | INTERNAL_ERROR |
| GET /missing | 404 | NOT_FOUND |
例如检查内部失败:
curl -i http://127.0.0.1:3000/failure
客户端得到通用提示,服务端终端能看到模拟异常。HTTP 失败状态仍保留,不能为了统一正文而把所有状态改为 200。
❓ 知识问答
Q1:每个错误都要创建一个 Error 子类吗?
不需要。简单业务分支可直接响应,公共错误中间件处理异常;有明确需求时再设计业务错误类型。
Q2:每层都需要打印错误吗?
不需要。同一异常在最终处理处记录,避免重复日志干扰排查。
Q3:204 也需要 data 吗?
不需要,204 本来就没有正文,响应格式约定要尊重状态码含义。
🧪 小练习
修改 NAME_TAKEN 的中文提示,确认前端仍可根据错误码判断;发送无效 JSON,观察它是否在进入业务接口前被拒绝。
// 请在这里编写代码或记录结果
