DjangoStarter v3 · AI 原生全栈框架

面向独立开发者与小团队的 AI+全栈脚手架，用最少样板代码快速把想法做成可上线的产品。

基于 Django 5 + Django-Ninja（类型安全 API）+ HTMX/Alpine/Tailwind，内建认证、安全、中间件、代码生成、容器化与观测，把时间全部留给业务。

为 AI 而设计：为 LLM 接入、向量检索/嵌入、函数调用（Tools/Actions）、异步任务与流式响应预留清晰的扩展点与最佳实践路径，轻松把你的应用升级为 AI 驱动。

典型场景：个人/独立产品 MVP、企业内部工具、数据看板、以及各类 AI Agent/助手的后端与管理界面。

在 AI 时代，用 Django 的可靠性 + Ninja 的速度，零阻力从 0 到 1，再从 1 到 100。 更多新版本的细节，可以查看这些博客文章:

• DjangoStarter v3版本开发笔记
• AI 加持下的 DjangoStarter v3.1 版本开发

v4.0 规划（草案）

v4.0 计划将当前的“全栈一体”工程拆分为三段式分发形态，以降低耦合、减少重复实现，并同时满足「只做 API」与「全栈开箱即用」两类用户。

• 核心（Core）：django-starter-core
  • 定位：提供可复用的底座能力（例如模型基类、通用响应封装、认证/安全相关的通用实现与约定等）
• API（API-only）：django-starter-api
  • 定位：仅 API 的项目模板，依赖 Core，不包含前端渲染与静态资源构建链路
• 全栈（Web）：django-starter-web
  • 定位：保留 DjangoStarter 的全栈体验（模板渲染 + HTMX/Alpine/Tailwind/DaisyUI），依赖 Core，并在此基础上集成前端与页面能力

命名说明（避免后续“改来改去”造成混乱）：

• 上述名称用于对外分发与文档表达（发行包名/项目名）
• Python import 命名空间与 Django app label 将作为公共 API 的一部分，尽量少改动、按大版本迁移策略演进

截图预览

主页

<table style="width: 100%; table-layout: fixed;"> <thead> <tr> <th style="width: 50%;">主页</th> <th style="width: 50%;">后台主页</th> </tr> </thead> <tbody> <tr> <td><img src="docs/images/home.png" alt="主页" style="width: 100%;"/></td> <td><img src="docs/images/admin_home.png" alt="后台主页" style="width: 100%;"/></td> </tr> </tbody> </table>

其他页面

| 登录页面 | 联系我们 | | ---------------------------- | ---------------------------- | | | | | 个人页面 | Demo页面 | | | |

历史版本

• v1
• v2

核心特性

• Django Ninja 集成：采用 Django Ninja 替代传统的 Django Rest Framework，为 API 开发带来了性能优化和更简洁的编码体验。利用 Python 类型提示，自动生成交互式 API 文档，不再需要 drf-yasg 那一堆繁琐的手动配置文档，同时提升了代码的可读性和维护性。
• 增强的安全性：内置了多项安全功能，包括但不限于 Admin 登录验证码、IP 限制等，确保应用的安全性。
• 代码自动生成：v3 版本进一步优化了代码生成器，丢掉了 DRF 这个包袱，只需要定义模型，就可以生成 schema 以及 RESTFul API，还能根据定义自动创建测试用例，大大提高开发效率。
• 随机种子数据生成：v3 版本内置 seed 模块，支持为已有模型自动填充假数据，方便开发测试。
• 模块化项目结构：推出了更加模块化的项目结构设计，方便开发者根据需要添加或移除功能模块，使项目维护更为简单。
• 现代化前端集成：采用 TailwindCSS v4 + DaisyUI v5 构建 UI，移除 Flowbite，支持 Light/Dark 多主题切换。使用 Alpine.js 处理前端交互，结合 HTMX 实现 SPA 级体验。以及利用 NPM 和 gulp 管理前端资源，帮助开发者打造富交互式的用户界面。
• 容器化支持：内置 Dockerfile 和 docker-compose.yml 配置，简化了容器化部署的过程，支持一键部署到任何支持 Docker 的环境。
• 详尽的文档与社区支持：提供全面的文档和指南，覆盖从项目启动到部署的每一个步骤。同时，基于活跃的 Django 开源社区，开发者可以轻松获取支持和反馈。

适用场景

DjangoStarter v3 是为那些追求高效开发流程、重视应用性能与安全性的 Django 开发者设计的。无论是构建复杂的企业级应用、快速开发 MVP 还是学习最佳实践，DjangoStarter v3 都是一个优秀的选择。

features

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

v3版本介绍

v2版本已经定下了大体的框架，v3的主要改动是将 RestFramework 换成了 django-ninja ，在 Django 里实现了 FastApi 风格的接口。

其他的功能目前大概是这些：

• 新的自动代码生成功能
• 完善了单元测试和集成测试，搭配代码生成，可以为每个应用自动生成 crud 的测试用例
• 随机种子数据，目前使用 faker 实现假数据，打算进一步实现类似 EFCore 的种子数据机制，使假数据更自然
• 新的登录接口
• 多种第三方登录接入（目前接了微信、小程序、企微）
• 使用 TailwindCSS v4 + DaisyUI 重构前端，提供精美的现代化 UI 组件与布局，支持多主题切换
• 拆分 settings 配置，像 AspNetCore 那样支持多个环境配置
• 更换了包管理器为 uv

功能持续更新中，我会同步发在博客，欢迎关注。

文件结构

 DjangoStarter
 ├─ media # 用户上传的文件
 ├─ src # 主要源码
 │  ├─ apps # 所有应用
 │  │  ├─ account # 用户相关的代码，包括登录接口
 │  │  ├─ demo # 示例应用
 │  │  └─ __init__.py
 │  ├─ config # Django项目配置
 │  │  ├─ settings # 拆分的settings模块
 │  │  ├─ __init__.py
 │  │  ├─ apis.py # ninja API 配置
 │  │  ├─ asgi.py
 │  │  ├─ env_init.py # 环境初始化
 │  │  ├─ urls.py # 路由配置文件
 │  │  ├─ urls_root.py # DjangoStarter的顶层路由配置，用于实现地址前缀配置
 │  │  └─ wsgi.py
 │  ├─ django_starter # 框架代码
 │  │  ├─ contrib # 封装好的组件
 │  │  ├─ db # 数据库功能（比如 Model 基类）
 │  │  ├─ http # 接口相关（如 API 接口返回值包装）
 │  │  ├─ middleware # 中间件（IP限制、错误处理等功能）
 │  │  ├─ __init__.py
 │  │  ├─ apis.py
 │  │  ├─ constants.py
 │  │  ├─ urls.py
 │  │  └─ utilities.py
 │  ├─ static # 静态文件
 │  │  ├─ admin
 │  │  └─ css
 │  ├─ templates # Django模板
 │  │  ├─ demo
 │  │  └─ _base.html
 │  ├─ Dockerfile
 │  ├─ docker-compose.yml
 │  ├─ manage.py
 │  ├─ test.py
 │  └─ uwsgi.ini
 ├─ static-dist # 运行collectstatic命令后把所有静态文件都保存到这个文件夹
 ├─ .gitignore
 ├─ LICENSE
 ├─ README.md
 ├─ clean_pycache.py # 运行后可以清理 __pycache__ 文件
 ├─ gulpfile.js
 ├─ package.json
 ├─ uv.lock
 ├─ pnpm-lock.yaml
 ├─ pyproject.toml
 └─ tailwind.config.js

快速开始

入门文档

如果你此前从未接触过 Django ，建议先阅读 Django 官方文档 ，了解 Django 的基本概念和用法。

以下是 DjangoStarter v3 的快速入门文档：

• 零基础快速入门
• 前端零基础友好入门指南

clone代码

master分支是最新的代码，正处在活跃开发中，不保证生产稳定性，欢迎大家提issue。

当前最新生产版本是 v3.3.0，使用以下命令克隆代码：

git clone --branch v3.3.0 --depth 1 https://github.com/Deali-Axy/DjangoStarter.git

包管理器

从 v3.4 版本开始，全面切换为使用 uv 管理 Python 环境和依赖。uv 是一个极速的 Python 包安装器和解析器，使用 Rust 编写，旨在替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等工具。

首先需要安装 uv：

# MacOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

更多安装方式请参考 uv 官方文档。

Just 命令运行器

本项目使用 just 作为命令运行器，方便执行常用的开发命令。

安装 just：

# Windows (使用 winget)
winget install -e --id Casey.Just

# Windows (使用 scoop)
scoop install just

# MacOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin

常用命令：

• just 或 just --list: 列出所有可用命令
• just mm: 生成数据库迁移文件 (makemigrations)
• just migrate: 执行数据库迁移 (migrate)
• just db-sync: 生成并执行迁移
• just serve: 使用 Granian 启动 ASGI 服务 (开发模式)
• just dev: 启动传统的 Django 开发服务器
• just shell: 进入 Django Shell
• just clean: 清理 Python 缓存文件 (__pycache__ 和 .pyc)

更多命令请查看项目根目录下的 justfile 文件。

虚拟环境

推荐使用 uv 来管理 python 环境。

首先创建一个虚拟环境（指定 Python 3.14）：

uv venv --python 3.14

启用虚拟环境：

• Windows: .venv\Scripts\activate
• Linux/macOS: source .venv/bin/activate

安装依赖

Python 依赖

安装Python依赖：

uv sync

前端资源

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

需要先安装 nodejs 环境，推荐使用 nvm 来管理 node 环境。

安装前端依赖：

pnpm i

打包前端资源：

gulp move

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

如果想使用 tailwindcss ，可以运行。

pnpm run tw:watch

关于tailwindcss，详见这篇文章: 在 DjangoStarter 中集成 TailwindCSS

数据库迁移

这个操作会生成一个 db.sqlite3 文件，本地测试推荐使用 SQLite 数据库。

uv run ./src/manage.py migrate

配置缓存（可选）

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

先在本机安装 Redis 服务并启动。

如果要自定义 Redis 服务器，可以编辑 src/config/settings/components/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代码（推荐）
• ~~在例子应用src/apps/demo里写~~（不推荐）

使用django-admin命令创建app：

cd apps
django-admin startapp [your_app_name]

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

• models.py

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

之后在src/config/apis.py中注册 Ninja 路由。

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

随机种子数据生成（可选）

DjangoStarter 内置种子数据生成功能（基于faker库），可以在开发环境下快速在数据库中填充随机假数据，方便测试。

使用以下命令即可自动生成

uv run ./src/manage.py seed app_label 10

其中 app_label 是开发者自行创建的 App 名称，比如 DjangoStarter 中的示例应用 demo

使用代码生成器（可选）

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

设计模型

首先完成 models.py 里的模型设计，编写规范可以参照 src/apps/demo/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节点添加应用，里面有注释，一看就懂。

运行代码自动生成

运行命令：

uv run ./src/manage.py autocode [app_label] [verbose_name]

参数说明：

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

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

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

• apis 目录下，按照每个 model 一个 python package 自动生成 ninja 的 crud 代码
• __init__.py
• admin.py
• apps.py
• tests 目录下，每个 model 会生成一个测试用例脚本

添加路