RESTful API 接口设计规范详解

这种方式的好处是浏览器、CDN、代理服务器都能直接根据 URL 来缓存响应结果，不同的 URL 可以分别缓存，更容易区分。

4. 版本控制

随着业务发展，接口需要更新升级，为了不影响老用户，可以在 URI 中标明版本。

• /v1/users — 第一版用户接口
• /v2/users — 第二版用户接口

5. 保持无状态

无状态是 RESTful 架构的核心约束之一。其含义是，服务器不应保存客户端的会话状态。每个来自客户端的请求都必须包含处理该请求所需的全部信息（如身份凭证、上下文等）。

典型实现方式：

1. 用户登录后，服务器生成一个唯一的身份凭证（如 Token），并将其返回给客户端。
2. 此后客户端的每一个请求都必须在 HTTP 标头（如 Authorization: Bearer <token>）中携带此凭证。
3. 服务器不关心请求之间的关联，仅根据当前请求提供的 Token 和参数进行验证、处理并返回响应。

这样做带来的关键优势：

• 极高的可扩展性：由于请求完全独立，无需会话亲和性，任何服务器实例都能处理任何请求。
• 简化服务器设计：服务器无需实现复杂的状态同步、会话存储和清理机制。
• 提升可靠性：单点故障的影响更小，客户端请求可以无缝地由其他可用服务器处理。

三、服务端给出响应

1. 统一响应格式

目前大多数 RESTful API 基本都使用 JSON 格式，因为轻量、容易解析，但并不是强制的，也可以用 XML 等格式。

JSON 格式示例：

{"id": 123, "name": "张三", "email": "[email protected]"}

XML 格式示例：

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <id>123</id>
  <name>张三</name>
  <email>[email protected]</email>
</user>

2. 返回合适的 HTTP 状态码

响应需要带上合适的状态码，前端开发者或运维人员通过查看状态码，就能快速定位问题方向。

HTTP 状态码大致可以分为 5 类：

1. 1xx 系列：信息提示
   • 100 Continue：继续请求
2. 2xx 系列：成功
   • 200 OK：请求成功，正常返回数据（用于 GET、PUT、PATCH）
   • 201 Created：创建成功（用于 POST 请求），通常会在响应头的 Location 中返回新的资源地址 URI
   • 202 Accepted：请求已接受，但还在处理中（常用于异步操作）
   • 204 No Content：请求成功，但无返回数据（常用于 DELETE）
3. 3xx 系列：重定向
   • 301 Moved Permanently：请求的资源已永久移动到新位置
   • 302 Found：请求的资源已临时移动到新位置
   • 304 Not Modified：资源未修改，客户端可以使用缓存
4. 4xx 系列：客户端错误
   • 400 Bad Request：请求参数格式错误
   • 401 Unauthorized：未验证身份，需要登录
   • 403 Forbidden：已认证但没有权限访问
   • 404 Not Found：资源不存在
   • 405 Method Not Allowed：请求方法不被允许
   • 409 Conflict：请求冲突（比如尝试创建已存在的资源）
   • 422 Unprocessable Entity：请求格式正确，但语义错误（比如邮箱格式不对）
   • 429 Too Many Requests：请求过于频繁，触发限流
5. 5xx 系列：服务器错误
   • 500 Internal Server Error：服务器内部错误
   • 502 Bad Gateway：网关错误
   • 503 Service Unavailable：服务器暂时不可用
   • 504 Gateway Timeout：网关超时

四、RESTful 六大约束

1. Client-Server（客户端 - 服务器分离）：前后端各干各的活，前端负责展示，后端负责数据处理，互不干扰。
2. Stateless（无状态）：每次请求都是独立的，服务器不保持客户端的会话信息，必要信息都在请求中。
3. Cacheable（可缓存）：服务器的响应可以被标记为可缓存，客户端可以重用缓存数据，减少服务器压力，提升性能。
4. Layered System（分层系统）：客户端不需要知道直接连接的是服务器还是中间层，系统可以灵活加代理、网关、负载均衡器等。
5. Uniform Interface（统一接口）：所有资源都通过统一的接口访问，降低理解成本，提高可维护性。
6. Code-On-Demand（按需代码）：可选性，服务器可以返回可执行代码（比如 JavaScript）给客户端执行，但实际工作中很少用。

很少有 API 能完美符合所有约束，大家可以灵活自行组合。只要团队达成一致，舒服就行。虽然用名词符合 RESTful 规范，但有同学会觉得用动词更直观易懂，也没问题。建议养成遵循 RESTful 的好习惯，写出更漂亮的接口。

五、开发与测试实践

1. 使用开发框架

几乎所有主流的开发框架都支持 RESTful API 的开发，他们能帮你自动处理很多细节。比如 Java 的 Spring Boot、Python 的 Django REST Framework、Go 的 Gin。这些框架虽然不强制你遵循 RESTful，但用他们的特性开发起来轻松又规范，帮你省掉大量重复代码。

2. 利用工具辅助

借助 AI 工具辅助编写样板代码也是一种高效方式。只需简单描述需求，AI 就能生成规范的 Controller 代码结构，大大减少重复劳动。

例如使用 Spring Boot 编写用户管理接口：

package com.example.usermanagement.controller;

import com.example.usermanagement.dto.UserRequest;
import com.example.usermanagement.dto.UserResponse;
import com.example.usermanagement.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
@Tag(name = "用户管理", description = "用户管理相关 API")
public class UserController {

    private final UserService userService;

    @PostMapping
    @Operation(summary = "创建用户")
    @PreAuthorize("hasRole('ADMIN')")
    public ResponseEntity<UserResponse> createUser(@Valid @RequestBody UserRequest userRequest) {
        UserResponse userResponse = userService.createUser(userRequest);
        return ResponseEntity.status(HttpStatus.CREATED).body(userResponse);
    }

    @GetMapping("/{id}")
    @Operation(summary = "根据 ID 获取用户")
    public ResponseEntity<UserResponse> getUserById(@Parameter(description = "用户 ID") @PathVariable Long id) {
        UserResponse userResponse = userService.getUserById(id);
        return ResponseEntity.ok(userResponse);
    }

    @GetMapping
    @Operation(summary = "获取用户列表（分页）")
    @PreAuthorize("hasRole('ADMIN')")
    public ResponseEntity<Page<UserResponse>> getAllUsers(
            @PageableDefault(size = 20, sort = "createdAt", direction = Sort.Direction.DESC) Pageable pageable) {
        Page<UserResponse> users = userService.getAllUsers(pageable);
        return ResponseEntity.ok(users);
    }

    @PutMapping("/{id}")
    @Operation(summary = "更新用户信息")
    public ResponseEntity<UserResponse> updateUser(
            @Parameter(description = "用户 ID") @PathVariable Long id,
            @Valid @RequestBody UserRequest userRequest) {
        UserResponse userResponse = userService.updateUser(id, userRequest);
        return ResponseEntity.ok(userResponse);
    }

    @DeleteMapping("/{id}")
    @Operation(summary = "删除用户")
    @PreAuthorize("hasRole('ADMIN')")
    public ResponseEntity<Void> deleteUser(@Parameter(description = "用户 ID") @PathVariable Long id) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();
    }
}

3. 生成文档

写完接口后还可以用 Swagger 这类工具，自动生成漂亮的文档。直接甩给前端，对方一看就懂，还能在线测试接口，省去大量沟通成本。

六、总结

RESTful API 有以下优点：

• 统一规范接口
• 提高开发效率
• 降低团队沟通成本

遵循良好的 API 设计规范，能让你的服务更加健壮、易维护且易于扩展。