Gson 构建 GET 接口并返回 JSON 的完整实战指南

1. 环境准备与依赖

1.1 目标与技术选型

本节聚焦在通过 Gson 实现 GET 接口 并返回 JSON 的完整流程，适用于 Java 与 Spring Boot 生态。通过明确的目标，可以在后续章节中快速落地并实现高可维护性。

在选型层面，优先考虑 Spring Boot 的快速启动能力和 Gson 的高效序列化能力，避免直接使用 Jackson 进行 JSON 输出，以符合“使用 Gson 构建 GET 接口并返回 JSON”的场景需求。

1.2 依赖引入示例

需要引入的核心依赖包含 web 框架和 Gson 库，确保 GET 请求 可以正确路由并输出 JSON。

<dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>com.google.code.gson</groupId><artifactId>gson</artifactId></dependency>
</dependencies>

若使用 Gradle，可对应使用 implementation 'com.google.code.gson:gson' 形式进行配置。

1.3 Gson 的基本使用场景

引入 Gson 后，序列化对象为 JSON、自定义日期格式、以及通过注解控制暴露字段，都是日常实践中的关键点。

在后续章节中，将通过具体的 Controller、Service 和配置来演示如何把 Gson 集成到 GET 接口的返回流程中。

2. 数据模型设计与实体类

2.1 定义数据模型（POJO）

设计一个简单的用户模型，包含 id、name、email 等字段，作为 GET 接口的返回对象。通过 POJO 的方式定义，便于后续进行序列化处理。

关键点在于确保字段的可序列化性与可扩展性，避免将敏感信息直接暴露给客户端。

2.2 使用 Gson 注解控制暴露字段

可以通过 @Expose 等注解控制哪些字段参与序列化，提升安全性与灵活性。

下面给出一个基础的用户实体类示例，包含简单暴露控制与构造方法。

import com.google.gson.annotations.Expose;public class User {@Expose private long id;@Expose private String name;@Expose private String email;public User(long id, String name, String email) {this.id = id;this.name = name;this.email = email;}// getters and setters
}

3. GET 接口实现与返回 JSON

3.1 服务层设计与数据获取

为了实现一个可测试的 GET 接口，先在服务层提供一个简单的查找方法，用于根据 id 获取 User 对象。此处采用 内存数据 模拟，便于快速迭代。

核心要点在于将数据获取与 JSON 序列化分离，确保应用的解耦性和可测试性。

import java.util.Optional;public class UserService {public User findById(long id) {// 模拟数据源if (id == 1) {return new User(1, "Alice", "alice@example.com");} else if (id == 2) {return new User(2, "Bob", "bob@example.com");}return null;}
}

3.2 控制层：GET 路由与 Gson 序列化

控制层负责接收 GET 请求，调用服务层获取数据，并使用 Gson 将对象序列化为 JSON 字符串返回给客户端。

为了确保返回 Content-Type 为 application/json，可以在响应中显式设置类型，避免客户端解析异常。

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("/api")
public class UserController {private final UserService service;private final Gson gson;public UserController(UserService service) {this.service = service;this.gson = new GsonBuilder().excludeFieldsWithoutExposeAnnotation().setPrettyPrinting().create();}@GetMapping(value = "/users/{id}", produces = MediaType.APPLICATION_JSON_VALUE)public ResponseEntity<String> getUser(@PathVariable long id) {User user = service.findById(id);if (user == null) {return ResponseEntity.notFound().build();}String json = gson.toJson(user);return ResponseEntity.ok(json);}
}

4. Gson 配置与高级用法

4.1 自定义序列化策略

对于某些字段类型（如 Date、Enum 等）需要定制序列化行为时，可以通过 JsonSerializer/JsonDeserializer，以及 TypeAdapter 注册到 Gson。

这类自定义能力能让返回给客户端的 JSON 结构更符合消费端的期望。

import com.google.gson.*;
import java.lang.reflect.Type;
import java.util.Date;class DateAdapter implements JsonSerializer {@Overridepublic JsonElement serialize(Date src, Type typeOfSrc, JsonSerializationContext context) {return new JsonPrimitive(new java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ").format(src));}
}// 注册自定义转换
Gson gson = new GsonBuilder().registerTypeAdapter(Date.class, new DateAdapter()).create();

4.2 全局错误处理与统一返回结构

为了提升前后端对齐，建议在控制层返回标准化的错误与成功结构，并结合 Gson 实现自定义的序列化策略。

class ApiResponse {private boolean success;private T data;private String error;// 构造、getter、setter
}

// 示例：在控制器中包装返回
@ApiResponse
@GetMapping("/users/{id}")
public ResponseEntity<String> getUser(@PathVariable long id) {User user = service.findById(id);if (user == null) {ApiResponse