📌 第一部分：RESTful API 概览与定位

1.1 定义与全称

REST（Representational State Transfer，表述性状态转移）是由 Roy Fielding 于 2000 年在博士论文中提出的架构风格。RESTful API 是遵循 REST 原则的 Web API 设计规范，以 资源为中心，使用 HTTP 方法操作资源。

1.2 核心定位

RESTful API 的核心定位是 Web 服务的标准化设计风格。它提供了：

• 资源导向的 URI 设计
• 使用 HTTP 方法（GET、POST、PUT、DELETE、PATCH）
• 无状态通信（Stateless）
• 统一接口（Uniform Interface）
• 可缓存（Cacheable）
• 分层架构（Layered System）
• 自描述消息（Self-Descriptive Messages）

1.3 主要应用领域

• Web 服务： 前后端分离的 API 服务
• 移动应用后端： iOS、Android 应用的数据接口
• 微服务架构： 服务间通信
• 第三方 API： 开放平台接口
• SaaS 产品： 云服务 API
• 物联网： 设备数据接口

1.4 知名案例

• GitHub API： 最经典的 RESTful API 示例
• Stripe API： 支付服务 API
• Twitter API： 社交平台 API
• Spotify API： 音乐服务 API
• 阿里云 API： 云服务 API
• 微信公众平台 API： 小程序和服务号 API

---

⚙️ 第二部分：REST 核心原则

2.1 资源（Resource）

• 资源是核心： 一切皆是资源（用户、订单、商品）
• URI 标识： 每个资源有唯一的 URI
• 名词复数： 使用复数名词（/users、/orders）
• 层次结构： /users/123/orders

2.2 HTTP 方法

• GET： 获取资源（幂等、安全）
• POST： 创建资源（非幂等）
• PUT： 全量更新资源（幂等）
• PATCH： 部分更新资源（非幂等）
• DELETE： 删除资源（幂等）

2.3 状态码

• 200 OK： 请求成功
• 201 Created： 资源创建成功
• 204 No Content： 成功但无响应体
• 400 Bad Request： 请求参数错误
• 401 Unauthorized： 未认证
• 403 Forbidden： 无权限
• 404 Not Found： 资源不存在
• 409 Conflict： 资源冲突
• 422 Unprocessable： 验证失败
• 429 Too Many Requests： 请求过多
• 500 Internal Server Error： 服务器错误

2.4 URI 设计规范

# 好的 URI 设计
GET    /users              # 获取用户列表
GET    /users/123          # 获取单个用户
POST   /users              # 创建用户
PUT    /users/123          # 更新用户
DELETE /users/123          # 删除用户

# 关系资源
GET    /users/123/orders   # 获取用户的订单
GET    /users/123/orders/456 # 获取用户的某个订单

# 过滤/分页/排序
GET    /users?page=1&limit=20
GET    /users?sort=created_at&order=desc
GET    /users?age=18&status=active

# 搜索
GET    /users?q=john

# 字段选择
GET    /users?fields=id,name,email

# 嵌套资源
GET    /users/123/orders/456/items

2.5 无状态（Stateless）

• 每个请求包含所有必要信息
• 服务器不保存客户端状态
• 认证信息通过 Token 传递（JWT）
• 易于水平扩展

---

📝 第三部分：API 设计最佳实践

3.1 请求/响应格式

// 请求示例
GET /api/v1/users/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json

// 成功响应
{
    "code": 0,
    "data": {
        "id": 123,
        "name": "Alice",
        "email": "alice@example.com",
        "created_at": "2024-01-15T10:30:00Z"
    },
    "message": "success"
}

// 分页响应
{
    "code": 0,
    "data": {
        "items": [...],
        "pagination": {
            "page": 1,
            "limit": 20,
            "total": 150,
            "pages": 8
        }
    },
    "message": "success"
}

// 错误响应
{
    "code": 40001,
    "message": "Invalid email format",
    "errors": [
        {
            "field": "email",
            "message": "Email is required and must be valid"
        }
    ]
}

3.2 版本管理

• URL 版本： /api/v1/users
• Header 版本： Accept: application/vnd.example.v1+json
• 建议： 使用 URL 版本，更直观
• 兼容性： 至少保持一个版本兼容

3.3 认证与授权

• JWT： JSON Web Token，无状态认证
• Bearer Token： Authorization: Bearer {token}
• API Key： X-API-Key: {key}
• OAuth2： 第三方授权
• Basic Auth： 基础认证（需 HTTPS）

3.4 限流（Rate Limiting）

• 响应头：
  • X-RateLimit-Limit：限流总数
  • X-RateLimit-Remaining：剩余请求数
  • X-RateLimit-Reset：重置时间
• 策略： IP 限流、用户限流
• 响应： 429 Too Many Requests

3.5 文档（API Documentation）

• OpenAPI（Swagger）： 官方标准
• Postman Collection： 导出和分享
• Redoc： 美观的文档展示
• 内容： 描述请求/响应格式、状态码、认证方式

---

⚖️ 第四部分：RESTful vs GraphQL

对比项	RESTful	GraphQL
数据获取	固定端点	按需查询
过/欠获取	可能	不会
版本管理	URL 版本	Schema 演进
缓存	HTTP 缓存	需要自定义
学习曲线	平缓	较陡
适用场景	通用 API	复杂数据查询

4.1 选择建议

• RESTful： 简单 CRUD、通用 API、Cache 友好
• GraphQL： 复杂数据关系、客户端需求多样
• 混合使用： 可以同时提供两种 API

---

🧠 第五部分：学习建议

推荐学习资源

• Roy Fielding 博士论文： REST 架构风格
• 《RESTful Web APIs》—— 全面介绍
• OpenAPI 规范： swagger.io/specification
• Postman： API 测试和文档工具

---

🎯 总结升华