引言

在分布式系统和微服务架构盛行的今天，API 设计的规范性直接决定了开发效率和系统可维护性。本文将详解 RESTful API 设计规范，并剖析其带来的核心优势，助您构建优雅、高效的接口服务。

---

一、RESTful API 设计规范

1. 核心原则

• 无状态性：每个请求包含完整上下文信息，服务端不存储客户端状态。
• 资源导向：URI 仅表示资源（名词），HTTP 方法（GET/POST 等）定义操作类型。

2. URI 设计规则

• 命名规范

  • 使用复数名词表示资源集合（如 /users）
  • 层级资源用 / 分隔（如 /users/123/orders）
  • 小写字母+连字符（如 /product-categories）
    ❌ 避免 URI 中出现动词（如 /getUser）

• HTTP 方法语义

  方法	说明	示例
  GET	获取资源	GET /users
  POST	创建资源	POST /users
  PUT	全量更新资源	PUT /users/123
  PATCH	部分更新资源	PATCH /users/123
  DELETE	删除资源	DELETE /users/123