Django REST Framework 快速入门指南：构建用户管理系统API

Django REST Framework 快速入门指南：构建用户管理系统API

django-rest-framework 项目地址: https://gitcode.com/gh_mirrors/dja/django-rest-framework

前言

本文将带你快速了解如何使用 Django REST Framework (DRF) 构建一个简单的 RESTful API。我们将创建一个用户管理系统，允许管理员查看和编辑系统中的用户和用户组。

环境准备与项目初始化

在开始之前，我们需要搭建开发环境并创建项目结构：

1. 创建项目目录并进入：

mkdir tutorial
cd tutorial

2. 创建并激活虚拟环境（推荐）：

python3 -m venv env
source env/bin/activate  # Windows使用 env\Scripts\activate

3. 安装必要依赖：

pip install djangorestframework

4. 创建Django项目和应用程序：

django-admin startproject tutorial .
cd tutorial
django-admin startapp quickstart
cd ..

这种将应用放在项目目录内的结构设计可以避免模块命名冲突问题。

5. 初始化数据库：

python manage.py migrate

6. 创建超级用户（后续API测试使用）：

python manage.py createsuperuser --username admin --email admin@example.com

数据序列化：Serializers

在DRF中，序列化器(Serializer)负责将复杂的数据类型（如Django模型实例）转换为Python原生数据类型，进而可以轻松转换为JSON等格式。

创建 tutorial/quickstart/serializers.py 文件：

from django.contrib.auth.models import Group, User
from rest_framework import serializers

class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ['url', 'username', 'email', 'groups']

class GroupSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Group
        fields = ['url', 'name']

这里我们使用了 HyperlinkedModelSerializer，它会自动为关联字段生成超链接，这是符合REST设计原则的做法。当然，你也可以使用其他类型的序列化器，如 ModelSerializer。

视图逻辑：Views

DRF的视图集(ViewSet)将常见的视图逻辑封装在一起，大大简化了代码。创建 tutorial/quickstart/views.py：

from django.contrib.auth.models import Group, User
from rest_framework import permissions, viewsets
from tutorial.quickstart.serializers import GroupSerializer, UserSerializer

class UserViewSet(viewsets.ModelViewSet):
    """
    用户管理API端点
    支持查看和编辑用户信息
    """
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer
    permission_classes = [permissions.IsAuthenticated]

class GroupViewSet(viewsets.ModelViewSet):
    """
    用户组管理API端点
    支持查看和编辑用户组信息
    """
    queryset = Group.objects.all().order_by('name')
    serializer_class = GroupSerializer
    permission_classes = [permissions.IsAuthenticated]

ModelViewSet 提供了完整的CRUD操作（创建、读取、更新、删除），我们只需要定义查询集和序列化类即可。

URL路由配置

DRF的路由器(Router)可以自动为视图集生成URL配置，极大简化了路由管理工作。编辑 tutorial/urls.py：

from django.urls import include, path
from rest_framework import routers
from tutorial.quickstart import views

router = routers.DefaultRouter()
router.register(r'users', views.UserViewSet)
router.register(r'groups', views.GroupViewSet)

urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

DefaultRouter 自动为我们生成了标准的RESTful路由，包括：

• /users/ - 用户列表和创建
• /users/{id}/ - 单个用户操作
• 同理适用于groups路由

分页配置

在实际应用中，我们通常需要对返回结果进行分页。在 tutorial/settings.py 中添加：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}

应用配置

最后，别忘了将DRF添加到已安装应用中，同样在 settings.py 中：

INSTALLED_APPS = [
    ...
    'rest_framework',
]

API测试

启动开发服务器：

python manage.py runserver

现在可以通过多种方式测试API：

1. 使用curl命令：

curl -u admin -H 'Accept: application/json; indent=4' http://127.0.0.1:8000/users/

2. 使用浏览器访问 http://127.0.0.1:8000/users/，记得使用右上角的登录功能进行认证

3. 使用HTTP客户端工具如httpie

总结

通过这个快速入门教程，我们完成了：

1. 项目环境搭建
2. 序列化器定义
3. 视图集创建
4. 自动URL路由配置
5. 分页设置
6. API测试

DRF的强大之处在于它提供了许多开箱即用的功能，同时保持了高度的可定制性。这个简单的用户管理系统API展示了DRF的核心概念，你可以在此基础上继续扩展功能。

django-rest-framework 项目地址: https://gitcode.com/gh_mirrors/dja/django-rest-framework