数据库与 ORM

说明

项目使用 Django ORM 作为数据库访问层，数据库连接配置位于 config/env.py 和 application/settings.py。默认使用 MySQL 数据库，通过 django.db.backends.mysql 引擎连接。

数据库配置

环境变量（config/env.py）

# 数据库引擎，默认 MySQL
DATABASE_ENGINE = os.getenv('DATABASE_ENGINE', "django.db.backends.mysql")

# 数据库名称
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.elevue')

# 数据库地址
DATABASE_HOST = os.getenv('DATABASE_HOST', "127.0.0.1")

# 数据库端口
DATABASE_PORT = os.getenv('DATABASE_PORT', 3306)

# 数据库用户名
DATABASE_USER = os.getenv('DATABASE_USER', 'root')

# 数据库密码
DATABASE_PASSWORD = os.getenv('DATABASE_PASSWORD', 'root')

# 数据表前缀
DATABASE_PREFIX = os.getenv('DATABASE_PREFIX', "django_")

Django Settings（application/settings.py）

DATABASES = {
    "default": {
        "ENGINE": env.DATABASE_ENGINE,
        "NAME": env.DATABASE_NAME,
        "USER": env.DATABASE_USER,
        "PASSWORD": env.DATABASE_PASSWORD,
        "HOST": env.DATABASE_HOST,
        "PORT": env.DATABASE_PORT,
    }
}

MySQL 引擎配置

项目默认使用 django.db.backends.mysql 引擎，需要安装 mysqlclient 或 PyMySQL：

# 方式一：mysqlclient（推荐，C 扩展，性能更好）
pip install mysqlclient

# 方式二：PyMySQL（纯 Python，兼容性更好）
pip install PyMySQL

如果使用 PyMySQL，需要在 application/__init__.py 中添加：

import pymysql
pymysql.install_as_MySQLdb()

数据表前缀

所有业务数据表自动添加 DATABASE_PREFIX 前缀（默认 django_），便于多应用共存：

# utils/common.py
def get_table_name(base_name):
    """获取带前缀的表名"""
    prefix = getattr(settings, 'DATABASE_PREFIX', '')
    return f"{prefix}{base_name}"

ORM 查询模式

基础查询

from application.example.models import Example

# 查询未删除的记录（软删除）
queryset = Example.objects.filter(is_delete=False)

# 条件过滤
queryset = queryset.filter(name__contains=name)  # 模糊查询
queryset = queryset.filter(status=status)         # 精确匹配
queryset = queryset.order_by("sort")              # 排序

分页查询

from django.core.paginator import Paginator, PageNotAnInteger, InvalidPage, EmptyPage

paginator = Paginator(queryset, page_size)
try:
    page_list = paginator.page(page_no)
except (PageNotAnInteger, InvalidPage, EmptyPage):
    page_list = paginator.page(1)

# 构建分页数据
page_data = {
    'records': [item for item in page_list],
    'total': paginator.count,
    'size': page_size,
    'current': page_no,
    'pages': paginator.num_pages,
}

创建记录

Example.objects.create(
    name="示例",
    status=1,
    create_user=get_username(request),
    update_user=get_username(request),
)

更新记录

instance = Example.objects.filter(id=instance_id, is_delete=False).first()
if instance:
    instance.name = "新名称"
    instance.update_user = get_username(request)
    instance.save()

批量更新（逻辑删除）

Example.objects.filter(id__in=id_list, is_delete=False).update(is_delete=True)

软删除机制

所有业务模型继承 BaseModel，包含 is_delete 字段。所有查询都过滤 is_delete=False，删除操作为逻辑删除：

# application/models.py
class BaseModel(models.Model):
    id = models.BigAutoField(primary_key=True)
    create_user = models.CharField(max_length=64, default='', null=True, blank=True)
    create_time = models.DateTimeField(auto_now_add=True)
    update_user = models.CharField(max_length=64, default='', null=True, blank=True)
    update_time = models.DateTimeField(auto_now=True)
    is_delete = models.BooleanField(default=False)

    class Meta:
        abstract = True

缓存配置（Redis）

Redis 用于 JWT Token 黑名单和权限缓存：

# application/settings.py
CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": f"redis://{env.REDIS_HOST}:{env.REDIS_PORT}/{env.REDIS_DB}",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "PASSWORD": env.REDIS_PASSWORD if env.REDIS_PASSWORD else None,
            "SOCKET_CONNECT_TIMEOUT": 5,
            "SOCKET_TIMEOUT": 5,
            "CONNECTION_POOL_KWARGS": {"max_connections": 100},
            "IGNORE_EXCEPTIONS": True,
        },
        "KEY_PREFIX": "djangoadmin",
    }
}

Redis 配置（config/env.py）：

REDIS_HOST = os.getenv('REDIS_HOST', '127.0.0.1')
REDIS_PORT = int(os.getenv('REDIS_PORT', 6379))
REDIS_PASSWORD = os.getenv('REDIS_PASSWORD', '123456')
REDIS_DB = int(os.getenv('REDIS_DB', 0))

总结

数据库会话管理由 Django ORM 自动处理，每个请求自动管理数据库连接的生命周期。通过 config/env.py 集中管理数据库和 Redis 连接配置，支持通过环境变量覆盖。软删除机制确保数据安全，所有查询自动过滤已删除记录。