express如何返回json

Express 返回 JSON 的完整指南：从基础到最佳实践

在 Web 开发中，JSON（JavaScript Object Notation）因其轻量级、易读、与 JavaScript 原生兼容的特性，已成为前后端数据交互的主流格式，Express 作为 Node.js 最流行的 Web 框架，提供了多种便捷的方式返回 JSON 响应，本文将详细介绍 Express 返回 JSON 的核心方法、进阶技巧及最佳实践,帮助你高效处理数据交互。

基础用法：使用 res.json() 返回 JSON

Express 框架在 Response 对象（res）中原生提供了 res.json() 方法，这是返回 JSON 数据最推荐、最核心的方式，该方法会自动完成以下操作：

• 将传入的 JavaScript 对象/数组序列化为 JSON 字符串；
• 设置正确的响应头 Content-Type: application/json；
• 发送响应并终止请求-响应周期。

示例：简单返回 JSON

const express = require('express');
const app = express();
const port = 3000;
app.get('/api/user', (req, res) => {
  const userData = {
    id: 1,
    name: '张三',
    email: 'zhangsan@example.com',
    isActive: true
  };
  res.json(userData); // 自动序列化为 JSON 并设置响应头
});
app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

访问结果

启动服务器后，访问 http://localhost:3000/api/user,浏览器或客户端会收到以下响应：

{
  "id": 1,
  "name": "张三",
  "email": "zhangsan@example.com",
  "isActive": true
}

响应头中会包含 Content-Type: application/json; charset=utf-8，明确告知客户端返回的是 JSON 数据。

进阶用法：res.json() 的灵活特性

res.json() 不仅能处理普通对象，还支持多种数据类型和高级场景,以下是常见用法：

返回 JSON 数组

app.get('/api/users', (req, res) => {
  const users = [
    { id: 1, name: '张三' },
    { id: 2, name: '李四' },
    { id: 3, name: '王五' }
  ];
  res.json(users); // 返回 JSON 数组
});

响应结果：

[
  { "id": 1, "name": "张三" },
  { "id": 2, "name": "李四" },
  { "id": 3, "name": "王五" }
]

返回嵌套 JSON 对象

app.get('/api/post/1', (req, res) => {
  const post = {
    id: 1, 'Express 返回 JSON 教程',
    content: '本文介绍如何使用 Express 返回 JSON 数据...',
    author: {
      id: 1,
      name: '张三',
      avatar: 'https://example.com/avatar.jpg'
    },
    tags: ['Express', 'JSON', 'Node.js']
  };
  res.json(post); // 返回嵌套对象
});

处理特殊数据类型（null、Number、Boolean）

res.json() 会自动处理 JavaScript 特殊类型，并转换为对应的 JSON 格式：

app.get('/api/data', (req, res) => {
  const data = {
    nullValue: null,
    numberValue: 3.14159,
    booleanValue: false,
    stringValue: 'Hello, JSON!'
  };
  res.json(data);
});

响应结果：

{
  "nullValue": null,
  "numberValue": 3.14159,
  "booleanValue": false,
  "stringValue": "Hello, JSON!"
}

返回错误 JSON

RESTful API 中，错误响应通常也以 JSON 格式返回,方便客户端统一处理：

app.get('/api/user/999', (req, res) => {
  const error = {
    error: 'UserNotFound',
    message: '用户 ID 999 不存在',
    code: 404
  };
  res.status(404).json(error); // 结合 res.status() 设置 HTTP 状态码
});

响应结果（状态码 404）：

{
  "error": "UserNotFound",
  "message": "用户 ID 999 不存在",
  "code": 404
}

替代方法：res.send() 与 JSON 返回

除了 res.json()，Express 还提供了 res.send() 方法，它也能返回 JSON 数据，但与 res.json() 有关键区别：

res.send() vs res.json()

示例：res.send() 返回 JSON

app.get('/api/send-json', (req, res) => {
  const data = { message: 'This is from res.send()' };
  res.send(data); // data 是对象/数组，res.send() 会自动转为 JSON
});

注意：res.send() 传入的是字符串，且内容看起来像 JSON（如 {"key": "value"}），Express 不会自动解析为 JSON，而是会将其作为普通文本返回，可能导致客户端解析错误。明确返回 JSON 时，优先使用 res.json()。

最佳实践：规范 JSON 返回格式

在实际项目中，统一的 JSON 返回格式能提升 API 的可维护性和客户端兼容性,以下是推荐的实践方案：

统一响应结构

建议所有 API 响应包含以下字段：

• success：布尔值,表示请求是否成功；
• data：数据字段，成功时返回业务数据，失败时可为 null；
• message：消息字段，成功时可返回操作提示（如“获取成功”）,失败时返回错误详情；
• error：错误字段（可选）,失败时返回错误类型或代码。

示例：成功响应

app.get('/api/profile', (req, res) => {
  const profile = { id: 1, username: 'admin' };
  res.json({
    success: true,
    data: profile,
    message: '用户信息获取成功'
  });
});

响应结果：

{
  "success": true,
  "data": { "id": 1, "username": "admin" },
  "message": "用户信息获取成功"
}

示例：失败响应

app.post('/api/login', (req, res) => {
  const { username, password } = req.body;
  if (username !== 'admin' || password !== '123456') {
    return res.status(401).json({
      success: false,
      data: null,
      message: '用户名或密码错误',
      error: 'InvalidCredentials'
    });
  }
  // 登录成功逻辑...
});

响应结果（状态码 401）：

{
  "success": false,
  "data": null,
  "message": "用户名或密码错误",
  "error": "InvalidCredentials"
}

处理 JSON 序列化问题

当返回的 JSON 对象中包含循环引用（如两个对象相互引用）时，直接使用 res.json() 会抛出错误 TypeError: Converting circular structure to JSON,解决方案：

方法 1：移除循环引用

const user = { id: 1, name: '张三' };
const post = { id: 1, title: 'Express 教程', author: user };
user.posts = [post]; // 循环引用：user -> post -> user
// 移除循环引用
user.posts = user.posts.map(p => ({ id: p.id, title: p.title }));
res.json(user);

方法 2：使用 JSON.stringify() 的 replacer 参数

const user = { id: 1, name: '张三' };
const post = { id: 1, title: 'Express 教程', author: user };
user.posts = [post];
// 使用 replacer 函数过滤循环引用
const jsonString = JSON.stringify(user, (key, value) => {
  if (key === 'posts') return undefined; // 过滤掉 posts 字段
  return value;
});
res.send(jsonString