RESTful API 设计

设计 RESTful API 时建议遵循：

• 使用资源名而非动词（如 /users 而非 /getUsers）
• 使用合适的 HTTP 方法（GET/POST/PUT/PATCH/DELETE）
• 返回统一响应格式（包含 code/message/data）
• 使用分页、过滤与排序参数

示例响应格式：

{ "code": 200, "message": "success", "data": {...} }

---

设计规范要点

• 使用资源路径表示实体（复数名词），例如 /api/users。
• 使用HTTP方法表达操作：GET（查询）、POST（创建）、PUT/PATCH（更新）、DELETE（删除）。
• 使用状态码表达结果：200/201/204/400/401/403/404/500 等。
• 请求与响应使用统一的包裹结构（如 {code,message,data}）。
• 支持分页、排序与筛选参数（page, size, sort）。

控制器设计示例

@RestController
@RequestMapping("/api/users")
public class UserController {

	@GetMapping
	public Result<Page<UserDTO>> list(@RequestParam(defaultValue = "0") int page,
									  @RequestParam(defaultValue = "10") int size) {
		Page<UserDTO> result = userService.list(page, size);
		return Result.success(result);
	}

	@GetMapping("/{id}")
	public Result<UserDTO> get(@PathVariable Long id) {
		return Result.success(userService.getById(id));
	}

	@PostMapping
	public Result<UserDTO> create(@Valid @RequestBody CreateUserDTO dto) {
		UserDTO created = userService.create(dto);
		return Result.success(created);
	}

	@PatchMapping("/{id}")
	public Result<UserDTO> update(@PathVariable Long id, @RequestBody UpdateUserDTO dto) {
		return Result.success(userService.update(id, dto));
	}

	@DeleteMapping("/{id}")
	public Result<Void> delete(@PathVariable Long id) {
		userService.delete(id);
		return Result.success(null);
	}
}

统一响应结构（示例）

@Data
public class Result<T> {
	private Integer code;
	private String message;
	private T data;

	public static <T> Result<T> success(T data) {
		Result<T> r = new Result<>();
		r.code = 200;
		r.message = "success";
		r.data = data;
		return r;
	}

	public static <T> Result<T> error(int code, String message) {
		Result<T> r = new Result<>();
		r.code = code;
		r.message = message;
		r.data = null;
		return r;
	}
}

错误处理与异常映射

使用 @RestControllerAdvice 统一转换异常为标准响应：

@RestControllerAdvice
public class GlobalExceptionHandler {
	@ExceptionHandler(MethodArgumentNotValidException.class)
	public Result<?> handleValidation(MethodArgumentNotValidException ex) {
		String msg = ex.getBindingResult().getFieldErrors().stream()
			.map(e -> e.getField() + ": " + e.getDefaultMessage())
			.collect(Collectors.joining("; "));
		return Result.error(400, msg);
	}

	@ExceptionHandler(NotFoundException.class)
	public Result<?> handleNotFound(NotFoundException ex) {
		return Result.error(404, ex.getMessage());
	}

	@ExceptionHandler(Exception.class)
	public Result<?> handleThrowable(Exception ex) {
		log.error("系统异常", ex);
		return Result.error(500, "系统错误");
	}
}

分页与排序（建议）

• 使用 PageRequest / Pageable（Spring Data）或自定义 page/size 参数。
• 返回分页元数据（total、page、size、items）。

版本管理

• 将 API 版本放在路径中，例如 /api/v1/users，便于后续迭代和灰度升级。

安全与认证

• 推荐使用 JWT 或 OAuth2，确保接口幂等性和权限控制。

性能与最佳实践

• 对大查询使用分页和流式处理，避免一次性返回大量数据。
• 对热点接口使用缓存（如 Redis）并设置合适的过期策略。
• 使用限流与熔断防止流量突发影响后端。

小结

RESTful API 的设计要兼顾可用性、可扩展性与易维护性。遵循统一规范、提供良好版本管理和异常处理，会让 API 更可靠也更易被消费。