统一响应格式、错误码与异常处理

给成功和失败制定稳定结构,并在公共入口完成异常响应

🎯 引言

学完这篇文章,你能让接口的成功和失败格式保持一致,并用 Express 错误处理中间件集中处理异常。

🧾 先约定响应格式

成功时将结果放到 data:

{"data":{"id":1,"name":"小明"}}

失败时提供稳定的错误码与可读提示:

{"error":{"code":"NAME_TAKEN","message":"名字已被使用"}}

业务错误码用于区分同类 HTTP 状态下的具体原因。前端按 code 决定行为,message 用于展示。字段名称由项目约定,重点是接口之间保持一致。


🚦 预期业务失败直接返回

新建 error-app.mjs:

error-app.mjs
import express from 'express';

export const app = express();
app.use(express.json({ limit: '16kb' }));

下面模拟一个名字已被占用的接口分支:

error-app.mjs
app.post('/users', (req, res) => {
    res.status(409).json({
        error: { code: 'NAME_TAKEN', message: '名字已被使用' }
    });
});

请求会得到 409 和约定的错误对象。实际项目应先检查数据库再决定是否走这个分支;这里固定返回失败,用来验证响应结构。


检查意外失败时的响应

添加一个故意失败的异步接口:

error-app.mjs
app.get('/failure', async (req, res) => {
    throw new Error('模拟内部操作失败');
});

请求 /failure 会进入公共错误处理,客户端应得到 500 和通用提示。框架如何传递异步异常见 Express 错误处理,这里重点检查最终返回的状态和字段。


🔎 先确定要告诉客户端什么

JSON 写错、正文过大和服务器内部失败,需要返回不同提示。先把“判断错误”单独写成函数,再让错误中间件负责发送响应。

新建 error-handler.mjs,先记录两种请求正文错误:

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 是返回给客户端的内容。

接着在同一文件添加判断函数:

error-handler.mjs
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 在前面的处理发生异常后调用的函数。继续在同一文件导出它:

error-handler.mjs
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,在路由后添加:

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 表示没有路由响应,它不属于自动抛出的异常,需要普通中间件处理。错误中间件放在后面,才能接收前面路由或解析过程产生的错误。


🧪 验证不同失败

新建启动文件:

error-server.mjs
import { app } from './error-app.mjs';

app.listen(3000, '127.0.0.1');

运行 node error-server.mjs,分别检查:

请求预期状态error.code
POST /users,合法 JSON409NAME_TAKEN
POST /users,错误 JSON400INVALID_JSON
GET /failure500INTERNAL_ERROR
GET /missing404NOT_FOUND

例如检查内部失败:

curl -i http://127.0.0.1:3000/failure

客户端得到通用提示,服务端终端能看到模拟异常。HTTP 失败状态仍保留,不能为了统一正文而把所有状态改为 200。


❓ 知识问答

Q1:每个错误都要创建一个 Error 子类吗?

不需要。简单业务分支可直接响应,公共错误中间件处理异常;有明确需求时再设计业务错误类型。

Q2:每层都需要打印错误吗?

不需要。同一异常在最终处理处记录,避免重复日志干扰排查。

Q3:204 也需要 data 吗?

不需要,204 本来就没有正文,响应格式约定要尊重状态码含义。


🧪 小练习

修改 NAME_TAKEN 的中文提示,确认前端仍可根据错误码判断;发送无效 JSON,观察它是否在进入业务接口前被拒绝。

// 请在这里编写代码或记录结果