搭建一个基于Django框架的WebApi项目

Django是一个强大的Python Web框架，以其“快速开发”和“不要重复自己”的原则闻名。到2026年，Django 5.x已成为主流版本，集成更强的异步支持和安全特性。本教程从零指导您搭建一个基于Django的Web API项目，使用Django REST Framework（DRF）实现RESTful API。示例项目：一个简单的“书籍管理”API，支持CRUD操作。整个过程基于Python 3.12+和Django 5.0+，适合初学者到中级开发者。

前提：确保您有Python环境（推荐虚拟环境）。如果没有，安装Python并用pip install virtualenv创建虚拟环境。

1. 环境准备

步骤1：创建虚拟环境

# 创建项目目录
mkdir django_api_project
cd django_api_project

# 创建并激活虚拟环境（Windows用Scripts\activate）
python -m venv venv
source venv/bin/activate  # Linux/Mac

# 升级pip
pip install --upgrade pip

步骤2：安装依赖

Django REST Framework是构建API的核心库。

pip install django djangorestframework

步骤3：创建Django项目

django-admin startproject book_api .

• book_api：项目名。
• .：在当前目录创建。

项目结构：

book_api/
├── manage.py
└── book_api/
    ├── __init__.py
    ├── asgi.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py

2. 创建应用（App）

API功能放在一个App中。

python manage.py startapp books

• books：App名。

添加App到settings.py的INSTALLED_APPS：

# book_api/settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',  # 添加DRF
    'books.apps.BooksConfig',  # 添加您的App
]

3. 定义模型（Models）

在books/models.py中定义Book模型。

# books/models.py
from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.CharField(max_length=100)
    published_date = models.DateField()
    description = models.TextField(blank=True)

    def __str__(self):
        return self.title

迁移数据库

python manage.py makemigrations
python manage.py migrate

4. 配置序列化器（Serializers）

DRF用序列化器将模型转为JSON。
在books/serializers.py创建：

# books/serializers.py
from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = '__all__'  # 或指定字段如 ['id', 'title', 'author']

5. 创建视图（Views）

使用DRF的ViewSet简化CRUD。
在books/views.py：

# books/views.py
from rest_framework import viewsets
from .models import Book
from .serializers import BookSerializer

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

6. 配置URL路由

项目级urls.py：

# book_api/urls.py
from django.contrib import admin
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from books.views import BookViewSet

router = DefaultRouter()
router.register(r'books', BookViewSet)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include(router.urls)),  # API根路径
]

7. 配置REST Framework

在settings.py添加DRF设置（可选，默认即可）：

# book_api/settings.py
REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10,  # 分页大小
}

8. 运行与测试

启动服务器

python manage.py runserver

• 访问：http://127.0.0.1:8000/api/books/ （浏览器显示DRF界面）。

创建超级用户（可选，管理后台）

python manage.py createsuperuser

• 访问/admin/添加书籍数据。

测试API

用Postman或curl：

• GET /api/books/：列出所有书籍。
• POST /api/books/：创建书籍（JSON: {“title”: “Django Book”, “author”: “Author”, “published_date”: “2026-01-01”}）。
• PUT /api/books/1/：更新ID=1的书籍。
• DELETE /api/books/1/：删除。

9. 优化与高级配置

• 认证与权限：在settings.py添加DEFAULT_AUTHENTICATION_CLASSES，如JWT或Token。

  REST_FRAMEWORK = {
      ...
      'DEFAULT_AUTHENTICATION_CLASSES': [
          'rest_framework.authentication.BasicAuthentication',
          'rest_framework.authentication.SessionAuthentication',
      ],
      'DEFAULT_PERMISSION_CLASSES': [
          'rest_framework.permissions.IsAuthenticated',
      ]
  }

• 异步支持：Django 5.x用ASGI（asgi.py），集成Celery处理后台任务。
• 部署：用Gunicorn + Nginx，数据库用PostgreSQL生产级。
• 安全：启用CORS（pip install django-cors-headers），配置ALLOWED_HOSTS。
• 文档：用DRF的Swagger（pip install drf-yasg），添加URL。

10. 常见问题排查

• No migrations：运行makemigrations和migrate。
• API 404：检查urls.py路由。
• 序列化错误：确保模型字段匹配。
• 性能：大项目用缓存（Redis）和分页。

通过这个项目，您已掌握Django API基础。建议扩展：添加用户认证、过滤器（search_fields）。如果需要完整代码或特定功能，欢迎评论交流～ 😄