Django Starter 基础框架 v2

基于Django的快速开发模板，增强/添加了安全、缓存、第三方登录、接口文档、部署、代码自动生成等方面的功能。

项目背景

这个项目是我为了满足公司安全部门的要求，定制了一个基于Django的Web框架， 功能包括：给DjangoAdmin加上验证码，并且加入登录次数尝试， 屏蔽了RestFramework默认的API主页，使外部访问无法看到所有接口。

后续我会根据实际工作继续添加一些其他功能以方便团队快速搭建应用~

features

v2版本介绍

在v1版本的基础上，新增 django_starter 包，将大部分封装的功能都集成在这个包下，加入了更多功能、更方便的版本升级、更低的耦合度~

目前版本与 v1 最大的区别是将框架的功能都集成到 django_starter 包中，不会与用户自己的代码产生冲突，后续会根据实际工作持续添加新功能到 django_starter 包内，新版本升级只需要根据升级指引替换 django_starter 目录的内容即可。

历史版本

文件结构

快速开始

安装依赖

安装Python依赖：

pip install -r requirements.txt

安装前端依赖：

yarn install

打包前端资源：

gulp move

如果没有gulp请先安装：npm install --global gulp-cli

前端资源管理参考这篇博客：使用NPM和gulp管理前端静态文件

迁移数据库

python manage.py makemigrations
python manage.py migrate

配置缓存

本项目的限流、安全限制等功能依赖Redis、Memcache等缓存服务，这里以Redis为例。

先在本机安装Redis服务，即可正常使用。

如果要自定义Redis服务器，可以编辑 config/caches.py 文件，修改以下配置。

'LOCATION': [
    'redis://redis:6379/0' if is_docker else 'redis://localhost:6379/0',
]

支持一主多从，默认是单Redis，会自动根据是否docker环境来切换服务器，请根据实际情况自行配置。

更多配置请参考Django文档: https://docs.djangoproject.com/en/4.1/topics/cache/

配置URL前缀

在环境变量中指定URL_PREFIX地址前缀

部署应用需要在docker-compose.yml文件中修改这个环境变量

运行应用后，会自动在所有URL前加上前缀，如管理后台的地址

添加URL前缀之前：

http://127.0.0.1/admin

添加URL前缀（如 test）之后：

http://127.0.0.1/test/admin

开始写业务逻辑

使用django-admin命令创建app：

cd apps
django-admin startapp [your_app_name]

仿照apps/core里的逻辑进行业务开发，每个App需要完成以下代码开发：

建议使用DjangoStarter代码生成器来生成这些重复的业务代码（见下节）

之后在urls.py中注册路由，代码参考apps/core/urls.py。

需要在Django后台进行管理的话，在admin.py中进行注册，参考apps/core/admin.py。

使用代码生成器

DjangoStarter内置业务代码生成器，开发者只需要专注于编写最核心的 models.py 完成模型定义，其他代码自动生成，减少重复劳动，解放生产力。

设计模型

首先完成 models.py 里的模型设计，编写规范可以参照 apps/core/models.py。

下面是一个简单的模型设计例子：

from django.db import models


class Author(models.Model):
    name = models.CharField('作者名称', max_length=20)

    def __str__(self):
        return self.name

    class Meta:
        verbose_name = '作者'
        verbose_name_plural = verbose_name


class Article(models.Model):
    name = models.CharField('文章名称', max_length=20)
    content = models.TextField('文章内容')
    author = models.ForeignKey('Author', verbose_name='文章作者', on_delete=models.CASCADE)

    def __str__(self):
        return self.name

    class Meta:
        verbose_name = '文章'
        verbose_name_plural = verbose_name

模型设计的基本要求

注册应用

设计好了Model，需要把其App添加到INSTALLED_APPS才能被扫描到。

编辑config/settings.py文件，在INSTALLED_APPS节点添加应用，里面有注释，一看就懂。

运行代码自动生成

运行命令：

python manage.py generate_code [app_label] [verbose_name]

参数说明：

注意：运行自动代码生成会覆盖已有的业务代码！

自动代码生成会创建(覆盖)以下文件：

添加路由

代码生成器会生成你需要的所有代码，之后在config/urls.py文件中添加路由：

urlpatterns = [
    path(f'core/', include('apps.core.urls')),
    # 需要根据你的App名称添加这一行路由
    path(app_label/', include('apps.app_label.urls')),
    # ...
]

访问接口文档

本项目默认集成RestFramework自带的AutoScheme和基于drf_yasg的Swagger和ReDoc两种接口文档，并对其进行优化

运行项目之后通过以下地址可以访问接口文档：

配置

配置Django后台网站名称

编辑config/django_starter.py文件，修改这三行代码：

'admin': {
  'site_header': 'DjangoStarter 管理后台',
  'site_title': 'DjangoStarter',
  'index_title': 'DjangoStarter',
  'list_per_page': 20
}

PS: 本项目的后台界面基于SimpleUI，更多Django后台配置方法请参考SimpleUI官方文档。

配置App在后台显示的名称

编辑每个App目录下的apps.py文件，在[AppName]Config类里配置verbose_name，然后在App目录下的__init__.py中，设置default_app_config 即可，具体参照apps/demo的代码。

配置app在swagger中的说明

编辑config/swagger.py文件，在CustomOpenAPISchemaGenerator类的get_schema方法中配置swagger.tags即可。

限流配置

编辑config/rest_framework.py文件 ，参照注释说明修改DEFAULT_THROTTLE_RATES节点即可。

配置启用admin后台安全限制中间件

编辑django_starter/middleware/admin_secure.py文件，在AdminSecureMiddleware类可修改以下两个字段进行配置：

编辑config/settings.py文件，在MIDDLEWARE节点中添加django_starter.middleware.admin_secure.AdminSecureMiddleware即可启用安全限制中间件。

配置启用非debug模式下管理员可以查看报错信息

编辑config/settings.py文件，在MIDDLEWARE节点中添加django_starter.middleware/user_base_exception.UserBasedExceptionMiddleware即可。

uWsgi自动重启

在uwsgi.ini配置文件中，本项目已经配置了监控readme.md文件，文件变化就会自动重启服务器，因此在生产环境中可以通过修改README.md文件实现优雅的uwsgi服务重启。

TODO

相关博文

公众号 公众号

公众号专辑：Django开发精选

知乎专栏：程序设计实验室

Django博客合集：https://www.cnblogs.com/deali/category/1799362.html

LICENSE

Apache License Version 2.0, January 2004
http://www.apache.org/licenses/