REST API 教程

基础概念

REST (Representational State Transfer) 是一种软件架构风格，用于设计网络应用程序的API。它基于HTTP协议，使用标准的HTTP方法(GET, POST, PUT, DELETE等)来操作资源。

REST API的核心原则包括：

• 客户端-服务器架构
• 无状态性(每个请求包含所有必要信息)
• 可缓存性
• 统一接口
• 分层系统
• 按需代码(可选)

优势

1. 简单性：使用标准的HTTP方法和状态码
2. 可扩展性：无状态特性使其易于扩展
3. 灵活性：支持多种数据格式(JSON, XML等)
4. 独立性：客户端和服务器可以独立开发和部署
5. 广泛支持：几乎所有编程语言和平台都支持REST

主要HTTP方法

| 方法 | 描述 | 幂等性 | 安全性 | |--------|--------------------------|--------|--------| | GET | 获取资源 | 是 | 是 | | POST | 创建资源 | 否 | 否 | | PUT | 更新整个资源 | 是 | 否 | | PATCH | 部分更新资源 | 否 | 否 | | DELETE | 删除资源 | 是 | 否 | | HEAD | 获取资源元数据 | 是 | 是 | | OPTIONS| 获取资源支持的通信选项 | 是 | 是 |

常见状态码

• 2xx 成功
  • 200 OK
  • 201 Created
  • 204 No Content
• 3xx 重定向
  • 301 Moved Permanently
  • 304 Not Modified
• 4xx 客户端错误
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
• 5xx 服务器错误
  • 500 Internal Server Error
  • 503 Service Unavailable

设计最佳实践

1. 使用名词而非动词表示资源
   • 好: /users 而不是 /getUsers

• 使用复数形式命名集合
  • /users 而不是 /user
• 使用小写字母和连字符(-)而非下划线(_)
• 避免在URI中使用文件扩展名
  • /users/1 而不是 /users/1.json
• 使用查询参数进行过滤、排序和分页
  • /users?active=true&sort=name&page=2&limit=10
• 使用适当的HTTP状态码
• 提供版本控制
  • /v1/users 或通过请求头控制

示例代码(Node.js/Express)

const express = require('express');
const app = express();
app.use(express.json());

let users = [
  { id: 1, name: 'John Doe', email: 'john@example.com' },
  { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
];

// 获取所有用户
app.get('/users', (req, res) => {
  res.status(200).json(users);
});

// 获取单个用户
app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ message: 'User not found' });
  res.status(200).json(user);
});

// 创建用户
app.post('/users', (req, res) => {
  const user = {
    id: users.length + 1,
    name: req.body.name,
    email: req.body.email
  };
  users.push(user);
  res.status(201).json(user);
});

// 更新用户
app.put('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ message: 'User not found' });
  
  user.name = req.body.name;
  user.email = req.body.email;
  
  res.status(200).json(user);
});

// 删除用户
app.delete('/users/:id', (req, res) => {
  const userIndex = users.findIndex(u => u.id === parseInt(req.params.id));
  if (userIndex === -1) return res.status(404).json({ message: 'User not found' });
  
  users.splice(userIndex, 1);
  res.status(204).send();
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

常见问题及解决方案

1. 跨域问题(CORS)
   • 原因：浏览器安全策略限制
   • 解决：在服务器端设置CORS头
   • 解决：在服务器端设置CORS头

• 认证与授权
  • 常见方案：JWT (JSON Web Token)
  • 示例：
  • 示例：
• 性能问题
  • 缓存策略：ETag, Last-Modified
  • 分页处理：/users?page=1&limit=10
  • 数据压缩：使用gzip中间件
• 版本控制
  • URL路径：/v1/users
  • 请求头：Accept: application/vnd.myapi.v1+json

测试工具

1. Postman - 功能强大的API测试工具
2. cURL - 命令行工具
3. cURL - 命令行工具
4. Swagger/OpenAPI - API文档和测试工具

应用场景

1. 移动应用后端
2. 单页应用(SPA)数据交互
3. 微服务架构中的服务间通信
4. 第三方API集成
5. 前后端分离架构

进阶主题

1. HATEOAS (Hypermedia as the Engine of Application State)
2. 速率限制(API限流)
3. 文档生成(Swagger/OpenAPI)
4. GraphQL与REST比较
5. gRPC与REST比较