Metadata-Version: 2.4
Name: fly-djangox
Version: 0.1.6
Summary: Django + DRF 通用扩展库，提供统一响应、全局异常处理、分页、软删除模型、中间件等功能
Author-email: fly <fzkf117@163.com>
License: MIT
Project-URL: Homepage, https://github.com/fly/fly-djangox
Project-URL: Repository, https://github.com/fly/fly-djangox
Project-URL: Issues, https://github.com/fly/fly-djangox/issues
Keywords: django,drf,utils,tools,scaffold
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asgiref>=3.11.1
Requires-Dist: django>=4.2.29
Requires-Dist: django-cors-headers>=4.9.0
Requires-Dist: djangorestframework>=3.16.1
Requires-Dist: sqlparse>=0.5.5
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: tzdata>=2025.3
Dynamic: license-file

# fly-djangox

Django + DRF 通用扩展库，提供统一响应、全局异常处理、分页、软删除模型、中间件等功能。

[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![Django](https://img.shields.io/badge/django-4.2+-green.svg)](https://www.djangoproject.com/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## 功能特性

### 统一响应结构
- 自动包装 API 返回数据为 `{code, msg, data, ts}` 格式
- 支持列表自动转为 `{items: []}` 结构

### 全局异常处理
- 统一错误码和错误信息返回
- 支持自定义业务异常 `APIException`
- 自动处理 DRF 内置异常

### 分页组件
- 支持 `page` 和 `page_size` 参数
- 返回结构包含 `total`, `page`, `page_size`, `total_pages`, `items`

### 软删除模型
- `BasicModel`: 基础模型，包含 `create_ts`, `update_ts`
- `TsSoftDeleteModel`: 软删除模型，使用 `delete_ts` 实现逻辑删除

### 中间件
- `RequestTimingMiddleware`: API 耗时统计，记录慢请求
- `SQLTimingMiddleware`: SQL 执行耗时统计，记录慢 SQL

### CORS 配置
- 支持白名单配置
- 精简 Header 和 Methods

### 日志配置
- 分级日志输出
- 分离 Django 框架日志和应用日志

## 安装

```bash
pip install fly-djangox
```

或使用 uv：

```bash
uv add fly-djangox
```

## 快速开始

### 1. 配置 Django 项目

```python
# settings.py

INSTALLED_APPS = [
    ...
    'fly_djangox',
    'rest_framework',
]

# 引入 DRF 配置
from fly_djangox.settings.drf_setting import *

# 引入跨域配置（可选）
from fly_djangox.settings.cross_domain_setting import *

# 引入日志配置（可选）
from fly_djangox.settings.logging_setting import *

# 引入中间件配置（可选）
from fly_djangox.settings.api_time_out_setting import *
```

### 2. 使用统一响应

```python
from fly_djangox.drf.response import JSONResponse

# 返回成功
return JSONResponse(data={"id": 1, "name": "test"})

# 返回错误
return JSONResponse(code=40000, msg="参数错误")
```

### 3. 使用自定义异常

```python
from fly_djangox.drf.exception import APIException

raise APIException(msg="业务错误", code=40001)
```

### 4. 使用软删除模型

```python
from fly_djangox.models.soft_delete import TsSoftDeleteModel
from django.db import models

class User(TsSoftDeleteModel):
    name = models.CharField(max_length=100)

# 查询时自动过滤已删除记录
User.objects.all()  # 只返回未删除的

# 删除操作（软删除）
user.delete()  # 设置 delete_ts

# 永久删除
user.hard_delete()

# 查询包括已删除的
User.all_objects.all()
```

### 5. 继承基础模型

```python
from fly_djangox.models.soft_delete import BasicModel
from django.db import models

class Article(BasicModel):
    title = models.CharField(max_length=200)
    content = models.TextField()
```

## 配置项

### 跨域白名单

```python
# settings.py
CORS_ALLOWED_ORIGINS = [
    "http://localhost:3000",
    "https://your-domain.com",
]
```

### 慢请求阈值

```python
# settings.py
SLOW_THRESHOLD_MS = 1000  # API 耗时超过 1000ms 记录警告日志
```

### 慢 SQL 阈值

```python
# settings.py
SLOW_SQL_THRESHOLD_MS = 500  # SQL 耗时超过 500ms 记录警告日志
```

## 项目结构

```
fly-djangox/
├── src/
│   └── fly_djangox/
│       ├── cache/              # 缓存模块（预留）
│       ├── drf/                # DRF 扩展
│       │   ├── exception.py    # 全局异常处理
│       │   ├── pagination.py   # 分页组件
│       │   ├── renderer.py     # 自定义渲染器
│       │   └── response.py     # 统一响应结构
│       ├── middlewares/        # 中间件
│       │   ├── timing_api_middlewares.py  # API 耗时统计
│       │   └── timing_sql_middlewares.py  # SQL 耗时统计
│       ├── models/             # 模型
│       │   └── soft_delete.py  # 软删除模型
│       ├── settings/           # 配置
│       │   ├── api_time_out_setting.py    # 中间件配置
│       │   ├── cross_domain_setting.py    # 跨域配置
│       │   ├── drf_setting.py             # DRF 配置
│       │   └── logging_setting.py         # 日志配置
│       └── utils/              # 工具模块（预留）
├── pyproject.toml              # 项目配置
├── README.md                   # 项目说明
└── LICENSE                     # MIT 许可证
```

## 依赖

- Python >= 3.9
- Django >= 4.2
- djangorestframework >= 3.16
- django-cors-headers >= 4.9

## 开发

```bash
# 克隆项目
git clone https://github.com/fly/fly-djangox.git
cd fly-djangox

# 安装依赖
uv sync

# 安装开发模式
pip install -e .
```

## License

MIT
