Java 中如何编写 JSON 接口
在现代 Web 开发中，JSON（JavaScript Object Notation）因其轻量级、易读性和跨语言兼容性，已成为数据交换的主流格式，Java 作为企业级应用开发的核心语言，提供了多种方式来处理 JSON 数据并构建 JSON 接口，本文将详细介绍如何在 Java 中编写 JSON 接口，涵盖核心概念、常用工具、实现步骤及最佳实践。
JSON 接口的核心概念
JSON 接口本质上是基于 HTTP 协议，通过请求-响应模式返回 JSON 格式数据的 API 接口，其核心流程包括：
- 接收请求：客户端通过 HTTP 请求（如 GET、POST）访问接口；
- 处理逻辑：服务端执行业务逻辑（如数据库查询、数据处理）；
- 序列化数据：将 Java 对象或数据结构转换为 JSON 格式；
- 返回响应：将 JSON 数据封装到 HTTP 响应中返回给客户端。
编写 JSON 接口的关键在于 JSON 序列化与反序列化（即 Java 对象与 JSON 字符串的相互转换）以及 HTTP 响应的构建。
常用 JSON 处理工具
Java 生态中有多种 JSON 处理库，以下是几种主流工具的对比与选择：
Jackson
Jackson 是目前 Java 生态中最流行的 JSON 处理库，具有高性能、功能丰富的特点，被 Spring Framework 等主流框架默认集成。
- 核心模块：
jackson-core：核心 JSON 处理引擎；jackson-databind：提供 Java 对象与 JSON 的双向绑定；jackson-annotations：支持注解驱动的序列化/反序列化配置。
- 优势：性能优异，支持复杂对象映射，与 Spring Boot 无缝集成。
Gson
Google 出品的 Gson 库，以简洁易用著称，适合轻量级 JSON 处理场景。
- 特点：无需注解即可实现序列化/反序列化，API 设计直观。
- 适用场景：中小型项目或对性能要求不高的场景。
org.json
轻量级 JSON 库，核心类包括 JSONObject 和 JSONArray，适合手动构建 JSON 数据。
- 特点：API 简单，无需依赖第三方框架，但灵活性较低。
推荐选择：若项目基于 Spring Boot，优先使用 Jackson；若需快速开发，可选 Gson；若需手动构建简单 JSON，可使用 org.json。
使用 Jackson 编写 JSON 接口的完整流程
以下以 Spring Boot 项目为例，演示如何通过 Jackson 编写 JSON 接口。
添加依赖
在 pom.xml 中引入 Jackson 依赖（Spring Boot 已默认集成，无需额外添加，若需手动配置可引入以下依赖）：
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.15.2</version>
</dependency>
定义数据模型
创建 Java 实体类作为 JSON 数据的载体，例如用户信息模型：
public class User {
private Long id;
private String name;
private Integer age;
private String email;
// 无参构造器、getter/setter、toString() 方法
public User() {}
public User(Long id, String name, Integer age, String email) {
this.id = id;
this.name = name;
this.age = age;
this.email = email;
}
// 省略 getter/setter...
}
编写 Controller 层
通过 @RestController 注解定义控制器，使用 @GetMapping 或 @PostMapping 映射 HTTP 请求，并返回 JSON 数据。
示例：返回单个用户对象
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
// 模拟从数据库查询用户
User user = new User(id, "张三", 25, "zhangsan@example.com");
return user; // Spring Boot 自动将对象序列化为 JSON
}
}
示例：返回用户列表
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Arrays;
import java.util.List;
@RestController
public class UserController {
@GetMapping("/users")
public List<User> getAllUsers() {
// 模拟数据库查询结果
return Arrays.asList(
new User(1L, "张三", 25, "zhangsan@example.com"),
new User(2L, "李四", 30, "lisi@example.com")
);
}
}
示例：返回自定义 JSON 响应
若需统一响应格式（如包含状态码、消息和数据），可定义响应类：
public class ApiResponse<T> {
private Integer code;
private String message;
private T data;
public ApiResponse(Integer code, String message, T data) {
this.code = code;
this.message = message;
this.data = data;
}
// 省略 getter/setter...
}
Controller 中使用：
@GetMapping("/api/users/{id}")
public ApiResponse<User> getUser(@PathVariable Long id) {
User user = new User(id, "张三", 25, "zhangsan@example.com");
return new ApiResponse<>(200, "查询成功", user);
}
JSON 序列化与反序列化配置
Jackson 支持通过注解灵活控制 JSON 转换行为，常用注解包括：
@JsonIgnore：忽略字段（不参与序列化/反序列化）；@JsonProperty：指定 JSON 字段名；@JsonFormat：格式化日期/数值类型；@JsonInclude：控制空值字段的包含策略。
示例：注解配置
public class User {
@JsonProperty("user_id")
private Long id; // JSON 字段名为 user_id
private String name;
@JsonIgnore
private String password; // 忽略 password 字段
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
private Date createTime; // 日期格式化
@JsonInclude(JsonInclude.Include.NON_NULL)
private String phone; // 若 phone 为 null，则不包含在 JSON 中
// 省略 getter/setter...
}
处理 JSON 请求体
若需接收客户端发送的 JSON 数据（如 POST 请求），可通过 @RequestBody 注解将 JSON 字符串反序列化为 Java 对象：
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
@RestController
public class UserController {
@PostMapping("/users")
public ApiResponse<User> createUser(@RequestBody User user) {
// 模拟保存用户到数据库
System.out.println("创建用户: " + user);
return new ApiResponse<>(201, "用户创建成功", user);
}
}
客户端发送 POST 请求（Content-Type: application/json）：
{
"name": "王五",
"age": 28,
"email": "wangwu@example.com"
}
其他 JSON 处理方式
手动构建 JSON（org.json）
若不想使用 Jackson，可通过 org.json 手动构建 JSON 数据：
import org.json.JSONObject;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class ManualJsonController {
@GetMapping("/manual-json")
public String getManualJson() {
JSONObject jsonObject = new JSONObject();
jsonObject.put("code", 200);
jsonObject.put("message", "手动构建 JSON");
jsonObject.put("data", new JSONObject().put("name", "手动JSON").put("value", 123));
return jsonObject.toString();
}
}
使用 Gson 序列化
若项目中使用 Gson，可通过 Gson 类手动序列化：
import com.google.gson.Gson;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class GsonController {
@GetMapping("/gson-json")
public String getGsonJson() {
User user = new User(1L, "Gson用户", 26, "gson@example.com");
Gson gson = new Gson();
return gson.toJson(user);
}
}
最佳实践
- 统一响应格式：定义
ApiResponse等统一响应类，避免直接返回原始数据，便于前端处理。 - 异常处理：通过
@ControllerAdvice和@ExceptionHandler统一处理异常，返回规范的错误信息（如 HTTP 状态码、错误消息）。 - 性能优化：
- 重用 Jackson/Gson 实例（避免重复创建）；
- 使用
@JsonView控制不同场景下返回的字段，减少数据传输量。
- 安全性：
- 对敏感字段使用
@JsonIgnore隐藏； - 校验请求数据（如使用
@Valid注解结合 Hibernate Validator）。
- 对敏感字段使用
Java 中编写 JSON 接口的核心在于选择合适的 JSON 处理工具（如 Jackson、Gson），掌握对象序列化与反序列化的方法，并结合 Spring Boot 等框架快速构建 HTTP 接口，通过合理使用注解、统一响应格式、优化性能和安全性，可以高效开发出稳定、易维护的 JSON 接口，无论是企业级应用还是小型项目，掌握这些技术都能显著提升开发效率。
