Optimize core、middleware、database、utils...

Author: wu-clan

.gitignore

@@ -1,5 +1,6 @@
 .idea/
 .vscode/
+.cursor/
 .DS_Store
 venv/
 .venv/

backend/app/admin/conf.py

@@ -4,13 +4,13 @@
 
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from backend.core.path_conf import BasePath
+from backend.core.path_conf import BASE_PATH
 
 
 class AdminSettings(BaseSettings):
     """Admin Settings"""
 
-    model_config = SettingsConfigDict(env_file=f'{BasePath}/.env', env_file_encoding='utf-8', extra='ignore')
+    model_config = SettingsConfigDict(env_file=f'{BASE_PATH}/.env', env_file_encoding='utf-8', extra='ignore')
 
     # OAuth2：https://github.com/fastapi-practices/fastapi_oauth20
     # GitHub

backend/app/admin/crud/crud_user.py

@@ -191,7 +191,7 @@ async def get_list(self, dept: int = None, username: str = None, phone: str = No
             )
             .order_by(desc(self.model.join_time))
         )
-        
+
         # 构建过滤条件
         filters = []
         if dept:
@@ -202,11 +202,11 @@ async def get_list(self, dept: int = None, username: str = None, phone: str = No
             filters.append(self.model.phone.like(f'%{phone}%'))
         if status is not None:
             filters.append(self.model.status == status)
-        
+
         # 应用过滤条件
         if filters:
             stmt = stmt.where(and_(*filters))
-        
+
         return stmt
 
     async def get_super(self, db: AsyncSession, user_id: int) -> bool:

backend/app/generator/service/gen_service.py

@@ -20,7 +20,7 @@
 from backend.app.generator.schema.gen_model import CreateGenModelParam
 from backend.app.generator.service.gen_model_service import gen_model_service
 from backend.common.exception import errors
-from backend.core.path_conf import BasePath
+from backend.core.path_conf import BASE_PATH
 from backend.database.db import async_db_session
 from backend.utils.gen_template import gen_template
 from backend.utils.type_conversion import sql_type_to_pydantic
@@ -114,7 +114,7 @@ async def generate(self, *, pk: int) -> None:
             tpl_code_map = await self.render_tpl_code(business=business)
             gen_path = business.gen_path
             if not gen_path:
-                gen_path = os.path.join(BasePath, 'app')
+                gen_path = os.path.join(BASE_PATH, 'app')
             for tpl_path, code in tpl_code_map.items():
                 code_filepath = os.path.join(
                     gen_path,

backend/app/task/conf.py

@@ -7,13 +7,13 @@
 from pydantic import model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from backend.core.path_conf import BasePath
+from backend.core.path_conf import BASE_PATH
 
 
 class TaskSettings(BaseSettings):
     """Task Settings"""
 
-    model_config = SettingsConfigDict(env_file=f'{BasePath}/.env', env_file_encoding='utf-8', extra='ignore')
+    model_config = SettingsConfigDict(env_file=f'{BASE_PATH}/.env', env_file_encoding='utf-8', extra='ignore')
 
     # Env Config
     ENVIRONMENT: Literal['dev', 'pro']

backend/core/conf.py

@@ -6,97 +6,97 @@
 from pydantic import model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from backend.core.path_conf import BasePath
+from backend.core.path_conf import BASE_PATH
 
 
 class Settings(BaseSettings):
-    """Global Settings"""
+    """全局配置"""
 
-    model_config = SettingsConfigDict(env_file=f'{BasePath}/.env', env_file_encoding='utf-8', extra='ignore')
+    model_config = SettingsConfigDict(
+        env_file=f'{BASE_PATH}/.env', env_file_encoding='utf-8', extra='ignore', case_sensitive=True
+    )
 
-    # Env Config
+    # 环境配置（从环境变量读取）
     ENVIRONMENT: Literal['dev', 'pro']
 
-    # Env Database Type
+    # 数据库配置（从环境变量读取）
     DATABASE_TYPE: Literal['mysql', 'postgresql']
-
-    # Env Database
     DATABASE_HOST: str
     DATABASE_PORT: int
     DATABASE_USER: str
     DATABASE_PASSWORD: str
 
-    # Env Redis
+    # Redis 配置（从环境变量读取）
     REDIS_HOST: str
     REDIS_PORT: int
     REDIS_PASSWORD: str
     REDIS_DATABASE: int
 
-    # Env Token
+    # Token 配置（从环境变量读取）
     TOKEN_SECRET_KEY: str  # 密钥 secrets.token_urlsafe(32)
 
-    # Env Opera Log
+    # 操作日志加密密钥（从环境变量读取）
     OPERA_LOG_ENCRYPT_SECRET_KEY: str  # 密钥 os.urandom(32), 需使用 bytes.hex() 方法转换为 str
 
-    # FastAPI
-    FASTAPI_API_V1_PATH: str = '/api/v1'
-    FASTAPI_TITLE: str = 'FastAPI'
-    FASTAPI_VERSION: str = '0.0.1'
-    FASTAPI_DESCRIPTION: str = 'FastAPI Best Architecture'
-    FASTAPI_DOCS_URL: str = '/docs'
-    FASTAPI_REDOC_URL: str = '/redoc'
-    FASTAPI_OPENAPI_URL: str | None = '/openapi'
-    FASTAPI_STATIC_FILES: bool = True
-
-    # Upload
-    UPLOAD_READ_SIZE: int = 1024  # 上传文件时分片读取大小
-    UPLOAD_IMAGE_EXT_INCLUDE: list[str] = ['jpg', 'jpeg', 'png', 'gif', 'webp']
-    UPLOAD_IMAGE_SIZE_MAX: int = 1024 * 1024 * 5
-    UPLOAD_VIDEO_EXT_INCLUDE: list[str] = ['mp4', 'mov', 'avi', 'flv']
-    UPLOAD_VIDEO_SIZE_MAX: int = 1024 * 1024 * 20
-
-    # Database
+    # 数据库配置（默认值）
     DATABASE_ECHO: bool = False
     DATABASE_POOL_ECHO: bool = False
     DATABASE_SCHEMA: str = 'fba'
     DATABASE_CHARSET: str = 'utf8mb4'
 
-    # Redis
+    # Redis 配置（默认值）
     REDIS_TIMEOUT: int = 5
 
-    # Socketio
-    WS_NO_AUTH_MARKER: str = 'internal'
-
-    # Token
-    TOKEN_ALGORITHM: str = 'HS256'  # 算法
-    TOKEN_EXPIRE_SECONDS: int = 60 * 60 * 24 * 1  # 过期时间，单位：秒
-    TOKEN_REFRESH_EXPIRE_SECONDS: int = 60 * 60 * 24 * 7  # refresh token 过期时间，单位：秒
+    # Token 配置（默认值）
+    TOKEN_ALGORITHM: str = 'HS256'
+    TOKEN_EXPIRE_SECONDS: int = 60 * 60 * 24  # 1 天
+    TOKEN_REFRESH_EXPIRE_SECONDS: int = 60 * 60 * 24 * 7  # 7 天
     TOKEN_REDIS_PREFIX: str = 'fba:token'
     TOKEN_EXTRA_INFO_REDIS_PREFIX: str = 'fba:token_extra_info'
     TOKEN_ONLINE_REDIS_PREFIX: str = 'fba:token_online'
     TOKEN_REFRESH_REDIS_PREFIX: str = 'fba:refresh_token'
-    TOKEN_REQUEST_PATH_EXCLUDE: list[str] = [  # JWT / RBAC 白名单
-        f'{FASTAPI_API_V1_PATH}/auth/login',
+    TOKEN_REQUEST_PATH_EXCLUDE: list[str] = [  # JWT / RBAC 路由白名单
+        '/api/v1/auth/login',
     ]
 
-    # JWT
+    # JWT 配置（默认值）
     JWT_USER_REDIS_PREFIX: str = 'fba:user'
-    JWT_USER_REDIS_EXPIRE_SECONDS: int = 60 * 60 * 24 * 7
+    JWT_USER_REDIS_EXPIRE_SECONDS: int = 60 * 60 * 24 * 7  # 7 天
 
-    # RBAC
+    # RBAC 配置（默认值）
     RBAC_ROLE_MENU_MODE: bool = False
     RBAC_ROLE_MENU_EXCLUDE: list[str] = [
         'sys:monitor:redis',
         'sys:monitor:server',
     ]
 
-    # Cookies
+    # Cookie 配置（默认值）
     COOKIE_REFRESH_TOKEN_KEY: str = 'fba_refresh_token'
-    COOKIE_REFRESH_TOKEN_EXPIRE_SECONDS: int = TOKEN_REFRESH_EXPIRE_SECONDS
+    COOKIE_REFRESH_TOKEN_EXPIRE_SECONDS: int = 60 * 60 * 24 * 7  # 7 天
+
+    # FastAPI 配置（默认值）
+    FASTAPI_API_V1_PATH: str = '/api/v1'
+    FASTAPI_TITLE: str = 'FastAPI'
+    FASTAPI_VERSION: str = '0.0.1'
+    FASTAPI_DESCRIPTION: str = 'FastAPI Best Architecture'
+    FASTAPI_DOCS_URL: str = '/docs'
+    FASTAPI_REDOC_URL: str = '/redoc'
+    FASTAPI_OPENAPI_URL: str | None = '/openapi'
+    FASTAPI_STATIC_FILES: bool = True
+
+    # Socketio 配置（默认值）
+    WS_NO_AUTH_MARKER: str = 'internal'
+
+    # 文件上传配置（默认值）
+    UPLOAD_READ_SIZE: int = 1024
+    UPLOAD_IMAGE_EXT_INCLUDE: list[str] = ['jpg', 'jpeg', 'png', 'gif', 'webp']
+    UPLOAD_IMAGE_SIZE_MAX: int = 5 * 1024 * 1024  # 5 MB
+    UPLOAD_VIDEO_EXT_INCLUDE: list[str] = ['mp4', 'mov', 'avi', 'flv']
+    UPLOAD_VIDEO_SIZE_MAX: int = 20 * 1024 * 1024  # 20 MB
 
-    # Log
+    # 日志配置（默认值）
     LOG_CID_DEFAULT_VALUE: str = '-'
-    LOG_CID_UUID_LENGTH: int = 32  # must <= 32
+    LOG_CID_UUID_LENGTH: int = 32  # 日志 correlation_id 长度，必须小于等于 32
     LOG_STD_LEVEL: str = 'INFO'
     LOG_ACCESS_FILE_LEVEL: str = 'INFO'
     LOG_ERROR_FILE_LEVEL: str = 'ERROR'
@@ -111,51 +111,51 @@ class Settings(BaseSettings):
     LOG_ACCESS_FILENAME: str = 'fba_access.log'
     LOG_ERROR_FILENAME: str = 'fba_error.log'
 
-    # Middleware
+    # 中间件配置（默认值）
     MIDDLEWARE_CORS: bool = True
     MIDDLEWARE_ACCESS: bool = True
 
-    # Trace ID
+    # 追踪 ID 配置（默认值）
     TRACE_ID_REQUEST_HEADER_KEY: str = 'X-Request-ID'
 
-    # CORS
-    CORS_ALLOWED_ORIGINS: list[str] = [
+    # CORS 配置（默认值）
+    CORS_ALLOWED_ORIGINS: list[str] = [  # 末尾不带斜杠
         'http://127.0.0.1:8000',
-        'http://localhost:5173',  # 前端地址，末尾不要带 '/'
+        'http://localhost:5173',
     ]
     CORS_EXPOSE_HEADERS: list[str] = [
-        TRACE_ID_REQUEST_HEADER_KEY,
+        'X-Request-ID',
     ]
 
-    # DateTime
+    # 时间配置（默认值）
     DATETIME_TIMEZONE: str = 'Asia/Shanghai'
     DATETIME_FORMAT: str = '%Y-%m-%d %H:%M:%S'
 
-    # Request limiter
+    # 请求限制配置（默认值）
     REQUEST_LIMITER_REDIS_PREFIX: str = 'fba:limiter'
 
-    # Demo mode (Only GET, OPTIONS requests are allowed)
+    # 演示模式配置（默认值）
     DEMO_MODE: bool = False
     DEMO_MODE_EXCLUDE: set[tuple[str, str]] = {
-        ('POST', f'{FASTAPI_API_V1_PATH}/auth/login'),
-        ('POST', f'{FASTAPI_API_V1_PATH}/auth/logout'),
-        ('GET', f'{FASTAPI_API_V1_PATH}/auth/captcha'),
+        ('POST', '/api/v1/auth/login'),
+        ('POST', '/api/v1/auth/logout'),
+        ('GET', '/api/v1/auth/captcha'),
     }
 
-    # Ip location
+    # IP 定位配置（默认值）
     IP_LOCATION_PARSE: Literal['online', 'offline', 'false'] = 'offline'
     IP_LOCATION_REDIS_PREFIX: str = 'fba:ip:location'
-    IP_LOCATION_EXPIRE_SECONDS: int = 60 * 60 * 24 * 1  # 过期时间，单位：秒
+    IP_LOCATION_EXPIRE_SECONDS: int = 60 * 60 * 24  # 1 天
 
-    # Opera log
+    # 操作日志配置（默认值）
     OPERA_LOG_PATH_EXCLUDE: list[str] = [
         '/favicon.ico',
-        FASTAPI_DOCS_URL,
-        FASTAPI_REDOC_URL,
-        FASTAPI_OPENAPI_URL,
-        f'{FASTAPI_API_V1_PATH}/auth/login/swagger',
-        f'{FASTAPI_API_V1_PATH}/oauth2/github/callback',
-        f'{FASTAPI_API_V1_PATH}/oauth2/linux-do/callback',
+        '/docs',
+        '/redoc',
+        '/openapi',
+        '/api/v1/auth/login/swagger',
+        '/api/v1/oauth2/github/callback',
+        '/api/v1/oauth2/linux-do/callback',
     ]
     OPERA_LOG_ENCRYPT_TYPE: int = 1  # 0: AES (性能损耗); 1: md5; 2: ItsDangerous; 3: 不加密, others: 替换为 ******
     OPERA_LOG_ENCRYPT_KEY_INCLUDE: list[str] = [  # 将加密接口入参参数对应的值
@@ -165,10 +165,8 @@ class Settings(BaseSettings):
         'confirm_password',
     ]
 
-    # Data permission
-    DATA_PERMISSION_MODELS: dict[
-        str, str
-    ] = {  # 允许进行数据过滤的 SQLA 模型，它必须以模块字符串的方式定义（它应该只用于前台数据，这里只是为了演示）
+    # 数据权限配置（默认值）
+    DATA_PERMISSION_MODELS: dict[str, str] = {  # 允许进行数据过滤的 SQLA 模型，它必须以模块字符串的方式定义
         'Api': 'backend.plugin.casbin.model.Api',
     }
     DATA_PERMISSION_COLUMN_EXCLUDE: list[str] = [  # 排除允许进行数据过滤的 SQLA 模型列
@@ -178,24 +176,25 @@ class Settings(BaseSettings):
         'updated_time',
     ]
 
-    # Plugin
+    # 插件配置（默认值）
     PLUGIN_PIP_CHINA: bool = True
     PLUGIN_PIP_INDEX_URL: str = 'https://mirrors.aliyun.com/pypi/simple/'
 
     @model_validator(mode='before')
     @classmethod
     def check_env(cls, values: Any) -> Any:
-        if values['ENVIRONMENT'] == 'pro':
+        """生产环境下禁用 OpenAPI 文档和静态文件服务"""
+        if values.get('ENVIRONMENT') == 'pro':
             values['FASTAPI_OPENAPI_URL'] = None
             values['FASTAPI_STATIC_FILES'] = False
         return values
 
 
 @lru_cache
 def get_settings() -> Settings:
-    """获取全局配置"""
+    """获取全局配置单例"""
     return Settings()
 
 
-# 创建配置实例
+# 创建全局配置实例
 settings = get_settings()

backend/core/path_conf.py

@@ -1,30 +1,27 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-import os
-
 from pathlib import Path
 
-# 获取项目根目录
-# 或使用绝对路径，指到backend目录为止，例如windows：BasePath = D:\git_project\fastapi_mysql\backend
-BasePath = Path(__file__).resolve().parent.parent
+# 项目根目录
+BASE_PATH = Path(__file__).resolve().parent.parent
 
 # alembic 迁移文件存放路径
-ALEMBIC_VERSION_DIR = os.path.join(BasePath, 'alembic', 'versions')
+ALEMBIC_VERSION_DIR = BASE_PATH / 'alembic' / 'versions'
 
 # 日志文件路径
-LOG_DIR = os.path.join(BasePath, 'log')
-
-# 离线 IP 数据库路径
-IP2REGION_XDB = os.path.join(BasePath, 'static', 'ip2region.xdb')
+LOG_DIR = BASE_PATH / 'log'
 
 # 静态资源目录
-STATIC_DIR = os.path.join(BasePath, 'static')
+STATIC_DIR = BASE_PATH / 'static'
 
 # 上传文件目录
-UPLOAD_DIR = os.path.join(BasePath, 'static', 'upload')
+UPLOAD_DIR = STATIC_DIR / 'upload'
 
 # jinja2 模版文件路径
-JINJA2_TEMPLATE_DIR = os.path.join(BasePath, 'templates')
+JINJA2_TEMPLATE_DIR = BASE_PATH / 'templates'
 
 # 插件目录
-PLUGIN_DIR = os.path.join(BasePath, 'plugin')
+PLUGIN_DIR = BASE_PATH / 'plugin'
+
+# 离线 IP 数据库路径
+IP2REGION_XDB = STATIC_DIR / 'ip2region.xdb'