Spring Boot REST 服务

引言

RESTful Web Services 是基于 HTTP 协议 设计的标准化 Web API 架构风格，具备无状态、可扩展、轻量等核心特性，是现代软件开发的主流通信方案。在前后端分离、移动应用、微服务架构中，REST API 作为不同系统的交互桥梁，实现高效、标准化的数据通信。

Spring Boot 作为主流 Java 开发框架，通过极简注解、自动配置和开箱即用的功能，大幅降低了 REST API 的开发成本。REST 服务默认以 JSON 为数据交换格式（最常用），同时支持 XML、HTML 等格式，兼容性极强。

什么是 REST

REST 全称为 Representational State Transfer（表述性状态转移），是由 Roy Thomas Fielding 在 2000 年博士论文中提出的架构设计风格（并非协议或标准）。它的核心设计理念：充分利用 HTTP 协议的原生特性，实现分布式系统之间的简洁通信，是构建现代化 Web API 的事实标准

核心概念

资源

REST 以资源为核心，所有可被访问的数据、对象、服务都属于资源（如用户、商品、订单）。

资源通过 URI（统一资源标识符） 唯一标识
规范示例：/users（用户集合）、/users/1001（单个用户）、/products/200（单个商品）

无状态通信

REST 最核心的特性：服务器不存储任何客户端的会话状态。

每个请求必须包含完整的认证、参数等所有必要信息
优势：支持服务水平扩展，无状态是微服务架构的基础

资源表现形式

资源可以通过多种格式返回给客户端，主流格式：

JSON（首选，轻量、易解析）
XML
HTML
PDF/ 文本等

HTTP 方法

REST 严格遵循 HTTP 标准方法，对应数据的 CRUD 操作，同时具备安全 / 幂等性

HTTP 方法	操作	作用	安全性	幂等性
GET	读取	查询资源	是	是
POST	创建	新增资源	否	否
PUT	更新	全量更新资源	否	是
DELETE	删除	删除资源	否	是

名词解释
安全性：不会修改服务器数据
幂等性：多次执行相同请求，结果完全一致

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController // 核心注解：标记该类为 REST 控制器，所有方法返回 JSON
@RequestMapping("/users") // 统一父路径
public class UserController {

    // 1. GET：查询单个用户
    @GetMapping("/{userId}")
    public ResponseEntity<User> getUserById(@PathVariable Integer userId) {
        User user = userService.getById(userId);
        return ResponseEntity.ok(user);
    }

    // 2. GET：查询所有用户
    @GetMapping
    public ResponseEntity<List<User>> listUsers() {
        return ResponseEntity.ok(userService.listAll());
    }

    // 3. POST：新增用户
    @PostMapping
    public ResponseEntity<String> createUser(@RequestBody User user) {
        userService.save(user);
        return ResponseEntity.status(HttpStatus.CREATED).body("用户创建成功");
    }

    // 4. PUT：全量更新用户
    @PutMapping("/{userId}")
    public ResponseEntity<String> updateUser(
            @PathVariable Integer userId,
            @RequestBody User user) {
        userService.update(userId, user);
        return ResponseEntity.ok("用户更新成功");
    }

    // 5. DELETE：删除用户
    @DeleteMapping("/{userId}")
    public ResponseEntity<Void> deleteUser(@PathVariable Integer userId) {
        userService.delete(userId);
        return ResponseEntity.noContent().build(); // 204 无内容
    }
}

HTTP 状态码

REST API 通过状态码精准反馈请求结果，按类型分类：

成功响应（2xx）

200 OK：请求成功（查询 / 更新通用）
201 Created：资源创建成功（POST 专用）
204 No Content：请求成功，无返回数据（DELETE 专用）

客户端错误（4xx）

400 Bad Request：请求参数错误
401 Unauthorized：未认证（未登录）
403 Forbidden：无权限访问
404 Not Found：资源不存在
409 Conflict：资源冲突（如重复创建）

服务端错误（5xx）

500 Internal Server Error：服务器内部异常
503 Service Unavailable：服务不可用

RESTful 核心原则

原文仅列举部分，补充完整行业标准原则：

资源唯一标识：每个资源对应唯一 URI
统一接口：强制使用 GET/POST/PUT/DELETE 标准方法
无状态交互：服务器不存储会话，请求自给自足
可缓存性：支持 HTTP 缓存，提升性能
客户端 - 服务器解耦：前后端独立开发、独立迭代
分层系统：服务可分层部署（网关、应用、数据层），增强安全性

实现 REST API

核心依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

实体类

import lombok.Data;
@Data // 自动生成 getter/setter
public class User {
    private Integer userId;
    private String username;
    private Integer age;
}

业务逻辑

@Service
public class UserService {
    // 模拟数据库
    private final Map<Integer, User> userMap = new HashMap<>();

    public User getById(Integer id) {
        return userMap.get(id);
    }
    public void save(User user) {
        userMap.put(user.getUserId(), user);
    }
}

Controller

即上文 UserController，直接运行即可使用。

最佳实践

认证授权：使用 JWT 无状态认证、OAuth2.0 第三方授权
数据加密：强制使用 HTTPS 加密传输
输入校验：使用 Spring Validation 防止 SQL 注入、XSS 攻击
接口限流：防止恶意请求（如 Redis + Lua 实现限流）
权限控制：基于角色（RBAC）控制接口访问权限

RESTful 优势

轻量简单：基于 JSON，比 SOAP 的 XML 更简洁，开发成本低
前后端解耦：客户端与服务器独立开发、独立部署
高可扩展性：无状态特性支持服务水平扩容
兼容性强：支持所有编程语言、设备端
性能优异：支持 HTTP 缓存，减少带宽消耗

总结

REST 是架构风格，核心是资源 + HTTP 标准方法 + 无状态
Spring Boot 用 @RestController 极简开发 REST API，JSON 为默认数据格式
开发遵循：URI 标准化、HTTP 方法规范、状态码精准、无状态设计
企业级应用需配合：JWT 认证、全局异常处理、接口限流、版本控制