2024金秋版：Django5开发与部署保姆级零基础教程

先睹为快

先看下目录了解本教程都有哪些内容。

章节目录

css 复制代码

1 搭建Python环境
• 1.1 Windows安装Python
• 1.2 Windows切换系统全局Python版本
• 1.3 macOS安装Python
• 1.4 macOS使用pyenv切换系统默认Python版本
• 1.5 为什么要构建Python虚拟环境
• 1.6 使用Python自带工具构建Python虚拟环境
• 1.7 退出虚拟环境
2 初始化Django项目
• 2.1 创建项目虚拟环境
• 2.2 设置VSCode自动激活虚拟环境
• 2.3 修改pip镜像源
• 2.4 创建Django项目代码
• 2.5 初次启动Django项目
• 2.6 导出项目依赖包
• 2.7 路由小试：替换Django默认欢迎页
• 2.8 Debug模式开启与关闭
• 2.9 设置项目时区
• 2.10 设置项目环境变量文件.env
• 2.11 建议的.gitignore文件配置
3 Demo应用教学：基于FBV的API开发
• 3.1 FBV和CBV
• 3.2 创建Demo应用
• 3.3 基于FBV开发API：GET请求
• 3.3.1 GET请求：query方式传参
• 3.3.2 使用Django的JsonResponse返回JSON数据
• 3.3.3 GET请求：path方式传参
• 3.4 基于FBV开发API：POST请求
• 3.4.1 POST请求：接收formdata数据
• 3.4.2 关闭跨站请求伪造（CSRF）保护
• 3.4.3 POST请求：接收JSON数据
4 Django REST framework（DRF）
• 4.1 什么是Django REST framework
• 4.2 安装Django REST framework
• 4.3 使用api_view装饰器解决跨站请求伪造（CSRF）保护
• 4.4 使用DRF简化FBV的API代码
• 4.5 解决浏览器无法直接访问DRF的GET请求地址的问题
5 使用Swagger自动生成API文档
• 5.1 安装drf-yasg
• 5.2 Swagger UI与ReDoc
• 5.3 继续完善API文档的说明
• 5.4 在Swagger页面中调试API
6 Demo应用教学：基于CBV的API开发
• 6.1 开发需求
• 6.2 创建数据库模型（Model）
• 6.3 使用Django自带的SQLite数据库
• 6.4 使用makemigrations和migrate创建数据库表结构
• 6.5 makemigrations指令和migrate指令的区别
• 6.6 构建数据库模型序列化器（ModelSerializer）
• 6.7 基于APIView类的实现方式
• 6.7.1 实现新增文章API
• 6.7.2 实现查询文章列表API（含搜索）
• 6.7.3 构建公共工具库：分页器
• 6.7.4 构建公共工具库：Swagger分页查询装饰器
• 6.7.5 构建公共工具库：全局异常处理
• 6.7.6 构建公共工具库：序列化器相关处理
• 6.7.7 实现查询指定文章API
• 6.7.8 实现更新指定文章API
• 6.7.9 实现删除指定文章API
• 6.8 基于GenericAPIView类的实现方式
• 6.8.1 实现新增文章和查询文章列表API
• 6.8.2 实现对指定文章的查询、更新、删除API
• 6.9 基于ViewSet类的实现方式
• 6.10 其他更高封装度的混合类（选读）   
7 Django自带的Admin管理后台
• 7.1 创建管理员账号
• 7.2 加入自建应用Article数据表
• 7.3 定制Article数据表的字段显示
8 实战应用教学：开发用户管理系统
• 8.1 项目需求
• 8.2 创建Account应用和用户（User）表
• 8.3 实现用户登录API
• 8.4 构建公共工具库：API登录状态及权限验证
• 8.5 实现用户退出API
• 8.6 在Swagger页面携带所需的请求头数据
• 8.7 构建公共工具：数据合法验证器
• 8.8 实现用户"增删改查查"5个API
9 迁移至MySQL数据库
• 9.1 安装mysqlclient
• 9.2 设置Django数据库驱动配置
• 9.3 导出SQLite中的全部数据
• 9.4 执行迁移MySQ数据库
10 将运行日志写入文件
• 10.1 日志保存的规则、格式和内容
• 10.2 构建公共工具库：日志文件处理
• 10.3 配置Django日志
• 10.4 关于runserver与uvicorn生成日志的区别
11 部署生产环境
• 11.1 安装并运行uvicorn
• 11.2 关于生产环境加载静态资源的问题
• 11.3 使用Docker部署
• 11.3.1 创建项目专用Network
• 11.3.2 编写Django项目的dockerfile
• 11.3.3 编写Nginx配置和dockerfile
• 11.3.4 编写Nginx+Django+MySQL的docker compose文件
• 11.3.5 使用docker compose一键启动整体项目
• 11.3.6 相关的其他docker compose命令
• 11.3.7 Docker学习推荐阅读
• 11.3.8 关于生产环境部署的安全考虑因素
• 11.3.9 检查项目依赖包是否有更新
• 11.4 最终项目目录结构
12 教程Git源码
结束语

由于全文篇幅较长，本教程的上篇包含第1章节至第6.7.6章节的内容。

教程使用的系统环境及软件版本

yaml 复制代码

【操作系统】
Windows 11
macOS Sonoma 14

【Docker软件】
Docker Engine: 27.1.1
Docker Desktop: 4.33.0
Docker Compose: v2.29.1-desktop.1

【Docker镜像】
mysql: 8.4.2
nginx: 1.27.0
python: 3.12.4

【主要Python依赖包】
Django: 5.0.7
django-environ 0.11.2
djangorestframework: 3.15.2
drf-yasg: 1.21.7
mysqlclient: 2.2.4
uvicorn 0.30.3

※注：

教程示例代码区域每行开头的：

"+" 表示新增

"-" 表示删除

"M" 表示修改

看了学习目录，是不是已经开始摩拳擦掌迫不及待想要学起来了呢？放心，本教程把知识点与实战相结合，只要你跟着教程一步步操作下来，一定可以扎实掌握Django全套开发与部署的。

1 搭建Python环境

1.1 Windows安装Python

打开Python官网（www.python.org/），下载Windows对应版本的Python安装程序，本教程下载的是3.12.4版本。

Windows安装Python的时候，注意需要以下几点：

安装pip。pip是Python的包管理工具，用于安装和管理Python包及其依赖。
安装py lancher。py是Python自带的启动器，用于简化在Windows系统上管理和使用多个Python版本的过程，可以方便地运行指定定版本的Python。
勾选将Python添加至环境变量（Add Python to environment variables）。

推荐按以下截图设置安装：

安装完成后，打开cmd，执行以下命令查看版本号：

css 复制代码

python --version

输出如下：

Python 3.12.4

当然，还可以同时安装多个版本的Python安装包，本教程为演示，��安装了Python 3.11.9。

※ 注：在Windows系统中，安装官方Python时，大版本只允许安装一个。例如：不能同时安装3.12.3和3.12.4，只能是从3.12.3安装升级至3.12.4，或者删除3.12.4后重新安装3.12.3。

1.2 Windows切换系统全局Python版本

使用py命令，查看当前系统已安装的Python版本，执行：

bash 复制代码

# 0是数字零
py -0
# 或者执行
py --list

本教程的Windows系统同时安装了Python3.12.4和3.11.9两个版本，输出如下：

arduino 复制代码

-V:3.12 *        Python 3.12 (64-bit)
-V:3.11          Python 3.11 (64-bit)

由于每个大版本只允许安装一个，因此这里显示的Python版本列表就不会出现更详细的第三级小版本号（例如：3.12.4或者3.11.9）。

输出信息中的 * 表示系统当前使用的Python版本。

遗憾的是，使用py命令并不能直接修改系统当前使用的Python版本。

如果要修改系统全局Python版本，需要打开Windows的"环境变量"面板。操作方式为：

Windows系统搜索"编辑系统环境变量"，启动它
在"系统属性"面板的右下角点击"环境变量"
在"环境变量"面板中的"用户变量"里，编辑Path的值，将需要的Python版本顺序放在最上面即可

保存修改后，重启cmd即可生效。

这是Windows修改系统全局Python版本最直接的方式了。

到这里，你可能会觉得这种切换步骤有点不方便。实际上，几乎不会去切换Windows系统全局Python版本。这是因为在实际项目开发中，基本都是通过创建Python虚拟环境来运行项目的，并不会直接用到系统全局Python环境。而py命令是可以直接创建指定Python版本的虚拟环境的。如果你不需要了解macOS搭建Python环境，可以直接跳到第1.5章节"为什么要构建Python虚拟环境"继续阅读。

1.3 macOS安装Python

打开Python官网（www.python.org/），下载macOS对应版本的Python安装程序，本教程下载的是3.12.4版本。

安装完成后，打开终端命令行工具，执行以下命令查看版本号：

css 复制代码

python3 --version

输出：

Python 3.12.4

※ 注：与Windows不一样，macOS的系统环境Python必须使用python3命令，而不是python。

1.4 macOS使用pyenv切换系统默认Python版本

如果要切换系统全局的Python版本环境，推荐使用pyenv。

使用Homebrew安装pyenv，执行：

sql 复制代码

brew update
brew install pyenv

安装后，查看本地安装的Python版本，执行：

pyenv versions

输出：

csharp 复制代码

* system (set by /Users/****/.pyenv/version)

这里的system表示系统安装的Python版本，* 表示系统当前使用的Python版本。

查看pyenv可以安装的Python版本，执行：

css 复制代码

pyenv install --list

这里分别安装Python 3.12.4和3.11.9两个版本，执行：

pyenv install 3.12.4
pyenv install 3.11.9

安装后，再执行：

pyenv versions

可以看到输出信息里多了3.12.4、3.11.9：

csharp 复制代码

* system (set by /Users/****/.pyenv/version)
  3.11.9
  3.12.4

system是通过Python官方安装包安装的Python版本（3.12.4），3.11.9、3.12.4是通过pyenv安装的Python版本。

接下来，最重要的一步，就是将pyenv添加到系统环境变量中。

按照pyenv官方说明，macOS（10.15及以上）需要执行：

bash 复制代码

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

※注：从 macOS Catalina（10.15）开始，Apple将默认的shell从Bash更改为Zsh。因此，macOS上的Terminal默认使用Zsh作为其默认shell。

如果你的macOS系统版本比较旧，可以参阅pyenv官方说明进行对应方式的安装。

Pyenv官方安装说明：

github.com/pyenv/pyenv...

完成以上配置后，测试一下pyenv添加至系统环境变量是否成功。

将系统全局Python版本切换为3.11.9版本，执行：

csharp 复制代码

pyenv global 3.11.9

然后执行以下命令，查看系统当前的Python版本：

sql 复制代码

pyenv exec python3 --version
# 或者
python --version
# 或者（如果以下命令也能输出3.11.9，说明pyenv已成功添加至系统环境变量）
python3 --version

输出如下：

Python 3.11.9

如果执行python3 --version和python --version的输出结果不一致，说明pyenv没有成功设置到系统环境变量中，请再次检查以上操作步骤。

本教程采用Python 3.12.4进行开发，使用pyenv切换版本，执行：

csharp 复制代码

pyenv global 3.12.4

Q：system安装的3.12.4 与pyenv安装的3.12.4有什么不同？

A：没什么不同。但还是推荐使用pyenv安装的Python。因为在system下执行Python命令，必须使用python3，而不能使用python。但是在pyenv环境下，则可以同时兼容python3和python命令，相对来说更方便。

1.5 为什么要构建Python虚拟环境

创建Python虚拟环境的主要目的是为了隔离项目的依赖包，确保项目之间的独立性和兼容性。简单来说，就是为了避免不同项目之间的"依赖包冲突"，并且让项目更容易管理和维护。主要有以下三方面意义：

意义一：依赖隔离

每个项目可能需要不同版本的库或依赖包。例如：

项目A使用的是Django 5.0
项目B使用的是Django 4.0

如果在同一个Python环境中工作，安装了Django 5.0，那么项目B可能无法正常运行，反之亦然。虚拟环境允许为每个项目创建独立的环境，在各自的虚拟环境中安装不同版本的库而不互相干扰。

意义二：简化依赖管理

使用虚拟环境，可以很容易地列出当前项目所需的所有依赖包，

执行以下命令可导出该虚拟环境的所有依赖包，并生成一个requirements.txt文件：

bash 复制代码

pip freeze > requirements.txt

这使得在部署项目或与他人共享项目时，安装所有依赖变得非常简单，只需一行命令就可以安装所需的依赖包：

bash 复制代码

pip install -r requirements.txt

如果你学过前端开发或者NodeJS开发，requirements.txt就类似于package.json文件，用于管理当前项目的依赖包。

意义三：保护全局环境

在没有虚拟环境的情况下，所有依赖包都会安装到系统全局Python环境，这会导致全局环境变得杂乱，难以维护。而虚拟环境保证了全局环境的干净和稳定，不会因为某个项目的依赖问题影响到全局Python的使用。

1.6 使用Python自带工具构建Python虚拟环境

Python自带了创建构建Python虚拟环境的工具，非常方便。

下面来演示创建Python 3.12.4版本的虚拟环境。

请根据你实际使用的系统，按照上述教程内容，将当前系统的全局Python版本切换至3.12.4。

Windows系统可以使��py命令直接创建指定Python版本的虚拟环境，先查看本机已安装的Python版本，执行：

py -0

输出如下：

arduino 复制代码

 -V:3.12 *        Python 3.12 (64-bit)
 -V:3.11          Python 3.11 (64-bit)

找个准备存放虚拟环境目录的地方，执行：

py -3.12 -m venv venv-3.12.4

这里的py -3.12表示调用3.12版本的Python解释器，也就是使用3.12.4的Python环境。

macOS系统需要先使用pyenv切换系统默认Python版本（具体请参阅1.4章节），然后执行：

python -m venv venv-3.12.4

venv-3.12.4 是自定义的虚拟环境名称，你可以改为任何你喜欢的名称。

虚拟环境创建完成后，会生成名为venv-3.12.4的虚拟环境目录。

进入venv-3.12.4目录，执行以下命令，激活虚拟环境：

bash 复制代码

# Windows系统
Scripts\activate

# macOS系统
source bin/activate

这时候命令提示符变成：

bash 复制代码

# Windows系统
(venv-3.12.4) PS 你的路径\venv-3.12.4>

# macOS系统
(venv-3.12.4) 你的路径\venv-3.12.4 %

命令提示符前的 (venv-3.12.4) 表示当前处于的虚拟环境名称。

你可以随意退出或者进入到任意目录中，并不会影响虚拟环境的状态。

这时候，执行：

bash 复制代码

python --version

输出的虚拟环境Python版本信息为：Python 3.12.4。

现在，再演示创建一个Python 3.11.9版本的虚拟环境。

先退出当前虚拟环境，在任何目录下都可以执行：

deactivate

Windows不用修改系统环境变量，使用py命令直接搞定。而macOS需要先使用pyenv切换系统默认Python版本。

再找个准备存放虚拟环境目录的地方，执行创建虚拟环境命令：

bash 复制代码

# Windows系统
py -3.11 -m venv venv-3.11.9
# macOS系统
python -m venv venv-3.11.9

虚拟环境创建完成后，会生成名为venv-3.11.9的虚拟环境目录。

进入venv-3.11.9目录，执行以下命令，激活虚拟环境：

bash 复制代码

# Windows系统
Scripts\activate

# macOS系统
source bin/activate

这时候命令提示符变成：

bash 复制代码

# Windows系统
(venv-3.11.9) PS 你的路径\venv-3.11.9>

# macOS系统
(venv-3.11.9) 你的路径\venv-3.11.9 %

这时候，执行：

bash 复制代码

python --version

输出的虚拟环境Python版本信息为：Python 3.11.9。

到此，你可以在两个虚拟环境中随意切换了。在实际项目中，也是根据项目情况，按照上述方法创建好适合项目的虚拟环境。

小结

强烈建议一个虚拟环境仅供一个项目使用。

无论当前处于任何目录，都可以随时执行退出虚拟环境命令deactivate。

使用python -m venv创建虚拟环境，是根据当前系统的Python版本创建的，因此创建前请先执行python --version确认好当前Python版本。

1.7 退出虚拟环境

在任何目录下都可以执行以下命令退出虚拟环境：

deactivate

2 初始化Django项目

2.1 创建项目虚拟环境

找个你喜欢的地方，创建项目目录，本教程以django5-template-2024autumn为例，作为项目目录名。

进入django5-template-2024autumn项目目录，创建venv目录。

这个目录是用于存放多个虚拟环境目录的，这是因为有的时候，需要测试项目在不同的Python和依赖包版本的兼容性。该项目的各类虚拟环境都创建在venv目录下。

进入venv目录，创建Python3.12.4的虚拟环境：

bash 复制代码

cd venv
# Windows系统（使用py指定Python版本）
py -3.12 -m venv venv-3.12.4
# 或者：Windows系统（使用当前系统全局版本，请确保当前版本为3.12.4）
python -m venv venv-3.12.4
# macOS系统（使用当前系统全局版本，请确保当前版本为3.12.4）
python -m venv venv-3.12.4

如果对以上命令还不清楚，请回看1.6章节内容。

创建后，项目目录结构如下：

bash 复制代码

├─ /django5-template-2024autumn    	<-- 项目目录，名称可以随意更改
|  ├─ /venv			   				<-- Python虚拟环境集合目录
|  |  └─ /venv-3.12.4  				<-- 一个名为venv-3.12.4的Python虚拟环境

退回至项目根目录django5-template-2024autumn，激活指定虚拟环境，执行：

bash 复制代码

# Windows系统
venv\venv-3.12.4\Scripts\activate

# macOS系统
source venv/venv-3.12.4/bin/activate

执行后，请确认命令提示符前是否带有(venv-3.12.4)，表示虚拟环境激活成功。如下图所示：

※ 注：后续操作均在venv-3.12.4虚拟环境中执行，不再特别说明。

2.2 设置VSCode自动激活虚拟环境

虽然在上一章节中通过命令激活了项目的虚拟环境，但是关闭VSCode后，虚拟环境也随之失效了。为了避免每次打开VSCode都要重新激活虚拟环境的麻烦，可以进行如下设置。

lua 复制代码

	├─ /django5-template-2024autumn    	<-- 项目目录，名称可以随意更改
+	|  ├─ /.vscode						<-- VSCode配置目录
+	|  |  └─ settings.json				<-- VSCode配置文件
	|  ├─ /venv			   				<-- Python虚拟环境集合目录
	|  |  └─ /venv-3.12.4  				<-- 一个名为venv-3.12.4的Python虚拟环境

编辑.vscode/settings.json：

Windows如下：

json 复制代码

{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/venv-3.12.4/Scripts/python.exe",
    "python.terminal.activateEnvironment": true
}

macOS如下：

json 复制代码

{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/venv-3.12.4/bin/python",
    "python.terminal.activateEnvironment": true
}

然后在VSCode中：

Windows系统按下 Ctrl+Shift+P ，macOS系统按下Common+Shift+P，打开命令面板。
在弹出的命令面板中输入并选择 Python: Select Interpreter。
从列表中选择 Use Python from 'python.defaultInterpreterPath' setting ，这就是刚刚在.vscode/settings.json中定义的虚拟环境目录。

完成以上设置后，重启VScode，之后每次打开VSCode就会自动激活指定的项目虚拟环境了。请特别注意VSCode的Terminal命令提示符前面是否显示了虚拟环境的名称。

但是！！！在Windows系统中，通过以上.vscode/settings.json的方式虽然激活了项目的虚拟环境，但是Terminal命令提示符前面可能并没有显示虚拟环境名称。

VSCode可能会弹出如下提示：

意思是venv-3.12.4虚拟环境已成功激活，但是可能不会显示在Terminal的命令提示符中。

关于这个原因，微软官方做了回应，是因为技术限制导致的。具体可参阅：

Activate Environments in Terminal Using Environment Variables

github.com/microsoft/v...

如何确认Windows的VSCode激活了指定的虚拟环境呢？

鼠标放在VSCode右下放的pwsh图标上，在弹出的提示框中查看当前激活的Python虚拟环境目录是否正确。

如果改变了.vscode/settings.json文件，例如将python.terminal.activateEnvironment设为false（不自动激活），下次启动VSCode的时候，请注意右下方的pwsh图标会有警告的图标。

点击Relunch terminal后，才会生效新的配置。否则仍按照之前的配置设置虚拟环境。

结论：

macOS VSCode体验完美。

Windows VSCode虽然能自动激活虚拟环境，但是在Terminal无法显示虚拟环境名称。可以在VSCode右下方的pwsh图标的弹出信息中确认。

2.3 修改pip镜像源

※注：从本章节开始，所有命令均在项目的Python虚拟环境中运行，请仔细确认是否已激活虚拟环境。

执行以下命令，将pip的镜像源改为阿里云镜像源：

arduino 复制代码

pip config set global.index-url http://mirrors.aliyun.com/pypi/simple/

还要设置被信任的host，执行：

arduino 复制代码

pip config set install.trusted-host mirrors.aliyun.com

修改后，可执行以下命令确认是否已更改为阿里云镜像源：

arduino 复制代码

pip config list

输出为：

ini 复制代码

global.index-url='http://mirrors.aliyun.com/pypi/simple/'
install.trusted-host='mirrors.aliyun.com'

如果想取消pip的指定镜像源，恢复默认，可以执行以下命令：

php 复制代码

pip config unset global.index-url

在恢复默认后，执行pip config list将不会显示默认镜像源地址。

2.4 创建Django项目代码

安装Django，执行：

bash 复制代码

pip install Django

因为是在虚拟环境中执行的安装命令，所以Django会直接安装到虚拟环境目录venv-3.12.4/Lib/site-packages，这里会新增Django及相关的依赖包。

回到项目根目录django5-template-2024autumn，执行创建Django项目命令：

django-admin startproject mysite ./

mysite 是项目的核心目录，当然你也可以改为你喜欢的名字，但是一旦执行生成后，就不方便修改名称了。所以，一定要确定好了名称再执行。

执行后，项目目录变为如下：

lua 复制代码

├─ /django5-template-2024autumn    	<-- 项目目录，名称可以随意更改
|  ├─ /.vscode						<-- VSCode配置目录
|  ├─ /mysite		   				<-- 项目程序包目录
|  |  ├─ __init__.py  				<-- 一个空文件，这种文件名用于将目录识别为一个Python包
|  |  ├─ asgi.py   	   				<-- 项目运行在ASGI兼容的Web服务器上的入口
|  |  ├─ settings.py   				<-- Django项目配置文件
|  |  ├─ urls.py   	   				<-- Django项目的路由配置文件
|  |  └─ wsgi.py   	   				<-- 项目运行在WSGI兼容的Web服务器上的入口 
|  ├─ /venv			   				<-- Python虚拟环境集合目录
|  └─ manage.py		   				<-- Django命令行管理工具

2.5 初次启动Django项目

在项目根目录执行：

bash 复制代码

python manage.py runserver

可以看到控制台输出如下：

sql 复制代码

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).

You have 18 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.
July 29, 2024 - 16:49:36
Django version 5.0.7, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.

浏览器打开：

bash 复制代码

http://127.0.0.1:8000/

可以看到Django的欢迎页面。

※注：以上方式仅限于作为开发服务器，不要用于正式的生产环境！

如果你的8000端口已被其他程序占用，可以在执行启动命令的时候指定端口号，例如：

bash 复制代码

python manage.py runserver 8080

以上方式仅允许通过127.0.0.1或者localhost访问项目的API。

如果需要让开发服务器可以被本机所有的公开IP访问，可以这样执行启动命令：

bash 复制代码

python manage.py runserver 0.0.0.0:8000

细心的你会发现，运行项目后，项目根目录多出了一个db.sqlite3文件。

lua 复制代码

	├─ /django5-template-2024autumn    	
	|  ├─ /.vscode				<-- VSCode配置目录
	|  ├─ /mysite		   		<-- 项目程序包目录
	|  ├─ /venv			   		<-- Python虚拟环境集合目录
+	|  ├─ db.sqlite3			<-- 临时SQLite数据库文件
	|  └─ manage.py		   		<-- Django命令行管理工具

这个文件是Django自带的SQLite数据库文件，为了在开发过程中省去安装MySQL数据库，而采用的临时替代方案。但是不适合用于生产环境。后续章节会详细介绍数据库开发。

2.6 导出项目依赖包

为项目安装了依赖包，在确认依赖包可用的情况下，记得随时导出项目的依赖包列表文件（requirements.txt）。这个文件记录了项目所需的全部依赖包及版本。对于接触过前端开发或者Nodejs开发的同学，这个requirements.txt就类似于package.json。

在项目根目录执行：

pip freeze > requirements.txt

生成的requirements.txt文件内容如下：

ini 复制代码

asgiref==3.8.1
Django==5.0.7
sqlparse==0.5.1
tzdata==2024.1

目录结构更新如下：

lua 复制代码

	├─ /django5-template-2024autumn    		
	|  ├─ /.vscode				<-- VSCode配置目录
	|  ├─ /mysite		   		<-- 项目程序包目录
	|  ├─ /venv			   		<-- Python虚拟环境集合目录
	|  ├─ db.sqlite3			<-- 临时SQLite数据库文件
	|  ├─ manage.py		   		<-- Django命令行管理工具
+	|  └─ requirements.txt		<-- Django项目依赖包

当别人安装这个项目时，只需在项目根目录执行：

pip install -r requirements.txt

就可以安装全部项目依赖包了。

※ 注：一定记得随时导出项目依赖包，更新requirements.txt。

2.7 路由小试：替换Django默认欢迎页

现在初步尝试下Django的路由，将Django的默认欢迎页替换成自定义的输出。

修改mysite/urls.py：

python 复制代码

	from django.contrib import admin
	from django.urls import path
+	from django.http import HttpResponse

+	# 欢迎信息
+	def welcome(request):
+	    return HttpResponse("Welcome to Django5")

	urlpatterns = [
    	path("admin/", admin.site.urls),
+	    path("", welcome),
	]

如果还没有启动项目，现在需要把项目启动起来。在项目根目录执行：

bash 复制代码

python manage.py runserver

浏览器打开http://127.0.0.1:8000/，可以看到原先的Django欢迎页面不见了，已经变成了如下图：

Django项目在开发环境是热更新的，修改代码无须重启服务即可生效。

urlpatterns里存放的就是项目的全部路由。path的第一个参数是路由地址，第二个参数是对应的视图（view）。

这里添加的path("", welcome)，就是表示路由地址为"项目访问根路径"，对应的视图（view）为welcome方法。

注意path的路由地址不要以"/"开头，否则影响路由的访问。

2.8 Debug模式开启与关闭

Django项目是默认开启Debug模式的，现在如果访问一个不存在的地址，例如：http://127.0.0.1:8000/test

页面会显示详细的报错信息。

如果关闭Debug模式，需要修改mysite/settings.py：

python 复制代码

    ...（略）

    # SECURITY WARNING: don't run with debug turned on in production!
-   DEBUG = True
+   DEBUG = False

-   ALLOWED_HOSTS = []
+   # 允许访问的HOST，*表示所有，也可以设置为127.0.0.1或者localhost来表示仅允许本地HOST访问。 
+   # 更多说明可参阅 https://docs.djangoproject.com/zh-hans/5.0/ref/settings/#allowed-hosts
+   ALLOWED_HOSTS = ["*"]

    ...（略）

ALLOWED_HOSTS是在关闭Debug模式后，运行访问项目的HOST，这里将ALLOWED_HOSTS设置为['*']表示允许任何HOST访问来源。

如果不设置ALLOWED_HOSTS，即ALLOWED_HOSTS为空数组的情况，访问不存在的 http://127.0.0.1:8000/test时，就只显示：

csharp 复制代码

Not Found
The requested resource was not found on this server.

这样就不会显示详细报错信息，保护了项目的代码安全。

按照Django官方说明：ALLOWED_HOSTS列表中的值可以是完全限定的名称（例如 www.example.com），在这种情况下，它们将与请求的 HOST 头完全匹配（不区分大小写，不包括端口）。以英文句号开头的值可以用作子域通配符。.example.com 将匹配 example.com、www.example.com 和 example.com 的任何其他子域。"*" 的值将匹配任何HOST。

ALLOWED_HOSTS 官方详细说明：

docs.djangoproject.com/zh-hans/5.0...

2.9 设置项目时区

Django默认为UTC（00:00时区），这是一个不受任何国家或地区影响的全球时间标准，时间将以UTC存储在数据库中。这是一个很好的实践，因为它消除了时区相关的复杂性。Django会根据UTC处理和显示时间。当从数据库中读取时间数据时，Django会根据系统配置转换成指定时区的时间。

为了便于直观显示中国时间，本教程将时区改为中国的标准时间。

修改mysite/settings.py：

python 复制代码

-	TIME_ZONE = "UTC"
+	TIME_ZONE = "Asia/Shanghai"

需要注意的是，即使设置了TIME_ZONE为Asia/Shanghai，Django写入数据库的时间仍然是UTC时区的时间。

所以，在数据库里查看的时间（UTC），与API接口返回的时间（Asia/Shanghai）显示是不一样的。

如果要求Django以本地时间入库，可以进行如下设置。

修改mysite/settings.py：

ini 复制代码

-	USE_TZ = True
+	USE_TZ = False

为了方便查看，统一数据库与API接口的返回，本教程也将USE_TZ设置为False。

在实际项目中，请根据对时区的实际需求，考虑是否修改TIME_ZONE和USE_TZ 。

2.10 设置项目环境变量文件.env

当项目被多人共同开发时，每个人都需要根据自己的系统环境情况做配置，这样就不适合将这些私有配置（例如DEBUG模式、本地的测试数据库账号密码等）写死在代码中了。可以通过项目根目录的.env文件来设置项目环境变量。当然，这个.env文件是不适合提交git的。

在项目根目录新建.env文件，代码如下：

ini 复制代码

# 是否开启DEBUG模式
DEBUG=True
# 数据库类型(可选值：mysql或sqlite)
DB_TYPE=sqlite
# MYSQL主机地址
DB_MYSQL_HOST=localhost
# MYSQL数据库名称
DB_MYSQL_NAME=my_django
# MYSQL账号
DB_MYSQL_USER=root
# MYSQL密码
DB_MYSQL_PASSWORD=12345678
# MYSQL端口
DB_MYSQL_PORT=3306

项目目录结构变为：

lua 复制代码

	├─ /django5-template-2024autumn    		
	|  ├─ /.vscode				<-- VSCode配置目录
	|  ├─ /mysite		   		<-- 项目程序包目录
	|  ├─ /venv			   	<-- Python虚拟环境集合目录
+	|  ├─ .env			   	<-- 项目环境变量文件
	|  ├─ db.sqlite3			<-- 临时SQLite数据库文件
	|  ├─ manage.py		   		<-- Django命令行管理工具
	|  └─ requirements.txt		        <-- Django项目依赖包

要读取.env文件中的环境变量，需要安装django-environ，执行：

pip install django-environ

修改mysite/settings.py：

ini 复制代码

	...（略）

	from pathlib import Path
+	import environ

+	# 初始化环境变量
+	env = environ.Env(
+		# 设置DEBUG类型转换和默认值
+	 	DEBUG=(bool, False),
+		DB_TYPE = (str, "mysql"),
+		DB_MYSQL_HOST = (str, "localhost"),
+		DB_MYSQL_NAME = (str, ""),
+		DB_MYSQL_USER = (str, "root"),
+		DB_MYSQL_PASSWORD = (str, ""),
+		DB_MYSQL_PORT = (int, 3306),
+	)

	# Build paths inside the project like this: BASE_DIR / 'subdir'.
	BASE_DIR = Path(__file__).resolve().parent.parent

+	# 读取.env文件
+	environ.Env.read_env(Path.joinpath(BASE_DIR, ".env"))

	...（略）

	# SECURITY WARNING: don't run with debug turned on in production!
-	DEBUG = False
+	# 从.env文件中读取DEBUG的值
+	DEBUG = env("DEBUG")

以上就完成了从.env文件中读取DEBUG配置，数据库环境变量的相关代码在后续章节介绍。

※注：使用.env文件必须注意两点

.env中设置变量名及其值，不允许在等号 (=) 前后有空格。否则空格会被视为变量名或值的一部分，可能导致读取错误。

修改.env中的变量值后，必须重启Django服务以及Python虚拟环境才能生效。如果修改了.env文件，在VSCode右下方的控制台会有提示，需要重启控制台。

2.11 建议的.gitignore文件配置

到目前为止，已经提到了很多不适合提交git的目录和文件，建议.gitignore文件可以设置如下。

在项目根目录新建.gitignore文件：

bash 复制代码

# 忽略.vscode目录
.vscode/

# 忽略虚拟环境目录内的文件（readme.md除外）
venv/**
!venv/readme.md

# 忽略env文件
.env

# 忽略db.sqlite3文件
db.sqlite3

# 忽略日志log目录内的文件（readme.md除外）
log/**
!log/readme.md

# 忽略 __pycache__ 目录及相关文件
**/__pycache__/
*.pyc
*.pyo
*.pyd

到这里，Django项目的初始化配置基本完成了，目录结构如下：

lua 复制代码

├─ /django5-template-2024autumn    		
|  ├─ /.vscode                   <-- VSCode配置目录
|  ├─ /mysite                    <-- 项目程序包目录
|  ├─ /venv                      <-- Python虚拟环境集合目录
|  ├─ .env                       <-- 项目环境变量文件
|  ├─ .gitignore                 <-- git忽略配置文件
|  ├─ db.sqlite3                 <-- 临时SQLite数据库文件
|  ├─ manage.py                  <-- Django命令行管理工具
|  └─ requirements.txt           <-- Django项目依赖包

3 Demo应用教学：基于FBV的API开发

3.1 FBV和CBV

在 Django 中，可以使用函数视图（Function-Based Views, FBV）和类视图（Class-Based Views, CBV）来实现 API 请求。两种方式各有其优势和劣势。

FBV（函数视图）

【优点】

简单直观：FBV通常比较直接，特别适用于简单的逻辑。
开发自由度高：在 FBV 中，可以完全定制API的处��流程的每一个细节，开发自由度很高。

【缺点】

代码复用性低：如果多个视图有相似的处理逻辑，FBV 可能会导致重复代码。需要通过额外的函数或装饰器来进行代码复用，可能会使结构复杂化。
扩展性有限：对于复杂和多变的业务逻辑，FBV 可能会导致单个函数过长、过复杂，难以维护和扩展。

CBV（类视图）

【优点】

代码复用性高：CBV 通过继承和混入（mixins）机制，使得代码复用更为方便。常见的行为（如权限检查、数据预处理）可以通过基类和混入类实现，易于管理和复用。
组织性好：CBV 允许通过类的方法组织视图逻辑，每个 HTTP 方法（如 GET、POST）可以用一个单独的方法来处理，使得视图的结构更清晰。
与 Django REST Framework 高度兼容：Django REST Framework（DRF）广泛使用 CBV，提供了大量的基类和混入类，极大地简化了 API 的开发。

【缺点】

学习曲线稍陡：相较于 FBV，CBV 有更多的抽象层次，初学者可能需要时间来理解继承和混入的使用。
开发自由度稍差：虽然 CBV 使代码组织更加结构化，但在某些情况下，它的固定结构可能限制了处理特定逻辑的灵活性。

在实际项目中，会根据不同的场景和需求，混合使用 FBV 和 CBV。大多情况下，CBV的使用率会更高。

❤️❤️❤️------试读结束------❤️❤️❤️

后续精彩章节

css 复制代码

• 3.2 创建Demo应用
• 3.3 基于FBV开发API：GET请求
• 3.3.1 GET请求：query方式传参
• 3.3.2 使用Django的JsonResponse返回JSON数据
• 3.3.3 GET请求：path方式传参
• 3.4 基于FBV开发API：POST请求
• 3.4.1 POST请求：接收formdata数据
• 3.4.2 关闭跨站请求伪造（CSRF）保护
• 3.4.3 POST请求：接收JSON数据
4 Django REST framework（DRF）
• 4.1 什么是Django REST framework
• 4.2 安装Django REST framework
• 4.3 使用api_view装饰器解决跨站请求伪造（CSRF）保护
• 4.4 使用DRF简化FBV的API代码
• 4.5 解决浏览器无法直接访问DRF的GET请求地址的问题
5 使用Swagger自动生成API文档
• 5.1 安装drf-yasg
• 5.2 Swagger UI与ReDoc
• 5.3 继续完善API文档的说明
• 5.4 在Swagger页面中调试API
6 Demo应用教学：基于CBV的API开发
• 6.1 开发需求
• 6.2 创建数据库模型（Model）
• 6.3 使用Django自带的SQLite数据库
• 6.4 使用makemigrations和migrate创建数据库表结构
• 6.5 makemigrations指令和migrate指令的区别
• 6.6 构建数据库模型序列化器（ModelSerializer）
• 6.7 基于APIView类的实现方式
• 6.7.1 实现新增文章API
• 6.7.2 实现查询文章列表API（含搜索）
• 6.7.3 构建公共工具库：分页器
• 6.7.4 构建公共工具库：Swagger分页查询装饰器
• 6.7.5 构建公共工具库：全局异常处理
• 6.7.6 构建公共工具库：序列化器相关处理
• 6.7.7 实现查询指定文章API
• 6.7.8 实现更新指定文章API
• 6.7.9 实现删除指定文章API
• 6.8 基于GenericAPIView类的实现方式
• 6.8.1 实现新增文章和查询文章列表API
• 6.8.2 实现对指定文章的查询、更新、删除API
• 6.9 基于ViewSet类的实现方式
• 6.10 其他更高封装度的混合类（选读）   
7 Django自带的Admin管理后台
• 7.1 创建管理员账号
• 7.2 加入自建应用Article数据表
• 7.3 定制Article数据表的字段显示
8 实战应用教学：开发用户管理系统
• 8.1 项目需求
• 8.2 创建Account应用和用户（User）表
• 8.3 实现用户登录API
• 8.4 构建公共工具库：API登录状态及权限验证
• 8.5 实现用户退出API
• 8.6 在Swagger页面携带所需的请求头数据
• 8.7 构建公共工具：数据合法验证器
• 8.8 实现用户"增删改查查"5个API
9 迁移至MySQL数据库
• 9.1 安装mysqlclient
• 9.2 设置Django数据库驱动配置
• 9.3 导出SQLite中的全部数据
• 9.4 执行迁移MySQ数据库
10 将运行日志写入文件
• 10.1 日志保存的规则、格式和内容
• 10.2 构建公共工具库：日志文件处理
• 10.3 配置Django日志
• 10.4 关于runserver与uvicorn生成日志的区别
11 部署生产环境
• 11.1 安装并运行uvicorn
• 11.2 关于生产环境加载静态资源的问题
• 11.3 使用Docker部署
• 11.3.1 创建项目专用Network
• 11.3.2 编写Django项目的dockerfile
• 11.3.3 编写Nginx配置和dockerfile
• 11.3.4 编写Nginx+Django+MySQL的docker compose文件
• 11.3.5 使用docker compose一键启动整体项目
• 11.3.6 相关的其他docker compose命令
• 11.3.7 Docker学习推荐阅读
• 11.3.8 关于生产环境部署的安全考虑因素
• 11.3.9 检查项目依赖包是否有更新
• 11.4 最终项目目录结构
12 教程Git源码
结束语

阅读完整版

📖 完整教程可订阅我的公众号【卧梅又闻花】

《2024金秋版：Django5开发与部署保姆级零基础教程（上篇）》

《2024金秋版：Django5开发与部署保姆级零基础教程（下篇）》

教程Git源码

本项目已上传至Gitee和GitHub，方便各位下载。

Gitee：

gitee.com/betaq/djang...
Github：

github.com/Yuezi32/dja...