从 Servlet 返回 JSON 响应

1. 简介

本文将带你快速搭建一个简单的 Web 应用，并掌握如何从 Servlet 中返回 JSON 格式的响应。这在实现轻量级 REST 接口时非常常见，尤其适用于不需要完整 Spring 框架的场景。

2. Maven 依赖

我们的项目需要两个核心依赖：Servlet API 和一个 JSON 序列化库。这里选择 Gson，简单轻量，适合小项目。

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>${javax.servlet.version}</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>${gson.version}</version>
</dependency>

✅ 说明：

javax.servlet-api 使用 provided 范围，因为运行时由 Tomcat 等容器提供。
Gson 版本建议使用最新稳定版，可前往 Maven Central 查看。

⚠️ 踩坑提醒：如果你在本地运行时报 ClassNotFoundException: javax.servlet.Servlet，说明缺少 Servlet API，记得检查依赖范围是否正确。

部署方面，可将应用打包为 WAR 部署到 Tomcat。具体操作可参考：如何在 Tomcat 部署 WAR 包。

3. 创建实体类

我们先定义一个 Employee 实体类，作为后续返回的 JSON 数据结构：

public class Employee {
    
    private int id;
    private String name;
    private String department;
    private long salary;

    // 无参构造
    public Employee() {}

    // 全参构造
    public Employee(int id, String name, String department, long salary) {
        this.id = id;
        this.name = name;
        this.department = department;
        this.salary = salary;
    }

    // 标准 getter 和 setter
    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDepartment() {
        return department;
    }

    public void setDepartment(String department) {
        this.department = department;
    }

    public long getSalary() {
        return salary;
    }

    public void setSalary(long salary) {
        this.salary = salary;
    }
}

⚠️ 注意：Gson 需要类有默认构造函数（无参），否则反序列化可能失败。

4. 对象转 JSON

要从 Servlet 返回 JSON，第一步就是把 Java 对象转成 JSON 字符串。常见的库有 Gson 和 Jackson。

✅ Gson：Google 出品，API 简洁，适合简单场景。
✅ Jackson：功能强大，性能好，Spring 默认使用它。

本文选用 Gson，上手快，代码干净。

使用 Gson 转换对象到 JSON 字符串，一行代码搞定：

String employeeJsonString = new Gson().toJson(employee);

✅ 小技巧：建议将 Gson 实例作为类的静态成员或单例，避免频繁创建。

5. 设置响应头与内容类型

在 Servlet 中返回响应时，顺序很重要。必须遵循以下步骤：

✅ 获取输出流
✅ 设置响应头（如 Content-Type）
✅ 写入内容
✅ 提交响应（自动或手动 flush）

关键点：响应头必须在响应提交前设置，否则会被容器忽略。

返回 JSON 时，必须设置正确的 Content-Type，否则前端可能无法正确解析。

PrintWriter out = response.getWriter();
response.setContentType("application/json");
response.setCharacterEncoding("UTF-8");
out.print(employeeJsonString);
out.flush();

✅ 解释：

Content-Type: application/json：告诉客户端这是 JSON 数据。
CharacterEncoding: UTF-8：防止中文乱码。
flush()：强制输出缓冲区内容，同时提交响应。

❌ 常见错误：先 flush() 再设置 header，会导致 header 无效。

6. 完整 Servlet 示例

下面是一个完整的 Servlet 示例，暴露一个 /employeeServlet 接口，返回员工信息的 JSON：

@WebServlet(name = "EmployeeServlet", urlPatterns = "/employeeServlet")
public class EmployeeServlet extends HttpServlet {

    private Gson gson = new Gson();

    @Override
    protected void doGet(
        HttpServletRequest request, 
        HttpServletResponse response) throws IOException {
        
        // 构造员工对象
        Employee employee = new Employee(1, "Karan", "IT", 5000);
        
        // 转为 JSON 字符串
        String employeeJsonString = this.gson.toJson(employee);

        // 获取输出流
        PrintWriter out = response.getWriter();
        
        // 设置响应头（必须在写内容前）
        response.setContentType("application/json");
        response.setCharacterEncoding("UTF-8");
        
        // 输出 JSON
        out.print(employeeJsonString);
        out.flush();   
    }
}

✅ 验证方式：启动应用后访问 http://localhost:8080/your-app/employeeServlet，应返回：

{"id":1,"name":"Karan","department":"IT","salary":5000}

7. 总结

本文演示了如何从 Servlet 直接返回 JSON 响应，核心要点如下：

✅ 使用 Gson 等库将对象序列化为 JSON 字符串
✅ 正确设置 Content-Type: application/json
✅ 响应头必须在写入内容前设置
✅ flush() 会提交响应，之后不能再修改 header

这种方式适合轻量级 REST 接口，无需引入 Spring MVC 等重型框架。但在复杂项目中，建议使用 Spring Boot + @RestController，开发效率更高。

所有示例代码已上传至 GitHub：https://github.com/dev-example/servlet-json-response

Persistence

REST

Security