二、RESTful 语法规范
2.1 URL 命名规则
URL 命名规则:
- 用名词复数 表示资源集合：
/api/users（用户列表）、/api/orders（订单列表） - 用路径参数 表示单个资源：
/api/users/1（ID=1 的用户） - 避免 URL 包含动词：
/api/getUser（不推荐）、/api/deleteUser（不推荐） - 用查询参数 实现过滤 / 分页：
/api/users?page=1&size=10（分页查询用户）
2.2 HTTP 方法与操作映射
|-------------|----------|-----------------------|-----------------------|
| HTTP 方法 | 操作含义 | 示例 URL | 说明 |
| GET | 查询资源 | GET /api/users | 查询所有用户 |
| GET | 查询资源 | GET /api/users/1 | 查询 ID=1 的用户 |
| POST | 创建资源 | POST /api/users | 新增用户（请求体含用户信息） |
| PUT | 全量更新 | PUT /api/users/1 | 更新 ID=1 的用户（请求体含完整信息） |
| DELETE | 删除资源 | DELETE /api/users/1 | 删除 ID=1 的用户 |
2.3 案例：用户 API 设计
|----------|----------|-------------------|------------------------------------------------|----------------------------------------------|
| 接口功能 | 请求方法 | URL | 请求体 | 响应体 |
| 查询所有用户 | GET | /api/users | 无 | {"code":200,"message":"成功","data":[用户列表]} |
| 查询单个用户 | GET | /api/users/{id} | 无 | {"code":200,"message":"成功","data":用户对象} |
| 新增用户 | POST | /api/users | {"name":"张三","email":"zs@test.com","age":20} | {"code":201,"message":"创建成功","data":新用户对象} |
| 更新用户 | PUT | /api/users/{id} | {"name":"张三","email":"zs@new.com","age":21} | {"code":200,"message":"更新成功","data":更新后用户} |
| 删除用户 | DELETE | /api/users/{id} | 无 | {"code":200,"message":"删除成功","data":null} |
三、核心注解详解
3.1 控制器相关注解
|-------------------|-----------------------------------------------------------|-----------------------------------------------------------------------------------------|
| 注解 | 作用 | 案例 |
| @RestController | 标识 REST 控制器（= @Controller+ @ResponseBody），所有方法返回 JSON | @RestController @RequestMapping("/api/users") public class UserController { ... } |
| @GetMapping | 简化 GET 请求映射（等价于 @RequestMapping(method=GET)） | @GetMapping public Result<List<User>> getAllUsers() |
| @PostMapping | 简化 POST 请求映射 | @PostMapping public Result<User> addUser(...) |
| @PutMapping | 简化 PUT 请求映射 | @PutMapping("/{id}") public Result<User> updateUser(...) |
| @DeleteMapping | 简化 DELETE 请求映射 | @DeleteMapping("/{id}") public Result<Void> deleteUser(...) |
3.2 参数绑定注解
|-----------------|-----------------------------------------|----------------------------------------------------------------------------------------|
| 注解 | 作用 | 案例 |
| @PathVariable | 绑定 URL 路径参数（如 /users/{id}中的 id） | @GetMapping("/{id}") public Result<User> getUser(@PathVariable Integer id) { ... } |
| @RequestBody | 接收请求体中的 JSON 数据并转为 Java 对象 | @PostMapping public Result<User> addUser(@RequestBody User user) { ... } |
| @RequestParam | 获取 URL 查询参数（如 /users?page=1中的 page） | @GetMapping public Result<List<User>> getUsers(@RequestParam int page) { ... } |
3.3 异常处理注解
|---------------------|-----------------------|--------------------------------------------------------------------------------------------------------|
| 注解 | 作用 | 案例 |
| @ControllerAdvice | 标识全局异常处理类，可捕获所有控制器的异常 | @ControllerAdvice public class GlobalExceptionHandler { ... } |
| @ExceptionHandler | 定义异常处理方法，指定处理的异常类型 | @ExceptionHandler(ResourceNotFoundException.class) public Result<Void> handleNotFound(...) { ... } |