Práctica de API RESTful

Mejores prácticas de seguridad

1. Autenticación y autorización

// 使用 JWT Token 进行身份验证
GET /api/users/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

// API 响应包含用户权限检查
{
  "success": true,
  "data": {
    "id": 123,
    "name": "张三",
    "role": "user"
  }
}

2. Validación de entrada

// 服务器端验证示例
POST /api/users
{
  "email": "[email protected]",
  "password": "123"  // 密码太短
}

// 验证失败响应
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "密码长度至少为8位"
  }
}

3. HTTPS y cifrado de datos

✅ https://api.example.com/users
❌ http://api.example.com/users

Prácticas de optimización del rendimiento

1. Paginación de datos

// 避免一次返回大量数据
GET /api/users?page=1&limit=20

{
  "success": true,
  "data": [...], // 只返回20条记录
  "pagination": {
    "currentPage": 1,
    "totalPages": 50,
    "totalItems": 1000
  }
}

2. Filtrado de campos

// 只返回需要的字段
GET /api/users?fields=id,name,email

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "张三",
      "email": "[email protected]"
      // 不返回其他不需要的字段
    }
  ]
}

3. Estrategias de caché

// 使用缓存头
GET /api/users/123
Cache-Control: max-age=3600  // 缓存1小时

// 条件请求
GET /api/users/123
If-None-Match: "etag-value"

// 304 Not Modified (数据未变化)

Mejores prácticas de manejo de errores

Formato de error unificado

{
  "success": false,
  "error": {
    "code": "SPECIFIC_ERROR_CODE",    // 机器可读的错误码
    "message": "用户友好的错误信息",      // 人类可读的错误信息
    "details": {...},                // 详细错误信息（可选）
    "timestamp": "2024-01-15T10:00:00Z"
  }
}

Diseño de códigos de error comunes

const ERROR_CODES = {
  // 4xx 客户端错误
  'VALIDATION_ERROR': 400,        // 数据验证失败
  'UNAUTHORIZED': 401,            // 未授权
  'FORBIDDEN': 403,              // 禁止访问
  'NOT_FOUND': 404,              // 资源不存在
  'METHOD_NOT_ALLOWED': 405,     // 方法不允许
  'CONFLICT': 409,               // 资源冲突
  
  // 5xx 服务器错误
  'INTERNAL_ERROR': 500,         // 内部服务器错误
  'SERVICE_UNAVAILABLE': 503     // 服务不可用
}

Documentación de API

Uso de formato de documentación estandarizado

Se recomienda usar la especificación OpenAPI (Swagger):

# swagger.yaml 示例
openapi: 3.0.0
info:
  title: 用户管理 API
  version: 1.0.0
  description: 提供用户的增删改查功能

paths:
  /api/users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          description: 页码
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'

Estrategias de control de versiones

Control de versiones por URL (recomendado)

// 版本1
GET /api/v1/users

// 版本2（新增字段，保持向后兼容）
GET /api/v2/users
{
  "id": 1,
  "name": "张三",
  "email": "[email protected]",
  "avatar": "https://example.com/avatar.jpg"  // 新增字段
}

Manejo de compatibilidad

// 保持向后兼容的策略
{
  "deprecationWarning": "该 API 版本将在2024年6月1日后停止支持，请升级到 v2",
  "data": {...}
}

Ejercicios prácticos

Ejercicio 1: API de sistema de gestión de libros

Diseñe un sistema simple de gestión de libros con las siguientes funciones:

Análisis de requisitos

Gestionar información de libros (título, autor, ISBN, precio)
Gestionar categorías de libros
Compatible con alta, baja, modificación y consulta de libros
Compatible con filtrar libros por categoría

Ejercicio de diseño de API

Diseñe los siguientes endpoints de API：

// 你的任务：完善以下 API 设计

// 图书相关
GET    /api/books                    // 获取图书列表
GET    /api/books/{id}              // 获取特定图书
POST   /api/books                   // 创建新图书
PUT    /api/books/{id}              // 更新图书信息
DELETE /api/books/{id}              // 删除图书

// 分类相关
GET    /api/categories              // 获取分类列表
GET    /api/categories/{id}/books   // 获取分类下的图书

Estructura de datos de ejemplo:

{
  "id": 1,
  "title": "JavaScript 高级程序设计",
  "author": "Nicholas C. Zakas",
  "isbn": "9787115275790",
  "price": 99.00,
  "categoryId": 1,
  "category": {
    "id": 1,
    "name": "编程技术"
  },
  "publishedDate": "2012-03-01",
  "description": "深入理解JavaScript语言",
  "stock": 50
}

Tareas del ejercicio

Diseñe la documentación de la API: escriba ejemplos detallados de solicitudes y respuestas para cada endpoint
Manejo de errores: diseñe el formato de respuesta para diversas situaciones de error
Validación de datos: enumere las reglas de validación para cada campo
Casos de prueba: escriba comandos curl para probar cada API

Ejercicio 2: API de tareas pendientes

Cree una API de gestión de tareas pendientes:

Requisitos funcionales

Crear, ver, actualizar y eliminar tareas pendientes
Marcar el estado de completado de las tareas
Filtrar tareas por estado
Compatible con prioridad de tareas

Diseño del modelo de datos

{
  "id": 1,
  "title": "学习 RESTful API",
  "description": "完成 API 教程的学习",
  "status": "pending",  // pending, completed, cancelled
  "priority": "high",   // low, medium, high
  "dueDate": "2024-01-20",
  "createdAt": "2024-01-15T08:00:00Z",
  "updatedAt": "2024-01-15T08:00:00Z"
}

Tareas desafiantes

Operaciones por lotes: diseñe una API para actualizar el estado de tareas en lote
Función de búsqueda: compatible con búsqueda por título y descripción
Información estadística: devuelve estadísticas sobre el estado de finalización de tareas

Ejercicio 3: API de red social

Diseñe la API de una plataforma de redes sociales simplificada:

Funciones principales

Registro e inicio de sesión de usuarios
Publicar y ver publicaciones
Seguir a otros usuarios
Me gusta y comentarios

Diseño de la estructura de la API

// 用户相关
POST /api/auth/register     // 用户注册
POST /api/auth/login        // 用户登录
GET  /api/users/profile     // 获取个人资料

// 动态相关
GET  /api/posts            // 获取动态列表
POST /api/posts            // 发布新动态
GET  /api/posts/{id}       // 获取特定动态
DELETE /api/posts/{id}     // 删除动态

// 互动相关
POST /api/posts/{id}/like     // 点赞动态
POST /api/posts/{id}/comments // 添加评论
GET  /api/posts/{id}/comments // 获取评论列表

Diseño de funciones avanzadas

Sistema de seguimiento: relaciones de seguimiento entre usuarios
Notificaciones push: mecanismo de notificación de nuevas interacciones
Moderación de contenido: filtrado de contenido sensible

Otras extensiones