Django开发环境配置与项目初始化指南-代码聚汇网

Django开发环境配置与项目初始化指南

为了晴子

1. Django 开发环境配置与项目初始化

1.1 Python 环境搭建

作为 Django 开发的基础，Python 环境的正确配置至关重要。我推荐使用 Python 3.11 版本，这是目前 Django 4.2 官方支持的最新稳定版本之一。

在 Ubuntu 系统上配置 Python 环境的完整步骤如下：

bash复制# 添加 deadsnakes PPA 源（包含多个 Python 版本）
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update

# 安装 Python 3.11 及必要组件
sudo apt install python3.11 python3.11-venv python3.11-dev

# 验证安装
python3.11 --version

提示：python3.11-venv 包提供了虚拟环境支持，python3.11-dev 包含开发所需的头文件和静态库。在生产环境中，这些组件都是必需的。

1.2 项目虚拟环境创建

虚拟环境是 Python 项目管理的标准做法，它能有效隔离不同项目的依赖关系。我习惯在项目根目录下创建名为 .venv 的虚拟环境：

bash复制cd /path/to/your/project
python3.11 -m venv .venv

激活虚拟环境的方法：

bash复制source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

激活后，终端提示符前会出现 (.venv) 标记，表示当前处于虚拟环境中。

1.3 依赖管理实践

在虚拟环境中安装 Django 及其他依赖：

bash复制# 更新 pip 工具
python -m pip install --upgrade pip

# 安装 Django 4.2.x 系列最新版本
pip install django~=4.2.0

# 安装代码格式化工具（开发用）
pip install black

依赖管理的两个重要命令：

bash复制# 生成 requirements.txt
pip freeze > requirements.txt

# 根据 requirements.txt 安装依赖
pip install -r requirements.txt

经验分享：我习惯在项目根目录下维护 requirements.txt 文件，并在每次添加新依赖后立即更新它。这能确保团队协作时环境的一致性。

2. Django 项目创建与基础配置

2.1 项目初始化

使用 django-admin 创建新项目时，我推荐在项目目录下直接初始化（注意末尾的点）：

bash复制django-admin startproject learn_django .

这种做法的好处是：

项目文件直接生成在当前目录，结构更清晰
避免了嵌套的项目目录结构
便于后续部署配置

2.2 数据库配置

Django 默认使用 SQLite 数据库，适合开发环境。初始化数据库的命令：

bash复制python manage.py migrate

对于生产环境，我强烈推荐使用 PostgreSQL。在 settings.py 中配置数据库：

python复制DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

2.3 环境变量管理

使用 environs 包管理敏感配置是行业最佳实践：

bash复制pip install "environs[django]"

创建 .env 文件示例：

code复制DATABASE_URL=postgres://user:password@localhost:5432/dbname
DEBUG=False
SECRET_KEY=your-secret-key
ALLOWED_HOSTS=yourdomain.com
CSRF_TRUSTED_ORIGINS=http://yourdomain.com

对应的 settings.py 配置：

python复制from environs import Env

env = Env()
env.read_env()

SECRET_KEY = env.str("SECRET_KEY")
DEBUG = env.bool("DEBUG", default=False)
ALLOWED_HOSTS = env.list("ALLOWED_HOSTS", default=["localhost", "127.0.0.1"])

# 数据库配置
DB_URL_STR = env.str("DATABASE_URL", default="")
if "sqlite3" in DB_URL_STR:
    DATABASES = {
        "default": {
            "ENGINE": "django.db.backends.sqlite3",
            "NAME": BASE_DIR / "db.sqlite3",
        }
    }
else:
    DATABASES = {
        "default": env.dj_db_url("DATABASE_URL"),
    }

CSRF_TRUSTED_ORIGINS = env.list(
    "CSRF_TRUSTED_ORIGINS", 
    default=["http://localhost", "http://127.0.0.1"]
)

安全提示：永远不要将 .env 文件提交到版本控制系统！确保它在 .gitignore 中。

3. Django 应用开发全流程

3.1 创建应用

创建一个名为 posts 的应用：

bash复制python manage.py startapp posts

然后在 settings.py 中注册应用：

python复制INSTALLED_APPS = [
    # ...
    "posts",
]

3.2 模型设计

在 posts/models.py 中定义模型：

python复制from django.db import models

class Post(models.Model):
    text = models.TextField()
    
    def __str__(self):
        return self.text[:50]

模型变更后执行迁移：

bash复制python manage.py makemigrations posts
python manage.py migrate

3.3 视图与URL配置

创建基于类的视图（posts/views.py）：

python复制from django.views.generic import ListView
from .models import Post

class HomePageView(ListView):
    model = Post
    template_name = "home.html"

配置 URL 路由（posts/urls.py）：

python复制from django.urls import path
from .views import HomePageView

urlpatterns = [
    path("", HomePageView.as_view(), name="home"),
]

在主 URL 配置中引入（learn_django/urls.py）：

python复制from django.urls import path, include

urlpatterns = [
    path("", include("posts.urls")),
]

3.4 模板系统

创建 templates/home.html：

html复制<!DOCTYPE html>
<html>
<head>
    <title>Message Board</title>
</head>
<body>
    <h1>Message Board Homepage</h1>
    <ul>
        {% for post in object_list %}
            <li>{{ post.text }}</li>
        {% endfor %}
    </ul>
</body>
</html>

确保 settings.py 中正确配置了模板路径：

python复制TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        # ...
    },
]

4. Django 后台管理与测试

4.1 后台管理配置

注册模型到后台（posts/admin.py）：

python复制from django.contrib import admin
from .models import Post

admin.site.register(Post)

创建超级用户：

bash复制python manage.py createsuperuser

4.2 测试实践

Django 提供了强大的测试框架。测试示例（posts/tests.py）：

python复制from django.test import TestCase
from django.urls import reverse
from .models import Post

class HomepageTests(TestCase):
    @classmethod
    def setUpTestData(cls):
        Post.objects.create(text="This is a test post")

    def test_url_exists_at_correct_location(self):
        response = self.client.get("/")
        self.assertEqual(response.status_code, 200)

    def test_url_available_by_name(self):
        response = self.client.get(reverse("home"))
        self.assertEqual(response.status_code, 200)

    def test_template_name_correct(self):
        response = self.client.get(reverse("home"))
        self.assertTemplateUsed(response, "home.html")

    def test_template_content(self):
        response = self.client.get(reverse("home"))
        self.assertContains(response, "Message Board Homepage")
        self.assertContains(response, "This is a test post")

运行测试：

bash复制python manage.py test

5. 生产环境部署

5.1 部署架构选择

对于小型项目，我推荐 WSGI + WhiteNoise 方案：

安装必要依赖：

bash复制pip install gunicorn==20.1.0
pip install whitenoise==6.12.0

配置 settings.py：

python复制INSTALLED_APPS = [
    "whitenoise.runserver_nostatic",
    # ...
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",
    # ...
]

STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
STORAGES = {
    "staticfiles": {
        "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage",
    },
}

收集静态文件：

bash复制python manage.py collectstatic

5.2 使用 Gunicorn 运行

启动命令：

bash复制gunicorn learn_django.wsgi:application --bind 0.0.0.0:8000

对于生产环境，建议使用进程管理器如 systemd 或 supervisor 来管理 Gunicorn。

5.3 PostgreSQL 数据库配置

安装 PostgreSQL：

bash复制sudo apt update
sudo apt install postgresql postgresql-contrib

创建数据库和用户：

bash复制sudo -u postgres psql
CREATE DATABASE dbname;
CREATE USER username WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE dbname TO username;
\q

配置 .env 文件：

code复制DATABASE_URL=postgres://username:password@localhost:5432/dbname

6. 开发工作流与最佳实践

6.1 版本控制配置

合理的 .gitignore 文件配置：

code复制# Python
.venv/
__pycache__/
*.py[cod]
*.sqlite3

# Environment
.env

# Static files
staticfiles/

6.2 代码风格统一

使用 black 自动格式化代码：

bash复制black .

我建议在提交代码前总是运行 black，这能保持团队代码风格一致。

6.3 持续集成建议

基本的 CI 流程应该包括：

运行测试套件
检查代码风格
安全扫描

示例 GitHub Actions 配置 (.github/workflows/test.yml):

yaml复制name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
    - name: Run tests
      run: |
        python manage.py test
    - name: Check code style
      run: |
        pip install black
        black --check .

7. 常见问题排查

7.1 数据库连接问题

错误：django.db.utils.OperationalError: could not connect to server

解决方案：

检查 PostgreSQL 服务是否运行：sudo systemctl status postgresql
验证连接信息是否正确
检查 pg_hba.conf 文件配置

7.2 静态文件404错误

错误：静态文件在生产环境无法加载

解决方案：

确保执行了 collectstatic 命令
检查 WhiteNoise 中间件配置顺序
验证 STATIC_ROOT 和 STATIC_URL 设置

7.3 跨站请求伪造(CSRF)错误

错误：Forbidden (403) CSRF verification failed

解决方案：

确保 CSRF_TRUSTED_ORIGINS 包含你的域名
检查模板中是否包含 {% csrf_token %}
验证 Cookie 设置是否正确

7.4 迁移冲突

错误：django.db.migrations.exceptions.InconsistentMigrationHistory

解决方案：

备份数据库
删除迁移文件（除了 init.py）
重新创建迁移：makemigrations
伪造初始迁移：migrate --fake-initial

8. 性能优化技巧

8.1 数据库优化

使用 select_related 和 prefetch_related 减少查询次数
添加适当的数据库索引
考虑使用 django-debug-toolbar 分析查询

8.2 缓存策略

配置 Django 缓存后端：

python复制CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
    }
}

使用缓存模板片段：

html复制{% load cache %}
{% cache 500 sidebar %}
    <!-- 缓存内容 -->
{% endcache %}

8.3 静态文件优化

启用 WhiteNoise 压缩和缓存：

python复制STORAGES = {
    "staticfiles": {
        "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage",
    },
}

考虑使用 CDN 分发静态文件

9. 安全最佳实践

9.1 敏感信息保护

永远不要将 SECRET_KEY 硬编码在代码中
使用环境变量管理敏感配置
定期轮换密钥和密码

9.2 安全头部配置

在 settings.py 中添加安全头部：

python复制SECURE_BROWSER_XSS_FILTER = True
SECURE_CONTENT_TYPE_NOSNIFF = True
X_FRAME_OPTIONS = "DENY"
SECURE_REFERRER_POLICY = "same-origin"

对于 HTTPS 站点：

python复制SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

9.3 定期更新依赖

使用 pip list --outdated 检查过期的包
定期更新 requirements.txt
关注 Django 安全公告

10. 项目结构建议

一个组织良好的 Django 项目结构示例：

code复制learn_django/
├── .env
├── .gitignore
├── manage.py
├── requirements.txt
├── static/
├── templates/
├── learn_django/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
└── posts/
    ├── migrations/
    ├── __init__.py
    ├── admin.py
    ├── apps.py
    ├── models.py
    ├── tests.py
    ├── urls.py
    └── views.py

我个人在实践中发现这种结构具有以下优势：

清晰的关注点分离
易于扩展新功能
便于团队协作
简化部署流程

对于更复杂的项目，可以考虑将设置文件拆分为多个环境特定的文件（base.py, development.py, production.py），并使用 django-environ 管理配置。

Django开发环境配置与项目初始化指南

1. Django 开发环境配置与项目初始化

1.1 Python 环境搭建

1.2 项目虚拟环境创建

1.3 依赖管理实践

2. Django 项目创建与基础配置

2.1 项目初始化

2.2 数据库配置

2.3 环境变量管理

3. Django 应用开发全流程

3.1 创建应用

3.2 模型设计

3.3 视图与URL配置

3.4 模板系统

4. Django 后台管理与测试

4.1 后台管理配置

4.2 测试实践

5. 生产环境部署

5.1 部署架构选择

5.2 使用 Gunicorn 运行

5.3 PostgreSQL 数据库配置

6. 开发工作流与最佳实践

6.1 版本控制配置

6.2 代码风格统一

6.3 持续集成建议

7. 常见问题排查

7.1 数据库连接问题

7.2 静态文件404错误

7.3 跨站请求伪造(CSRF)错误

7.4 迁移冲突

8. 性能优化技巧

8.1 数据库优化

8.2 缓存策略

8.3 静态文件优化

9. 安全最佳实践

9.1 敏感信息保护

9.2 安全头部配置

9.3 定期更新依赖

10. 项目结构建议

内容推荐