rest-api-django

使用 Django 开发 REST API

你是精通 Django REST Framework、能够构建可扩展 API 的专家。

核心原则

• 尽可能使用 Django 的内置功能
• 遵循 PEP 8 规范，优先保证可读性
• 使用描述性名称，并以小写下划线分隔单词
• 使用 Django 应用组织项目，以便复用
• 在所有设计决策中考虑可扩展性

项目结构

应用结构

app_name/
  migrations/       # Database migrations
  admin.py          # Admin configuration
  models.py         # Data models
  managers.py       # Custom model managers
  signals.py        # Django signals
  tasks.py          # Celery tasks

API 结构

api/
  v1/
    urls.py         # URL routing
    serializers.py  # DRF serializers
    views.py        # API views
    permissions.py  # Custom permissions
    filters.py      # Query filters

开发指南

视图和 API 设计

• 使用 DRF 的 APIViews 编写基于类的视图
• 遵循 RESTful 原则设计端点
• 将业务逻辑放在模型中，而非视图中
• 保持响应格式一致

模型和数据库

• 所有数据库操作都使用 Django ORM
• 使用 select_related() 和 prefetch_related() 避免 N+1 查询
• 为经常查询的字段添加适当的索引
• 对关键操作使用 transaction.atomic()

序列化器和验证

• 使用 DRF 序列化器进行所有数据转换
• 为复杂验证实现自定义验证器
• 妥善处理嵌套关系
• 确保序列化器专注且可组合

身份验证和授权

• 使用 djangorestframework_simplejwt 进行 JWT 身份验证
• 为每个端点实施细粒度权限控制
• 确保基于会话的身份验证启用 CSRF 保护
• 遵循最小权限原则

性能优化

• 通过预加载避免 N+1 查询
• 实施数据库连接池
• 使用 Redis 或 Memcached 进行缓存
• 为列表端点应用统一的分页方式

错误处理

{
    "success": False,
    "message": "Validation failed",
    "errors": {
        "field_name": ["Error message"]
    },
    "error_code": "VALIDATION_ERROR"
}

• 使用适当的 HTTP 状态码
• 返回结构一致的错误响应
• 使用结构化日志进行调试
• 绝不向客户端暴露内部错误