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
- 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
- Gestion des erreurs: Concevoir des formats de réponse pour divers scénarios d'erreur
- Validation des données: Lister les règles de validation pour chaque champ
- 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
- Opérations par lots: Concevoir une API pour la mise à jour par lots des statuts de tâches
- Fonctionnalité de recherche: Prendre en charge la recherche par titre et description
- 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
- Système de suivi: Relations de suivi entre utilisateurs
- Notifications: Mécanisme de notification pour les nouvelles interactions
- Modération de contenu: Filtrage de contenu sensible