揭秘 application/json：现代 API 的通用语言！！！

原创于 2025-04-18 17:06:49 发布 · 1.2k 阅读

16 ·

CC 4.0 BY-SA版权

文章标签：

#json

Java Web 专栏收录该内容

19 篇文章

订阅专栏

该文章已生成可运行项目，

揭秘 `application/json`：现代 API 的通用语言 🌐

嘿，各位开发者伙伴们！👋 有没有想过现代 Web 应用和服务之间是如何如此顺畅地交流的？当你的前端 JavaScript 向后端 API 发送数据，或者微服务之间进行通信时，它们很可能在说一种共同的语言：JSON (JavaScript 对象表示法)。而那个告诉所有参与者“嘿，数据载荷是 JSON 格式！”的关键，就是 HTTP 头部 Content-Type: application/json。🚀

让我们深入探讨这个头部意味着什么，为什么它如此重要，以及它是如何驱动着现代 Web 的大部分运作的！

🤔 首先，什么是 JSON？

在理解这个头部之前，让我们快速回顾一下 JSON 本身。它是一种轻量级的、人类可读的数据交换格式，基于 JavaScript 的对象语法。它的构建块很简单：

对象 (Objects): 无序的键值对集合，用花括号 {} 包裹。键是字符串，值可以是字符串、数字、布尔值、数组或其他对象。例如：{"name": "爱丽丝", "age": 30}
数组 (Arrays): 有序的值列表，用方括号 [] 包裹。例如：["苹果", "香蕉", "樱桃"]
值 (Values): 字符串（用双引号包裹）、数字、true、false、null。

它的简洁性和易于机器（及人类！）解析的特点使其变得极其流行。🧱📜

🏷️ `Content-Type: application/json` 意味着什么？

现在回到 HTTP 头部。Content-Type 是一个标准的 HTTP 头部字段，用于请求和响应中。它的作用是指明消息体 (message body) 中资源的媒体类型 (media type)。

当客户端（如浏览器或其他应用程序）发送一个 HTTP 请求（例如 POST 或 PUT），其请求体 (request body) 中包含数据时，如果它设置了头部 Content-Type: application/json，它就是在明确告知服务器：

“注意啦！我在这个请求体里发送给你的数据是 JSON 格式的。请据此解析。” 📦

同样地，当服务器发送一个在其响应体中包含 JSON 数据的响应时，它也会在响应头中包含 Content-Type: application/json，以告知客户端如何解释收到的载荷。

🚀 我们何时以及为何使用它？

application/json 是现代 API 通信的基石，尤其适用于：

RESTful API: 当创建、更新或向 REST API 端点发送复杂数据时（通常使用 POST, PUT, PATCH 方法），JSON 是请求体的首选格式。
AJAX 请求: 前端 JavaScript 发送异步请求（例如使用 fetch 或 axios）到后端 API 时，频繁地发送和接收 JSON 数据。
微服务通信: 分布式系统中的服务之间通常使用 JSON 通过 HTTP 或其他协议交换信息。
配置文件: 虽然不严格属于 HTTP，但 JSON 的结构使其非常适合做配置文件。

为什么 JSON 和 application/json 如此受欢迎：

可读性: 便于人类阅读和编写。
简洁性: 结构简单，定义明确。
语言支持: 几乎所有现代编程语言（尤其是 JavaScript！）都原生支持或可以轻松处理。
灵活性: 可以表示复杂的嵌套数据结构（对象内对象、对象数组等）。

关于 GET 请求的重要说明: 标准的 HTTP GET 请求旨在检索数据，并且不应包含请求体。因此，在典型的 GET 请求上设置 Content-Type（它描述的是主体内容）通常是无意义的，也不符合标准实践。GET 请求的数据通常通过 URL 查询参数传递。

⚙️ 后端处理：接收 JSON (以 Java Spring 为例)

当服务器收到一个 Content-Type: application/json 的请求时，后端框架需要知道如何将请求体中的 JSON 字符串反序列化（转换）为编程语言中可用的对象。

在 Java Spring Boot/MVC 中，这个魔法是通过 @RequestBody 注解实现的：

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.http.ResponseEntity; // 引入 ResponseEntity

// 定义一个与预期 JSON 结构匹配的 POJO (普通 Java 对象)
public class UserData {
    private String username;
    private String email;
    private int age;

    // --- 重要：需要 Getters 和 Setters (或使用 Lombok) ---
    // 以便框架（如 Jackson）能够将 JSON 反序列化到这个对象中
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    public String getEmail() { return email; } // 假设添加了 email 的 getter/setter
    public void setEmail(String email) { this.email = email; }
    public int getAge() { return age; } // 假设添加了 age 的 getter/setter
    public void setAge(int age) { this.age = age; }
}

@RestController
public class ApiController {

    @PostMapping("/api/users")
    public ResponseEntity<String> createUser(@RequestBody UserData userData) {
        // 因为请求的 Content-Type 是 application/json,
        // Spring 使用一个由 @RequestBody 触发的消息转换器 (如 Jackson)
        // 来自动将 JSON 体转换成 UserData 对象。✨

        System.out.println("收到的用户: " + userData.getUsername());
        System.out.println("邮箱: " + userData.getEmail());

        // --- 处理 userData 对象 (例如，保存到数据库) ---

        return ResponseEntity.ok("用户创建成功!");
    }
}

关键点：

@RequestBody 告诉 Spring 获取整个请求体。
Spring 检查 Content-Type 头部。如果是 application/json，它会使用配置好的 JSON 消息转换器（默认通常是 Jackson）。
转换器尝试将 JSON 字段映射到 UserData 类的属性（因此需要匹配的名称和 setter/getter 方法）。

📊 vs `application/x-www-form-urlencoded`：关键区别

特性	`application/json`	`application/x-www-form-urlencoded`
数据格式	JSON (`{"key": "value", ...}`)	键值对 (`key=value&key=value`)
结构	层级结构 (对象, 数组)	扁平结构 (简单键值对)
编码	通常是 UTF-8	URL 编码 (%XX, + 代表空格)
可读性	高	较低 (因编码)
主要用途	API (REST, AJAX), 微服务	HTML 表单提交 (`POST`)
JS 处理	`JSON.stringify()`, `JSON.parse()`	手动编码或 `URLSearchParams`
Java Spring 接收	`@RequestBody` + POJO/Map	`@RequestParam`, POJO 绑定
灵活性	高 (处理复杂数据)	有限 (处理简单数据)

🗺️ 流程图：典型的 JSON API 交互

🎬 序列图：客户端-服务器 JSON 交换

✨ 核心要点

📌 Content-Type: application/json 告知接收方 HTTP 消息主体 (body) 包含 JSON 格式的数据。
📌 对于使用 POST, PUT, PATCH 请求发送结构化数据的 API (RESTful, AJAX) 至关重要。
📌 JSON 本身易于阅读，并支持复杂的嵌套结构（对象/数组）。
📌 后端框架（如 Spring）使用此头部选择正确的解析器（反序列化器）处理请求体，常与 @RequestBody 等注解配合使用。
📌 它与用于传统 HTML 表单提交的 application/x-www-form-urlencoded 不同。