Pratique de l'API RESTful

Bonnes pratiques de sécurité

1. Authentification et autorisation

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

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

2. Validation des entrées

// 服务器端验证示例
POST /api/users
{
  "email": "test@example.com",
  "password": "123"  // 密码太短
}

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

3. HTTPS et chiffrement des données

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

Pratiques d'optimisation des performances

1. Pagination des données

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

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

2. Filtrage des champs

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

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

3. Stratégies de mise en cache

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

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

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

Bonnes pratiques de gestion des erreurs

Format d'erreur unifié

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

Conception des codes d'erreur courants

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     // 服务不可用
}

Documentation de l'API

Utiliser des formats de documentation standardisés

Il est recommandé d'utiliser la spécification 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'

Stratégies de gestion de version

Versionnement par URL (recommandé)

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

// 版本2(新增字段,保持向后兼容)
GET /api/v2/users
{
  "id": 1,
  "name": "张三",
  "email": "zhangsan@example.com",
  "avatar": "https://example.com/avatar.jpg"  // 新增字段
}

Gestion de la compatibilité

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

Exercices pratiques

Exercice 1 : API de système de gestion de bibliothèque

Concevez un système simple de gestion de bibliothèque avec les fonctionnalités suivantes :

Analyse des besoins

  • Gérer les informations sur les livres (titre, auteur, ISBN, prix)
  • Gérer les catégories de livres
  • Prendre en charge les opérations CRUD pour les livres
  • Prendre en charge le filtrage des livres par catégorie

Exercice de conception d'API

Veuillez concevoir les points de terminaison d'API suivants ::

// 你的任务:完善以下 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   // 获取分类下的图书

Exemple de structure de données :

{
  "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
}

Tâches de l'exercice

  1. Concevoir la documentation de l'API: Rédiger des exemples détaillés de requête et de réponse pour chaque point de terminaison
  2. Gestion des erreurs: Concevoir des formats de réponse pour divers scénarios d'erreur
  3. Validation des données: Lister les règles de validation pour chaque champ
  4. Cas de test: Écrire des commandes curl pour tester chaque API

Exercice 2 : API de liste de tâches

Créer une API de gestion de tâches :

Exigences fonctionnelles

  • Créer, consulter, mettre à jour et supprimer des tâches
  • Marquer le statut d'achèvement d'une tâche
  • Filtrer les tâches par statut
  • Prendre en charge la priorité des tâches

Conception du modèle de données

{
  "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"
}

Tâches de défi

  1. Opérations par lots: Concevoir une API pour la mise à jour par lots des statuts de tâches
  2. Fonctionnalité de recherche: Prendre en charge la recherche par titre et description
  3. Statistiques: Renvoyer des données statistiques sur l'achèvement des tâches

Exercice 3 : API de médias sociaux

Concevoir une API pour une plateforme de médias sociaux simplifiée :

Fonctionnalités principales

  • Inscription et connexion des utilisateurs
  • Publier et consulter des fils d'actualité
  • Suivre d'autres utilisateurs
  • Aimer et commenter

Conception de la structure de l'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 // 获取评论列表

Conception de fonctionnalités avancées

  1. Système de suivi: Relations de suivi entre utilisateurs
  2. Notifications: Mécanisme de notification pour les nouvelles interactions
  3. Modération de contenu: Filtrage de contenu sensible
Autres extensions