# fly_django

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 框架日志和应用日志

## 安装

```bash
pip install -e .
```

## 使用

### 在 Django 项目中引入

```python
# settings.py

# 1. 基础配置
INSTALLED_APPS = [
    ...
    'fly_django',
    'rest_framework',
]

# 2. 引入 DRF 配置（推荐）
from fly_django.settings.drf_setting import *  # 或逐个引入

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

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

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

### 使用统一响应

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

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

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

### 使用自定义异常

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

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

### 使用软删除模型

```python
from fly_django.models.soft_delete import TsSoftDeleteModel

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

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

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

# 永久删除
user.hard_delete()

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

### 继承基础模型

```python
from fly_django.models.soft_delete import BasicModel

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

## 配置项

### 跨域白名单

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

### 慢请求阈值

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

### 慢 SQL 阈值

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

## 依赖

- django >= 4.2
- djangorestframework >= 3.16
- django-cors-headers >= 4.9

## License

MIT
