源内容（英文）
表述性状态转移 (REST) 是一种软件架构风格，它定义了一组用于创建 Web 服务的约束条件。RESTful Web 服务允许系统通过一组统一且预定义的无状态操作来访问和操作 Web 资源。与 SOAP（它公开了自己的一套操作）不同，RESTful Web 服务依赖于简单的 HTTP 方法，如 GET、POST、PUT 和 DELETE。
为什么选择 Spring Boot？
Spring Boot 让我们能够轻松创建可用于生产环境的应用程序：
- 建立在 Spring Framework 之上
- 通过自动配置减少了样板代码
- REST API 的快速设置
- 对初学者友好
Spring Boot 中 REST API 的分步实现
步骤 1：创建 Spring Boot 项目
使用 Spring Initializr（推荐）
- 在浏览器中打开 Spring Initializr。
- 填写项目详情：
- Project: Maven
- Language: Java
- Spring Boot version: (最新的稳定版本，例如 3.1.x)
- Group: com. example
- Artifact: demo
- Name: demo
- Packaging: Jar
- Java version: 17+
- 点击 Add Dependencies（添加依赖）-> 选择 Spring Web。
- 点击 Generate（生成）-> 它将下载一个 .zip 文件。
- 解压 zip 文件 -> 在你的 IDE (IntelliJ / Eclipse / VS Code) 中打开它。
步骤 2：定义 Employee 实体
在 com.example.demo 内部创建一个简单的 Employee 类：
package com.example.demo;
// Employee entity class
public class Employee {
private Integer id;
private String firstName;
private String lastName;
private String email;
// Default constructor
public Employee() {}
// Parameterized constructor
public Employee(Integer id, String firstName, String lastName, String email) {
this.id = id;
this.firstName = firstName;
this.lastName = lastName;
this.email = email;
}
// Getters and Setters
public Integer getId() { return id; }
public void setId(Integer id) { this.id = id; }
public String getFirstName() { return firstName; }
public void setFirstName(String firstName) { this.firstName = firstName; }
public String getLastName() { return lastName; }
public void setLastName(String lastName) { this.lastName = lastName; }
public String getEmail() { return email; }
public void setEmail(String email) { this.email = email; }
@Override
public String toString() {
return "Employee [id=" + id + ", firstName=" + firstName +
", lastName=" + lastName + ", email=" + email + "]";
}
}
步骤 3：创建存储类
创建一个类来保存员工列表。
package com.example.demo;
import java.util.ArrayList;
import java.util.List;
public class Employees {
private List employeeList;
public List getEmployeeList() {
if (employeeList == null) {
employeeList = new ArrayList();
}
return employeeList;
}
public void setEmployeeList(List employeeList) {
this.employeeList = employeeList;
}
}
步骤 4：创建 DAO 类
DAO 类将处理添加和检索员工。
package com.example.demo;
import org.springframework.stereotype.Repository;
@Repository
public class EmployeeDAO {
private static Employees employees = new Employees();
static {
employees.getEmployeeList().add(new Employee(1, "Prem", "Tiwari", "[email protected]"));
employees.getEmployeeList().add(new Employee(2, "Vikash", "Kumar", "[email protected]"));
employees.getEmployeeList().add(new Employee(3, "Ritesh", "Ojha", "[email protected]"));
}
public Employees getAllEmployees() {
return employees;
}
public void addEmployee(Employee employee) {
employees.getEmployeeList().add(employee);
}
}
步骤 5：创建控制器
控制器包含 REST API 端点。
package com.example.demo;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
import java.net.URI;
@RestController
@RequestMapping("/employees")
public class EmployeeController {
@Autowired
private EmployeeDAO employeeDao;
@GetMapping("/")
public Employees getAllEmployees() {
return employeeDao.getAllEmployees();
}
}
—
2026年开发者视角：当我们谈论 REST API 时，我们在谈论什么？
你好！作为一名在这个行业摸爬滚打多年的技术老兵，我非常高兴能和你一起探讨这个话题。虽然上面的代码展示了 REST API 的核心逻辑，但在 2026 年，我们的工作流和标准已经发生了巨大的变化。"Hello World" 级别的代码已经不足以应对现代生产的复杂性。在这篇文章中，我们将深入探讨如何将这个简单的示例转化为符合现代云原生标准的企业级应用，并分享我们是如何在 AI 时代重新定义开发流程的。
拥抱 AI 辅助开发：从 Cursor 到 Copilot
你可能已经注意到，现在的编码环境与几年前大不相同。在我们的团队中，我们已经完全接受了 "氛围编程 (Vibe Coding)" 的理念。这并不是说我们不再写代码，而是我们将 AI 视为我们的结对编程伙伴。
当你使用 Cursor 或 Windsurf 等现代 IDE 时，你不再需要手动编写所有的 Getter 和 Setter。你可以直接告诉 AI：
> "请基于 Java 17 的 Record 特性重构这个 Employee 实体，并生成 Javadoc，确保线程安全。"
现代实体重构示例 (2026 风格):
package com.example.demo.model;
import com.fasterxml.jackson.annotation.JsonInclude;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
/**
* 2026标准：使用不可变 Record 减少样板代码，
* 并内置 Jakarta Validation 用于自动参数校验。
*/
public record Employee(
Integer id,
@NotBlank(message = "First name is required")
String firstName,
@NotBlank(message = "Last name is required")
String lastName,
@Email(message = "Email should be valid")
String email
) {}
在我们的实际项目中，使用 Record 不仅可以减少代码量，还能从根本上防止空指针异常，因为我们强制在构造时就校验数据。你可能会问，那之前的 DAO 层怎么办？这正是我们要讲的下一个重点：现代化分层架构。
超越内存存储：拥抱真实的数据持久化与 Repository 模式
在上述 GeeksforGeeks 的教程中，我们使用了一个静态列表来存储数据。这对演示来说很好，但在生产环境中，这绝对是一个巨大的隐患。重启服务，数据就没了——这在 2026 年是不可接受的。
让我们通过引入 Spring Data JPA 和一个内存数据库 H2（方便你快速测试，无需安装 MySQL）来升级这个 DAO。
步骤升级：添加数据库依赖
首先，在 pom.xml 中添加：
org.springframework.boot
spring-boot-starter-data-jpa
com.h2database
h2
runtime
现代 Repository 实现：
我们不再手动编写 INLINECODE2f5a6a73，而是让它继承 INLINECODE1cd265e0。这就像是魔法一样，CRUD 操作自动生成。
package com.example.demo.repository;
import com.example.demo.model.Employee;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
import java.util.Optional;
@Repository
public interface EmployeeRepository extends JpaRepository {
// Spring Data 会自动实现这行代码，甚至不需要写 SQL！
// 你可以通过方法名查询，例如 findByEmail(String email)
Optional findByEmail(String email);
}
在这个过程中，如果你遇到比如 "Entity not mapped" 的错误，别担心。利用 AI 调试工具（比如 Cursor 的 INLINECODE1f88064e 解释错误功能），它能迅速告诉你忘记加 INLINECODE18a85d6e 注解了。在我们最近的微服务重构中，这种 AI 辅助排查将我们的调试时间缩短了 40%。
RESTful 最佳实践：不仅仅是返回 JSON
现在我们来升级 Controller。在 GeeksforGeeks 的原始代码中，我们直接返回了对象列表。但在企业级开发中，我们需要更精细的控制：HTTP 状态码、异常处理以及RESTful 的 HATEOAS（虽然现在 GraphQL 和 RPC 很流行，但 REST 依然是基石）。
升级后的 Service 层（业务逻辑隔离）：
为了更好的代码结构，我们通常在 Controller 和 Repository 之间加一层 Service。
package com.example.demo.service;
import com.example.demo.model.Employee;
import com.example.demo.repository.EmployeeRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;
@Service
public class EmployeeService {
@Autowired
private EmployeeRepository repository;
public List getAllEmployees() {
return repository.findAll();
}
public Employee createEmployee(Employee employee) {
// 这里可以添加复杂的业务逻辑，比如检查邮箱是否已存在
return repository.save(employee);
}
}
企业级 Controller 实现：
让我们看看如何处理 "创建成功" 应该返回 201 状态码，以及 "资源未找到" 返回 404。
package com.example.demo.controller;
import com.example.demo.model.Employee;
import com.example.demo.service.EmployeeService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.net.URI;
import java.util.List;
@RestController
@RequestMapping("/api/v1/employees") // API 版本控制是 2026 的标配
public class EmployeeController {
@Autowired
private EmployeeService employeeService;
// GET: 获取所有员工
@GetMapping
public ResponseEntity<List> getAllEmployees() {
List employees = employeeService.getAllEmployees();
// 如果你使用的是 AI 代码助手，它会建议你这里检查 isEmpty() 并返回 204
return ResponseEntity.ok(employees);
}
// POST: 创建新员工 - 符合 REST 规范
@PostMapping
public ResponseEntity createEmployee(@RequestBody Employee employee) {
Employee savedEmployee = employeeService.createEmployee(employee);
// 201 Created + Location Header
URI location = URI.create(String.format("/api/v1/employees/%s", savedEmployee.id()));
return ResponseEntity.created(location).body(savedEmployee);
}
// GET: 获取单个员工 (展示路径变量)
@GetMapping("/{id}")
public ResponseEntity getEmployeeById(@PathVariable Integer id) {
// 注意：这里为了演示简化了逻辑，实际应使用 Optional.orElseThrow()
return employeeService.getAllEmployees().stream()
.filter(e -> e.id().equals(id))
.findFirst()
.map(ResponseEntity::ok)
.orElse(ResponseEntity.notFound().build());
}
}
从全局异常处理谈起：优雅地处理错误
你肯定遇到过这种情况：用户传入了一个错误的邮箱格式，或者数据库突然挂了。如果不处理，用户会看到一大堆红色的错误堆栈，这不仅不安全，也不专业。
在 2026 年，我们使用 @RestControllerAdvice 来全局捕获这些异常。让我们思考一下这个场景：
package com.example.demo.exception;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.Map;
@ControllerAdvice
public class GlobalExceptionHandler {
// 处理自定义的业务异常
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity handleResourceNotFound(ResourceNotFoundException ex) {
Map body = new HashMap();
body.put("timestamp", LocalDateTime.now());
body.put("message", ex.getMessage());
body.put("status", HttpStatus.NOT_FOUND.value());
return new ResponseEntity(body, HttpStatus.NOT_FOUND);
}
// 处理通用的参数校验错误
@ExceptionHandler(org.springframework.web.bind.MethodArgumentNotValidException.class)
public ResponseEntity handleValidationExceptions(
org.springframework.web.bind.MethodArgumentNotValidException ex) {
Map errors = new HashMap();
ex.getBindingResult().getFieldErrors().forEach(error ->
errors.put(error.getField(), error.getDefaultMessage())
);
return new ResponseEntity(errors, HttpStatus.BAD_REQUEST);
}
}
通过这种方式，无论发生什么错误，API 的响应格式都是统一且整洁的 JSON，这对前端开发者（或者是调用你 API 的 Agentic AI Agent）非常友好。
性能优化与可观测性：2026 年的必修课
当我们把代码部署到 Kubernetes 或 Serverless 环境中时，仅仅"能跑"是远远不够的。我们需要知道它"跑得怎么样"。
- 虚拟线程: 如果你使用的是 Java 21+（Spring Boot 3.2+ 原生支持），一定要尝试开启虚拟线程。只需在
application.properties中加一行：
spring.threads.virtual.enabled=true
这能让你的应用在同样的硬件上处理成倍的并发请求，这在高并发的 REST API 中是性能飞跃的关键。
- 结构化日志与追踪:
在我们的微服务架构中，一个请求可能经过几十个服务。如果出错了，怎么查？我们使用 Micrometer Tracing。
io.micrometer
micrometer-tracing-bridge-brave
配合 OpenTelemetry，我们可以实时在 Grafana 或 Jaeger 中看到请求的完整链路。
总结：我们的前进之路
在这篇文章中，我们从 GeeksforGeeks 的基础教程出发，一路探讨到了 2026 年 Java 开发的最前沿。我们不仅学习了如何构建一个简单的 Controller，还深入了 Record 特性、Repository 模式、全局异常处理以及虚拟线程的性能优化。
记住，技术永远在迭代。Agentic AI 可能会在未来几年接管更多的 CRUD 编写工作，但理解底层原理、架构设计以及如何与 AI 协作，将是我们作为工程师不可替代的核心竞争力。
现在，轮到你了。打开你的 IDE（最好是基于 AI 的），试着创建一个新项目，并在评论区告诉我你的体验。让我们拥抱变化，共同进化！