Django Starter 基础框架 v2

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

项目背景

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

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

features

业务代码生成器（新）
admin后台安全限制中间件（需手动启用）
非debug模式下管理员可以查看报错信息（需手动启用）
自定义访问前缀
支持Docker部署（使用docker-compose方式）
支持uWsgi部署，支持uWsgi自动重启
默认启用CORS_ALLOW实现接口跨域
基于SimpleUI定制的管理后台
管理后台支持登录验证码和登录尝试次数限制
集成RestFramework，默认屏蔽了链接主页，即对外隐藏API
对默认的settings进行拆分
默认使用Redis缓存
默认集成Swagger文档，开箱即用，无需额外配置
集成微信SDK，支持(企业)微信登录，详见博客
接口返回值统一包装，详见博客
集成NPM和Gulp管理前端资源，详见博客
封装了常用的三种分页功能，详见博客
重写admin主页，界面更美观，详见博客
封装了简单的本地配置中心

v2版本介绍

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

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

历史版本

文件结构

apps：所有应用
- demo：示例应用，包含示例接口
config：Django项目配置
- caches.py：缓存配置
- django_starter.py：框架配置
- env_init.py：环境初始化
- logging.py：日志配置
- rest_framework.py：DRF配置
- swagger.py：Swagger文档配置
- urls.py：路由配置文件
- urls_root.py：DjangoStarter的顶层路由配置，用于实现地址前缀配置
django_starter：框架代码
- contrib：封装好的组件
- core：核心功能（比如分页）
- db：数据库功能（比如 Model 基类）
- drf：RestFramework功能封装
- http：接口相关（如 API 接口返回值包装）
- middleware：中间件（IP限制、错误处理等功能）
static：静态文件
static_collected：运行collectstatic命令后把所有静态文件都保存到这个文件夹
templates：模板

快速开始

安装依赖

安装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

开始写业务逻辑

根据实际业务在apps包中创建新的应用并使用代码生成器生成CRUD代码（推荐）
~~在默认应用apps/core里写~~（不推荐）

使用django-admin命令创建app：

cd apps
django-admin startapp [your_app_name]

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

models.py
serializers.py
viewsets.py

建议使用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

模型设计的基本要求

每个字段加上友好的 verbose_name ，一般是中文名
定义 __str__ ，便于在管理后台中表示这个模型的对象
定义 Meta 元类，给模型加上一个更友好的名称（一般是中文名）

注册应用

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

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

运行代码自动生成

运行命令：

python manage.py generate_code [app_label] [verbose_name]

参数说明：

app_label: App名称，之前运行 django-admin 命令创建的App名称
verbose_name: 和模型的 verbose_name 类似，App的友好名称，一般是其中文名

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

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

__init__.py
apps.py
serializers.py
urls.py
viewsets.py

添加路由

代码生成器会生成你需要的所有代码，之后在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两种接口文档，并对其进行优化

优化drf_yasg的Swagger分组和文档显示效果（显示分组说明、接口说明等）

支持访问权限配置等

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

http://localhost:8000/api-docs/swagger
http://localhost:8000/api-docs/redoc
~~http://localhost:8000/api-docs/auto~~（仅提供兼容支持）

配置

配置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类可修改以下两个字段进行配置：

allow_networks：配置IP段白名单
allow_addresses：配置IP地址白名单

编辑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

LICENSE

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

Deali-Axy/DjangoStarter

Deali-Axy

Reviews

Repository Details