ninja 轻量级接口开发框架

Django Ninja是一个为Django设计的轻量级现代REST API框架，作者是乌克兰程序员Vitaliy Kucheryaviy。Django Ninja的灵感来源于FastAPI，Django Ninja框架集成了Pydantic，能够优雅的实现数据验证、序列化和自动生成Swagger文档，与学习曲线陡峭的“重量级”框架Django DRF相比，Django Ninja具有轻量级、开发体验友好、心智负担极低的特点。如果你喜欢简洁的FastAPI而非复杂的Django DRF但又不愿抛弃Django ORM，那Django Ninja绝对是你的不二之选。

官方网站：https://django-ninja.dev/

Github：https://github.com/vitalik/django-ninja

安装Django Ninja

在Django工程中，执行以下命令安装Django Ninja。

pip install django-ninja

框架安装完成后，在Django配置文件的INSTALLED_APPS中添加相关配置。

settings.py

INSTALLED_APPS = [
    # ... other apps
    'ninja',
]

注意实际上Django Ninja的核心功能并不需要在INSTALLED_APPS中添加ninja配置，这里添加配置的唯一作用是能让Swagger UI（或Redoc）的静态资源文件从本地staticfiles加载而非从网络CDN加载，如果你的开发环境能正常访问国际网络那么其实是不需要配置它的。

Django Ninja简单使用

我们这里创建一个最简单的Django工程，目录结构如下，其中api.py是我们新添加的Python源码文件，其中包含API接口的实现代码。

blog
  |_ blog            # Django APP
    |_ api.py        # Django Ninja的API接口实现
    |_ wsgi.py
    |_ urls.py
    |_ settings.py   # 工程配置文件
  |_ manage.py

api.py

from ninja import NinjaAPI

api = NinjaAPI()


@api.get('/hello')
def hello(request):
    return {'code': 0, 'message': 'Hello World'}

代码非常简单，我们定义了一个叫/hello的GET接口，它返回一个dict类型的数据，Django Ninja会将其序列化为JSON返回给客户端。api是NinjaAPI的实例，NinjaAPI是Django Ninja的核心类，在这里它的作用是API路由管理器，我们可以基于它使用@api.get()、@api.post()注册API端点，以及生成Django所需的URL配置。

编写好API接口实现后，我们还需要将其注册到Django的路由系统中，这需要用到api.urls属性，我们这里将其挂载到/api路径下。

urls.py

from django.contrib import admin
from django.urls import path

from blog.api import api

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', api.urls),
]

此时启动工程，我们可以使用浏览器访问http://localhost:8000/api/hello，查看响应结果。

Pydantic模型简介

Django Ninja使用Pydantic定义数据模型，数据的字段验证、序列化等都依赖Pydantic模型定义。我们这里继续之前的例子，添加一个schemas.py用于定义Pydantic数据模型。

blog
  |_ blog            # Django APP
    |_ api.py        # Django Ninja的API接口实现
    |_ schemas.py    # 数据模型定义
    |_ wsgi.py
    |_ urls.py
    |_ settings.py   # 工程配置文件
  |_ manage.py

Pydantic数据模型需要继承Django Ninja的Schema类，这里我们定义一个用户模型，包含ID、名字、邮箱等字段，其中is_active有默认值True，而birthday是一个可为None的日期类型。

schemas.py

from ninja import Schema
from datetime import date


class UserSchema(Schema):
    id: int
    username: str
    email: str
    is_active: bool = True
    birthday: date | None = None

接口实现中，我们编写一个POST接口，其中使用请求体接收我们的UserSchema数据模型并将受到的信息打印到控制台上。

api.py

from ninja import NinjaAPI

from blog.schemas import UserSchema

api = NinjaAPI()


@api.post('/add-user')
def hello(request, data: UserSchema):
    print(data.id)
    print(data.username)
    print(data.email)
    print(data.is_active)
    print(data.birthday)
    return {'code': 0, 'message': 'success'}

启动工程后，我们可以使用Postman等调试工具访问POST http://localhost:8000/api/add-user，如果我们的请求参数中缺少Pydantic数据模型定义的必填项，会发现服务端自动返回422 Unprocessable Entity，并给出了错误提示。有关如何定制错误处理逻辑，将在后文介绍，如果你对Pydantic并不熟悉，可以参考Python/第三方库/pydantic-数据模型验证库章节。

作者：Gacfox