fly-djangox 0.1.6

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

fly-djangox

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

功能特性

统一响应结构

• 自动包装 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 框架日志和应用日志

安装

pip install fly-djangox

或使用 uv：

uv add fly-djangox

快速开始

1. 配置 Django 项目

# 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. 使用统一响应

from fly_djangox.drf.response import JSONResponse

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

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

3. 使用自定义异常

from fly_djangox.drf.exception import APIException

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

4. 使用软删除模型

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. 继承基础模型

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()

配置项

跨域白名单

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

慢请求阈值

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

慢 SQL 阈值

# 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

开发

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

# 安装依赖
uv sync

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

License

MIT