# thinkDj

**Repository Path**: damingstore/thinkDj

## Basic Information

- **Project Name**: thinkDj
- **Description**: thinkDj是使用python编写的后端服务架构，主要使用django框架进行封装，采用分层的思想进行封装，层次分明，架构清晰。 主要使用到以下技术: django(框架) pyjwt(token)python-dotenv(env配置)django-ipware(客户端IP)django-redis(nosql)...
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-09-10
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# thinkDj 后端服务封装架构

## 简介

thinkDj 是一个基于 Django 的 Python 后端服务封装项目，目标是把常用后端能力进行统一封装，让业务开发保持清晰的分层结构。

项目采用 Controller、Validate、DAO、Service、Exception 等分层思想，适合作为前后端分离 API 项目的基础骨架，也适合继续扩展成多应用、多模块的大型后端服务。

## 技术栈

```text
Django 3.2.3                 Web 框架
PyJWT                        Token 生成与解析
python-dotenv                .env 环境变量配置
django-redis                 Redis 缓存
PyMySQL                      MySQL 数据库连接
Pillow                       图片处理
qrcode                       二维码生成
requests                     外部 HTTP 请求
```

## 项目能力

- env 环境配置加载
- Controller 控制器层
- Validate 参数校验层
- DAO 数据访问层
- Model 模型层
- 统一响应结构
- 统一异常处理
- JWT token 服务
- 文件上传服务
- 验证码服务
- 二维码服务
- 外部 HTTP 请求服务
- 日志记录
- 测试调试模块隔离

## 项目启动

### 1. 克隆项目

```bash
git clone https://gitee.com/damingstore/thinkDj.git
cd thinkDj
```

### 2. 创建并启用虚拟环境

Windows 示例：

```bash
python -m venv venv
venv\Scripts\activate
```

如果已经有虚拟环境，可以直接使用对应解释器。本项目当前开发环境示例：

```bash
C:\Software\pythonenv\dj32\Scripts\python.exe
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置环境变量

复制 `.env.example` 为 `.env`，并按本地环境修改数据库、JWT、验证码等配置。

```bash
copy .env.example .env
```

关键配置示例：

```env
DEBUG=True
ENABLE_TEST_ROUTES=False
SECRET_KEY=your-secret-key

DATABASE_ENGINE=django.db.backends.mysql
DATABASE_HOST=127.0.0.1
DATABASE_NAME=your_database
DATABASE_PORT=3306
DATABASE_USER=root
DATABASE_PASSWORD=root

JWT_SECRET=secret
JWT_ALG=HS256
JWT_ISS=thinkDj
JWT_AUD=thinkDj
JWT_EXP=60000
```

### 5. 检查项目

```bash
python manage.py check
```

### 6. 启动服务

```bash
python manage.py runserver 127.0.0.1:8000
```

访问：

```text
http://127.0.0.1:8000/
```

## 目录结构

```text
thinkDj/
├── app/                         应用目录，可创建多个业务应用
│   ├── system/                  system 正式业务应用
│   │   ├── controller/          控制器层
│   │   ├── dao/                 数据访问层
│   │   ├── validate/            参数校验层
│   │   ├── migrations/          数据库迁移
│   │   ├── apps.py
│   │   ├── models.py
│   │   └── urls.py
│   └── test/                    测试调试应用，仅开发或显式开启时挂载
│       ├── controller/          调试控制器
│       ├── dao/                 调试 DAO
│       ├── validate/            调试参数校验
│       ├── migrations/
│       ├── apps.py
│       └── urls.py
├── config/                      配置扩展目录
├── core/                        Django 核心配置
│   ├── settings.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
├── lib/                         第三方或本地库封装
├── public/                      静态资源、上传资源
├── runtime/                     运行日志目录
├── utils/                       公共能力封装
│   ├── basics/                  基础类
│   ├── decorators/              装饰器
│   ├── exceptions/              异常处理
│   ├── middlewares/             中间件
│   └── services/                通用服务
├── requirements.txt
└── manage.py
```

## 测试调试模块

调试、演示接口统一放在 `app/test`，不再放入 `app/system`。这样可以避免测试接口和正式业务接口混在一起。

当前测试路由统一挂载在：

```text
/test/
```

示例：

```text
/test/test1/
/test/upload/
/test/captcha/
/test/qrcode/
/test/req/
```

挂载规则：

- `DEBUG=True` 时自动挂载，方便本地开发。
- `DEBUG=False` 时默认不挂载。
- 如果生产或预发环境确实需要临时调试，可以显式配置 `ENABLE_TEST_ROUTES=True`，用完后应立即关闭。

正式业务接口仍放在 `app/system` 或其他业务 app 中，例如：

```text
/system/
```

## 分层约定

### Controller

负责接收请求、调用参数校验、调用业务服务，并返回统一响应。不建议在 Controller 中堆复杂业务逻辑。

### Validate

负责参数校验。当前基于 Django Forms 封装，支持前后端分离常见输入来源：

- GET query
- POST form
- JSON body
- PUT/PATCH/DELETE urlencoded body
- path params
- files

推荐写法：

```python
params = TestValidate.validateRequest(request)
```

带路径参数：

```python
params = TestValidate.validateRequest(request, pathParams={'id': id})
```

如果只需要判断是否通过：

```python
TestValidate.fromRequest(request).validate()
```

### DAO

负责数据库访问，建议只处理数据读写，不承载复杂业务规则。

### Service

负责公共能力或业务能力封装，例如 JWT、上传、请求转发、二维码等。大型项目中建议继续补充业务 Service 层。

## 统一响应

使用 `ResponseService` 返回统一结构：

```python
return ResponseService.sucess().data({'id': 1})
```

返回格式：

```json
{
  "code": 0,
  "msg": "请求成功",
  "data": {
    "id": 1
  }
}
```

## 统一异常

业务异常统一抛出自定义异常：

```python
raise CustomParamsException('参数错误')
```

`CustomExceptionHandle` 会在 `DEBUG=False` 时统一接管异常：

- 自定义业务异常：返回对应业务错误码和消息
- 数据库异常：记录日志，返回数据库错误
- 普通系统异常：记录日志，返回系统内部错误

`DEBUG=True` 时保留 Django 原生错误页，方便开发调试。

## 文件上传服务

`UploadService` 已增加基础安全策略：

- 文件名清洗
- 后缀白名单
- 脚本和可执行文件黑名单
- 双后缀检测
- MIME 类型校验
- 文件头魔数校验
- 脚本内容特征扫描
- 文件大小限制
- 路径穿越防护
- 递归创建目录

示例：

```python
file = request.FILES.get('file')
ret = UploadService().store(file, 'uploads/avatar')
return ResponseService.sucess().data(ret)
```

可通过 Django settings 覆盖默认策略：

```python
UPLOAD_MAX_SIZE = 10 * 1024 * 1024
UPLOAD_ALLOWED_EXTENSIONS = {'jpg', 'jpeg', 'png', 'pdf'}
UPLOAD_BLOCKED_EXTENSIONS = {'php', 'jsp', 'asp', 'exe', 'sh'}
UPLOAD_SCAN_SCRIPT_CONTENT = True
```

## 外部请求服务

`RequestService` 已封装 timeout、重试、异常捕获、日志记录和统一返回结构。

GET 示例：

```python
ret = RequestService().request(
    'https://example.com/api',
    method='get',
    params={'page': 1},
    toJson=True
)
```

POST JSON 示例：

```python
ret = RequestService().request(
    'https://example.com/api',
    method='post',
    jsonData={'name': 'thinkDj'},
    toJson=True
)
```

返回结构：

```json
{
  "success": true,
  "status_code": 200,
  "data": {},
  "headers": {},
  "url": "https://example.com/api",
  "elapsed": 0.123,
  "error": null
}
```

## 常用开发命令

```bash
# 项目检查
python manage.py check

# 启动开发服务
python manage.py runserver 127.0.0.1:8000

# 生成迁移文件
python manage.py makemigrations

# 执行迁移
python manage.py migrate
```

## 大型应用扩展建议

如果基于 thinkDj 做大型应用，建议逐步补齐：

- 多环境 settings 拆分：`base/dev/test/prod`
- 业务 Service 层
- RBAC 权限体系
- API 版本管理，例如 `/api/v1`
- OpenAPI/Swagger 文档
- 单元测试和接口测试
- Celery 异步任务
- 统一缓存策略
- request_id 链路追踪
- 错误告警和监控
- Docker 和 CI/CD

## 开发进度

```text
env 环境配置文件加载        - ok
自定义异常接管             - ok
控制器层                   - ok
参数验证层                 - ok
DAO 层                     - ok
Model 层                   - ok
日志服务                   - ok
JWT 服务                   - ok
文件上传服务               - ok
外部请求服务               - ok
测试调试模块隔离           - ok
```