📚 课程目录第1章企业级Django项目初始化

1. 企业级Django项目初始化

企业级Django项目与教学示例最大的区别，不在于用了多少第三方库，而在于项目从第一天起就具备可复现、可隔离、可配置、可协作的工程基础。一个团队如果在前两周没有把虚拟环境、依赖锁定、目录边界和配置分离这四件事做扎实，后续的联调、部署和排障成本会成倍增加。本章围绕项目初始化阶段最关键的四个动作展开：虚拟环境搭建、依赖管理、项目结构规划与配置分离策略。

虚拟环境：隔离的是解释器与包，不是代码

虚拟环境解决的核心问题是：同一台开发机上，不同项目对同一个包的不同版本需求会互相冲突。例如项目A需要 Django==4.2，项目B需要 Django==5.0，如果都装在全局Python中，必然有一个项目无法正常运行。虚拟环境为每个项目创建独立的 site-packages 目录，使包安装互不影响。

推荐使用Python内置的 venv 模块，无需额外安装工具。在项目根目录执行：

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
# 确认当前解释器路径
python -c "import sys; print(sys.executable)"

激活后，命令行提示符前会出现 (.venv) 标识。此时执行 pip install，包只会安装到该虚拟环境中。企业实践中，虚拟环境目录 .venv 必须加入 .gitignore，绝不提交到版本库，因为不同操作系统和Python版本的二进制包不兼容。

判断虚拟环境是否生效的可靠方法：执行 pip -V，输出路径中应包含 .venv。若路径指向系统Python，说明激活失败。

依赖管理：从 requirements.txt 到可复现锁定

依赖管理要区分两类文件：直接依赖与锁定依赖。直接依赖是开发者主动选择并声明在项目中的包，锁定依赖是包含所有传递依赖及其精确版本的文件。企业项目中，两者应分开维护。

推荐结构如下：

requirements/
├── base.txt        # 所有环境共用的直接依赖
├── dev.txt         # 开发环境额外依赖
└── prod.txt        # 生产环境额外依赖

base.txt 示例：

Django==5.0.6
djangorestframework==3.15.1
psycopg[binary]==3.1.19
python-dotenv==1.0.1

dev.txt 通过 -r base.txt 继承基础依赖，再追加开发工具：

-r base.txt
pytest==8.2.0
pytest-django==4.8.0
django-debug-toolbar==4.4.2
ruff==0.4.4

安装时使用 pip install -r requirements/dev.txt。生产环境则使用 prod.txt，避免把调试工具带入线上。对于需要精确复现的场景，可用 pip freeze > requirements/lock.txt 生成完整锁定文件，但要注意 pip freeze 会包含所有传递依赖，适合部署流水线使用，不适合作为人工维护的直接依赖清单。

项目结构规划：按职责分层，而非按文件类型堆放

Django默认的 startproject 生成的是最小骨架，企业项目需要在此基础上规划清晰的目录边界。推荐采用“配置与业务分离、应用按领域拆分”的结构：

erp_project/
├── config/                 # 项目配置层
│   ├── settings/
│   │   ├── base.py
│   │   ├── dev.py
│   │   └── prod.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
├── apps/                   # 业务应用层
│   ├── accounts/
│   ├── orders/
│   └── inventory/
├── common/                 # 公共工具与基类
├── requirements/
├── tests/
├── manage.py
└── .env.example

关键决策点有三个。第一，把 settings.py 拆成包，而不是单文件，这是配置分离的物理基础。第二，业务应用统一放在 apps/ 下，避免项目根目录被大量应用文件夹淹没。第三，common/ 存放跨应用复用的抽象基类、分页器、权限类等，但不要把它变成什么都往里塞的垃圾桶。

创建应用时指定目录：

python manage.py startapp orders apps/orders

随后在 apps/orders/apps.py 中确认 name = "apps.orders"，并在 INSTALLED_APPS 中使用完整路径注册。

配置分离策略：环境变量驱动，敏感信息不入库

配置分离的目标是：同一套代码，通过不同的环境变量组合，在开发、测试、生产环境中表现出正确的行为差异。核心原则是“代码不变，配置变”。

在 config/settings/base.py 中读取环境变量：

import os
from pathlib import Path
from dotenv import load_dotenv

BASE_DIR = Path(__file__).resolve().parent.parent.parent
load_dotenv(BASE_DIR / ".env")

SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = os.environ.get("DJANGO_DEBUG", "False") == "True"
ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "").split(",")

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ["DB_NAME"],
        "USER": os.environ["DB_USER"],
        "PASSWORD": os.environ["DB_PASSWORD"],
        "HOST": os.environ.get("DB_HOST", "127.0.0.1"),
        "PORT": os.environ.get("DB_PORT", "5432"),
    }
}

dev.py 与 prod.py 分别从 base.py 导入并覆盖差异项：

# config/settings/dev.py
from .base import *
DEBUG = True
ALLOWED_HOSTS = ["*"]
INSTALLED_APPS += ["debug_toolbar"]

# config/settings/prod.py
from .base import *
DEBUG = False
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True

通过 DJANGO_SETTINGS_MODULE 切换配置：开发时设为 config.settings.dev，生产时设为 config.settings.prod。.env 文件必须加入 .gitignore，同时提交一份 .env.example 作为字段说明，供新成员复制填写。

不要把 SECRET_KEY、数据库密码、第三方API密钥写进任何被Git跟踪的文件。一旦提交，即使后续删除，历史记录中仍然可被检索到，必须视为已泄露并立即轮换。

初始化完成后的验证闭环

完成上述四步后，应执行一次完整验证：激活虚拟环境、安装开发依赖、执行 python manage.py check 确认配置无语法与引用错误、执行 python manage.py migrate 确认数据库连接可用、启动开发服务器并访问一个健康检查接口。若 check 报出 ModuleNotFoundError，优先检查 INSTALLED_APPS 中应用路径是否与 apps/ 目录结构一致；若数据库连接失败，检查 .env 是否被正确加载以及 DB_HOST 是否可达。

上图把初始化阶段的四个工程基础按依赖顺序排列：虚拟环境提供隔离边界，依赖管理保证可复现，结构规划确定代码归属，配置分离控制环境差异。四者缺一不可，且顺序不宜颠倒——没有虚拟环境就装依赖，容易污染全局；没有结构规划就写配置，后期拆分成本极高。

可直接使用的初始化检查清单

检查项	通过标准	常见失败原因
虚拟环境激活	`pip -V` 路径含 `.venv`	未执行 activate 或使用了系统 pip
依赖安装	`pip install -r requirements/dev.txt` 无报错	版本冲突或网络源不可达
配置加载	`python manage.py check` 输出 System check identified no issues	`DJANGO_SETTINGS_MODULE` 未设置或 .env 缺失
数据库连通	`python manage.py migrate` 成功执行	DB_HOST/DB_PORT 错误或数据库未启动
敏感信息隔离	`git status` 中不出现 `.env`	.gitignore 未配置或 .env 已被跟踪

完成以上检查后，项目即具备进入下一阶段开发的基础条件。后续所有应用开发、接口编写和部署配置，都应在这个初始化框架内进行，而不是回头修改目录结构或重新组织依赖文件。