# django项目初始化优化工具

**Repository Path**: chenwm-star/django-upgrade-init

## Basic Information

- **Project Name**: django项目初始化优化工具
- **Description**: 这是一个专业的Django项目创建工具，采用分层架构设计，快速创建功能完整的Django项目。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-08-04
- **Last Updated**: 2025-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Django, Python, 初始化, init

## README

# Django 项目创建工具

## 简介

这是一个专业的Django项目创建工具，采用分层架构设计，快速创建功能完整的Django项目。

## 工具架构

- **`start.py`** - 交互式启动脚本和流程控制
- **`django-creator.py`** - 基础Django项目创建（项目框架、虚拟环境、依赖安装）
- **`django-helper.py`** - 项目结构优化（apps、models、views、middleware、management等）

## 特性

- **分层创建** - 基础创建 + 结构优化，功能清晰分离
- **清华镜像** - 使用清华大学PyPI镜像，安装速度快
- **完整功能** - 集成JWT认证、API文档、验证码、管理命令等
- **简化配置** - 最小化环境检查，快速上手
- **虚拟环境** - 可选创建独立的Python虚拟环境

## 工作流程

1. **环境检查** - 验证Python版本和项目名称
2. **基础创建** - 使用`django-creator.py`创建Django项目框架
3. **结构优化** - 使用`django-helper.py`添加apps、models、utils等
4. **完成配置** - 自动配置settings、urls、中间件等

## 快速开始

### 方法一：交互式创建（推荐）

```bash
python start.py
```

然后按照提示输入项目信息即可。

### 方法二：命令行创建

```bash
# 基本用法
python django-creator.py myproject

# 指定路径
python django-creator.py myproject --path /path/to/projects

# 不创建虚拟环境
python django-creator.py myproject --no-venv
```

### 方法三：直接运行

```bash
# 直接创建项目
python start.py myproject

# 指定路径直接创建
python start.py myproject /path/to/projects
```

## 项目结构

创建的项目包含以下结构：

```
myproject/
├── venv/                   # 虚拟环境（可选）
├── apps/                   # 应用目录
│   ├── accounts/          # 认证应用
│   │   ├── views.py       # JWT认证视图
│   │   └── urls.py        # 认证路由
│   └── common/            # 公共应用
│       ├── models.py      # 基础模型类
│       ├── views.py       # 通用视图集
│       ├── utils/         # 工具模块
│       │   ├── response.py   # 统一响应格式
│       │   ├── pagination.py # 分页工具
│       │   └── account.py    # 认证工具
│       ├── middleware/    # 中间件
│       │   └── NetworkMiddleware.py # 网络请求中间件
│       └── management/    # 管理命令
│           └── commands/
│               └── server.py # 自定义服务器命令
├── media/                 # 媒体文件
├── static/                # 静态文件
├── templates/             # 模板文件
├── myproject/             # Django配置
├── manage.py
└── requirements.txt       # 依赖列表
```

## 内置功能

### 🔐 认证系统
- JWT Token认证
- 图片验证码
- 用户登录/登出
- Token刷新机制

### 📡 API框架
- Django REST Framework
- 自动API文档（Swagger/ReDoc）
- 统一响应格式
- 分页支持

### 🛠️ 工具类
- 基础模型类（时间戳、软删除、UUID）
- 通用视图集（CRUD操作）
- 自定义分页器
- 统一响应格式
- 网络请求中间件
- 自定义管理命令（使用uvicorn启动服务器）

## API 端点

### 认证相关
- `POST /accounts/token/` - 用户登录
- `POST /accounts/token/refresh/` - 刷新Token  
- `POST /accounts/token/verify/` - 验证Token
- `GET /accounts/captcha/` - 获取验证码

### 系统功能
- `GET /admin/` - 管理后台
- `GET /doc/swagger/` - Swagger API文档
- `GET /doc/redoc/` - ReDoc API文档

## 快速启动

创建项目后，按以下步骤启动：

```bash
# 1. 进入项目目录
cd myproject

# 2. 激活虚拟环境（如果创建了）
source venv/bin/activate    # Linux/Mac
# 或
venv\Scripts\activate       # Windows

# 3. 运行数据库迁移
python manage.py migrate

# 4. 创建超级用户
python manage.py createsuperuser

# 5. 启动开发服务器
python manage.py runserver
```

## 访问地址

- **应用首页**: http://127.0.0.1:8000/
- **管理后台**: http://127.0.0.1:8000/admin/
- **API文档**: http://127.0.0.1:8000/doc/swagger/

## 测试工具

```bash
# 运行测试
python test_tool.py test

# 查看使用说明
python test_tool.py
```

## 技术栈

- **Django 5.2** - Web框架
- **Django REST Framework** - API框架  
- **JWT** - Token认证
- **SimpleUI** - 后台美化
- **django-cors-headers** - 跨域支持
- **drf-spectacular** - API文档
- **django-simple-captcha** - 验证码
- **django-model-utils** - 模型工具

## 项目名称要求

为了避免与Python内置模块冲突，项目名称需要满足以下要求：

- 不能是Python关键字（如：`if`, `for`, `class` 等）
- 不能与Python内置模块同名（如：`abc`, `json`, `math` 等）
- 只能包含字母、数字、下划线和连字符
- 不能以数字开头

**推荐的项目名称格式：**
- `my_project`
- `web_app`
- `blog_site`
- `api_server`

## 注意事项

1. 确保Python版本 >= 3.8
2. 网络连接正常（需要下载依赖包）
3. 使用清华镜像源，国内用户安装速度更快
4. 创建项目后记得先运行数据库迁移
5. 选择合适的项目名称，避免与系统模块冲突

## 故障排除

### 依赖安装失败
如果依赖安装失败，可以手动安装：
```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 虚拟环境问题
如果虚拟环境创建失败，可以使用 `--no-venv` 参数：
```bash
python django-creator.py myproject --no-venv
```

### 权限问题
确保在有写权限的目录下运行工具。