Django REST Framework 快速入门指南：构建用户管理系统API-优快云博客

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

【免费下载链接】django-rest-framework encode/django-rest-framework: Django REST framework 是一个强大的 Web API 开发工具包，专为 Django 框架设计，提供了一套丰富的功能集来构建 Web API，包括序列化、分页、权限管理等。项目地址: https://gitcode.com/gh_mirrors/dj/django-rest-framework

还在为构建用户管理API而烦恼？本文将带你从零开始，使用Django REST Framework快速构建一个功能完整的用户管理系统API，涵盖认证、权限、序列化等核心功能。

你将学到什么

✅ Django REST Framework核心概念和架构
✅ 用户模型的序列化和反序列化
✅ 基于Token的身份认证实现
✅ 细粒度权限控制策略
✅ ViewSet和Router的高效API构建
✅ 完整的用户CRUD操作实现

环境准备与项目初始化

1. 创建项目目录和虚拟环境

# 创建项目目录
mkdir user_management_api
cd user_management_api

# 创建虚拟环境
python3 -m venv env
source env/bin/activate  # Windows: env\Scripts\activate

# 安装必要依赖
pip install django djangorestframework django-cors-headers

2. 初始化Django项目

# 创建Django项目
django-admin startproject user_management .
cd user_management

# 创建用户管理应用
django-admin startapp users
cd ..

3. 项目结构概览

mermaid

核心配置设置

1. 基础配置 (settings.py)

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'rest_framework.authtoken',
    'corsheaders',
    'users',
]

# REST Framework配置
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.TokenAuthentication',
        'rest_framework.authentication.SessionAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ],
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20
}

# 中间件配置
MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware',
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

# CORS配置
CORS_ALLOWED_ORIGINS = [
    "http://localhost:3000",
    "http://127.0.0.1:3000",
]

# 数据库配置（使用SQLite）
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

用户模型与序列化器

1. 扩展用户模型 (users/models.py)

from django.contrib.auth.models import AbstractUser
from django.db import models

class CustomUser(AbstractUser):
    phone_number = models.CharField(max_length=15, blank=True, null=True)
    avatar = models.ImageField(upload_to='avatars/', blank=True, null=True)
    bio = models.TextField(blank=True, null=True)
    is_verified = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        verbose_name = '用户'
        verbose_name_plural = '用户管理'

    def __str__(self):
        return self.username

2. 用户序列化器 (users/serializers.py)

from rest_framework import serializers
from django.contrib.auth.models import Group
from .models import CustomUser

class UserSerializer(serializers.ModelSerializer):
    groups = serializers.SlugRelatedField(
        many=True,
        queryset=Group.objects.all(),
        slug_field='name',
        required=False
    )
    
    class Meta:
        model = CustomUser
        fields = [
            'id', 'username', 'email', 'first_name', 'last_name',
            'phone_number', 'avatar', 'bio', 'is_verified', 'is_active',
            'is_staff', 'date_joined', 'groups', 'last_login'
        ]
        read_only_fields = ['id', 'date_joined', 'last_login']
        extra_kwargs = {
            'password': {'write_only': True}
        }

    def create(self, validated_data):
        groups_data = validated_data.pop('groups', [])
        password = validated_data.pop('password', None)
        user = CustomUser(**validated_data)
        if password:
            user.set_password(password)
        user.save()
        
        for group_name in groups_data:
            group, _ = Group.objects.get_or_create(name=group_name)
            user.groups.add(group)
            
        return user

    def update(self, instance, validated_data):
        groups_data = validated_data.pop('groups', None)
        password = validated_data.pop('password', None)
        
        for attr, value in validated_data.items():
            setattr(instance, attr, value)
            
        if password:
            instance.set_password(password)
            
        instance.save()
        
        if groups_data is not None:
            instance.groups.clear()
            for group_name in groups_data:
                group, _ = Group.objects.get_or_create(name=group_name)
                instance.groups.add(group)
                
        return instance

class UserRegistrationSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True, min_length=8)
    password_confirm = serializers.CharField(write_only=True)

    class Meta:
        model = CustomUser
        fields = ['username', 'email', 'password', 'password_confirm']

    def validate(self, attrs):
        if attrs['password'] != attrs['password_confirm']:
            raise serializers.ValidationError("密码确认不匹配")
        return attrs

    def create(self, validated_data):
        validated_data.pop('password_confirm')
        user = CustomUser.objects.create_user(**validated_data)
        return user

视图与API端点实现

1. 用户视图集 (users/views.py)

from rest_framework import viewsets, status, permissions
from rest_framework.decorators import action
from rest_framework.response import Response
from django.contrib.auth.models import Group
from .models import CustomUser
from .serializers import UserSerializer, UserRegistrationSerializer

class UserViewSet(viewsets.ModelViewSet):
    queryset = CustomUser.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer
    permission_classes = [permissions.IsAuthenticated]

    def get_permissions(self):
        if self.action == 'create':
            return [permissions.AllowAny()]
        elif self.action == 'register':
            return [permissions.AllowAny()]
        return super().get_permissions()

    def get_serializer_class(self):
        if self.action == 'register':
            return UserRegistrationSerializer
        return super().get_serializer_class()

    @action(detail=False, methods=['post'], permission_classes=[permissions.AllowAny])
    def register(self, request):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = serializer.save()
        
        # 自动分配默认用户组
        user_group, created = Group.objects.get_or_create(name='普通用户')
        user.groups.add(user_group)
        
        return Response({
            'user': UserSerializer(user).data,
            'message': '用户注册成功'
        }, status=status.HTTP_201_CREATED)

    @action(detail=True, methods=['post'])
    def set_password(self, request, pk=None):
        user = self.get_object()
        password = request.data.get('password')
        
        if not password:
            return Response(
                {'error': '密码不能为空'}, 
                status=status.HTTP_400_BAD_REQUEST
            )
            
        user.set_password(password)
        user.save()
        return Response({'message': '密码设置成功'})

    @action(detail=True, methods=['post'])
    def deactivate(self, request, pk=None):
        user = self.get_object()
        user.is_active = False
        user.save()
        return Response({'message': '用户已停用'})

    @action(detail=True, methods=['post'])
    def activate(self, request, pk=None):
        user = self.get_object()
        user.is_active = True
        user.save()
        return Response({'message': '用户已激活'})

    @action(detail=False, methods=['get'])
    def me(self, request):
        serializer = self.get_serializer(request.user)
        return Response(serializer.data)

2. 认证视图 (users/views.py)

from rest_framework.authtoken.views import ObtainAuthToken
from rest_framework.authtoken.models import Token
from rest_framework.response import Response

class CustomAuthToken(ObtainAuthToken):
    def post(self, request, *args, **kwargs):
        serializer = self.serializer_class(data=request.data,
                                           context={'request': request})
        serializer.is_valid(raise_exception=True)
        user = serializer.validated_data['user']
        token, created = Token.objects.get_or_create(user=user)
        
        return Response({
            'token': token.key,
            'user_id': user.pk,
            'username': user.username,
            'email': user.email,
            'is_staff': user.is_staff
        })

路由配置

1. 应用路由 (users/urls.py)

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import UserViewSet, CustomAuthToken

router = DefaultRouter()
router.register(r'users', UserViewSet, basename='user')

urlpatterns = [
    path('', include(router.urls)),
    path('auth/login/', CustomAuthToken.as_view(), name='auth-login'),
]

2. 项目路由 (user_management/urls.py)

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

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('users.urls')),
    path('api-auth/', include('rest_framework.urls')),
]

数据库迁移与超级用户创建

# 应用数据库迁移
python manage.py makemigrations
python manage.py migrate

# 创建超级用户
python manage.py createsuperuser --username=admin --email=admin@example.com

# 启动开发服务器
python manage.py runserver

API端点详解

用户管理API端点

端点	方法	描述	权限要求
`/api/users/`	GET	获取用户列表	认证用户
`/api/users/`	POST	创建新用户	所有人
`/api/users/{id}/`	GET	获取用户详情	认证用户
`/api/users/{id}/`	PUT	更新用户信息	认证用户
`/api/users/{id}/`	DELETE	删除用户	管理员
`/api/users/register/`	POST	用户注册	所有人
`/api/users/me/`	GET	获取当前用户信息	认证用户
`/api/auth/login/`	POST	用户登录获取Token	所有人

认证流程示意图

mermaid

高级功能实现

1. 自定义权限类

# users/permissions.py
from rest_framework import permissions

class IsOwnerOrReadOnly(permissions.BasePermission):
    def has_object_permission(self, request, view, obj):
        if request.method in permissions.SAFE_METHODS:
            return True
        return obj == request.user

class IsAdminOrSelf(permissions.BasePermission):
    def has_object_permission(self, request, view, obj):
        return request.user.is_staff or obj == request.user

2. 用户过滤器

# users/filters.py
from django_filters import rest_framework as filters
from .models import CustomUser

class UserFilter(filters.FilterSet):
    username = filters.CharFilter(lookup_expr='icontains')
    email = filters.CharFilter(lookup_expr='icontains')
    is_active = filters.BooleanFilter()
    date_joined = filters.DateFromToRangeFilter()

    class Meta:
        model = CustomUser
        fields = ['username', 'email', 'is_active', 'is_staff', 'date_joined']

3. 集成过滤器到视图

# users/views.py (更新UserViewSet)
from django_filters import rest_framework as filters
from .filters import UserFilter

class UserViewSet(viewsets.ModelViewSet):
    # ... 其他代码不变 ...
    filter_backends = [filters.DjangoFilterBackend]
    filterset_class = UserFilter

测试API端点

1. 用户注册测试

# 使用curl测试用户注册
curl -X POST http://127.0.0.1:8000/api/users/register/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "testpassword123",
    "password_confirm": "testpassword123"
  }'

2. 用户登录测试

# 获取认证Token
curl -X POST http://127.0.0.1:8000/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "testpassword123"
  }'

3. 访问受保护端点

# 使用Token访问用户列表
curl -X GET http://127.0.0.1:8000/api/users/ \
  -H "Authorization: Token your_token_here"

错误处理与响应格式

标准响应格式

{
  "success": true,
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com"
  },
  "message": "操作成功"
}

错误响应格式

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "输入数据验证失败",
    "details": {
      "email": ["请输入有效的邮箱地址"]
    }
  }
}

部署建议与最佳实践

1. 生产环境配置

# settings.py 生产环境配置
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.TokenAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ],
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',
    ],
    'DEFAULT_PARSER_CLASSES': [
        'rest_framework.parsers.JSONParser',
    ],
    'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
}

# 安全配置
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

2. 性能优化建议

使用 select_related 和 prefetch_related 优化数据库查询
实现API缓存策略
使用分页控制返回数据量
启用Gzip压缩
使用CDN加速静态资源

总结与扩展建议

通过本教程，你已经成功构建了一个功能完整的用户管理系统API，具备以下特性：

✅ 用户注册、登录、认证功能
✅ 完整的CRUD操作
✅ Token-based身份验证
✅ 细粒度权限控制
✅ 数据验证和错误处理
✅ 可扩展的架构设计

下一步扩展方向

社交媒体登录集成：集成微信、微博等第三方登录
双因素认证：增加短信/邮箱验证码验证
用户行为日志：记录用户操作日志
实时通知：集成WebSocket实现实时消息推送
微服务架构：将用户服务拆分为独立微服务

常见问题解决

问题	解决方案
跨域问题	确保已安装并配置django-cors-headers
Token无效	检查Token格式和有效期
权限不足	验证用户角色和权限设置
数据库连接失败	检查数据库配置和连接字符串

现在你已经掌握了使用Django REST Framework构建用户管理系统API的核心技能，可以在此基础上继续扩展和优化你的应用了！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考