LoongLee's blog

Django Ninja

Django Ninja

定义

Django Ninja 是一个用于构建 API 的现代框架，基于 Django 和 Python 类型提示，提供高性能和自动文档生成功能。

核心特性

  • 类型安全：基于 Python 类型提示
  • 自动验证：使用 Pydantic 进行请求/响应验证
  • 自动文档：生成 OpenAPI/Swagger 文档
  • 高性能：异步支持，与 Django 原生性能相当
  • 简洁语法：代码量比 Django REST Framework 少

快速开始

安装

pip install django-ninja

基本使用

# api.py
from ninja import NinjaAPI

api = NinjaAPI()

@api.get("/hello")
def hello(request):
    return {"message": "Hello World"}

# urls.py
from django.urls import path
from .api import api

urlpatterns = [
    path("api/", api.urls),
]

Schema 定义

from ninja import Schema
from typing import Optional

class TaskIn(Schema):
    title: str
    description: Optional[str] = None
    priority: int = 1

class TaskOut(Schema):
    id: int
    title: str
    description: Optional[str]
    status: str

路由与视图

from ninja import Router
from .schemas import TaskIn, TaskOut
from .models import Task

router = Router()

@router.get("/tasks", response=list[TaskOut])
def list_tasks(request):
    return Task.objects.all()

@router.post("/tasks", response=TaskOut)
def create_task(request, payload: TaskIn):
    task = Task.objects.create(**payload.dict())
    return task

@router.get("/tasks/{task_id}", response=TaskOut)
def get_task(request, task_id: int):
    return Task.objects.get(id=task_id)

@router.put("/tasks/{task_id}", response=TaskOut)
def update_task(request, task_id: int, payload: TaskIn):
    task = Task.objects.get(id=task_id)
    for attr, value in payload.dict().items():
        setattr(task, attr, value)
    task.save()
    return task

@router.delete("/tasks/{task_id}")
def delete_task(request, task_id: int):
    Task.objects.get(id=task_id).delete()
    return {"success": True}

认证

from ninja.security import HttpBearer

class AuthBearer(HttpBearer):
    def authenticate(self, request, token):
        if token == "supersecret":
            return token
        return None

api = NinjaAPI(auth=AuthBearer())

@api.get("/private")
def private(request):
    return {"message": f"Auth: {request.auth}"}

权限控制

from ninja import permissions

@router.get("/admin-only", permissions=[permissions.IsAdminUser])
def admin_only(request):
    return {"message": "Admin access granted"}

分页

from ninja.pagination import paginate

@router.get("/tasks", response=list[TaskOut])
@paginate  # 默认分页
def list_tasks(request):
    return Task.objects.all()

文件上传

from ninja import File
from django.core.files.uploadedfile import UploadedFile

@router.post("/upload")
def upload(request, file: File[UploadedFile]):
    file_path = handle_upload(file)
    return {"file": file_path}

异步视图

@router.get("/async-tasks")
async def list_tasks_async(request):
    tasks = await Task.objects.all().async_list()
    return tasks

文档自动生成

启动服务器后访问： - Swagger UI: /api/docs - ReDoc: /api/redoc - OpenAPI Schema: /api/openapi.json

与 Django REST Framework 对比

特性 Django Ninja DRF
类型提示 ✅ 原生 ⚠️ 需要第三方库
自动文档 ✅ 内置 ✅ 需安装 drf-yasg
异步支持 ✅ ⚠️ 有限
性能 ✅ 更快 一般
社区规模 较小 很大
学习曲线 低 中等

相关技术

  • Django - Web 框架
  • Pydantic - 数据验证库
  • FastAPI - 类似理念的 API 框架
  • OpenAPI - API 规范

录入自: Django开发实践笔记