Optimize common

Author: wu-clan

backend/app/admin/api/v1/sys/token.py

@@ -9,7 +9,7 @@
 from backend.app.admin.schema.token import GetTokenDetail, KickOutToken
 from backend.common.enums import StatusType
 from backend.common.response.response_schema import ResponseModel, ResponseSchemaModel, response_base
-from backend.common.security.jwt import DependsJwtAuth, jwt_decode, superuser_verify
+from backend.common.security.jwt import DependsJwtAuth, jwt_decode, revoke_token, superuser_verify
 from backend.common.security.permission import RequestPermission
 from backend.common.security.rbac import DependsRBAC
 from backend.core.conf import settings
@@ -78,7 +78,9 @@ def append_token_detail():
         DependsRBAC,
     ],
 )
-async def kick_out(request: Request, pk: Annotated[int, Path(...)], session_uuid: KickOutToken) -> ResponseModel:
+async def kick_out(
+    request: Request, pk: Annotated[int, Path(..., description='用户 ID')], session_uuid: KickOutToken
+) -> ResponseModel:
     superuser_verify(request)
-    await redis_client.delete(f'{settings.TOKEN_REDIS_PREFIX}:{pk}:{session_uuid}')
+    await revoke_token(pk)
     return response_base.success()

backend/app/admin/crud/crud_user.py

@@ -193,7 +193,7 @@ async def get_list(
             )
             .order_by(desc(self.model.join_time))
         )
-        
+
         filters = []
         if dept:
             filters.append(self.model.dept_id == dept)
@@ -203,7 +203,7 @@ async def get_list(
             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))
 
@@ -315,18 +315,18 @@ async def get_with_relation(
                 selectinload(Role.rules),
             ),
         )
-        
+
         filters = []
         if user_id:
             filters.append(self.model.id == user_id)
         if username:
             filters.append(self.model.username == username)
-            
+
         if filters:
             stmt = stmt.where(and_(*filters))
-    
+
         user = await db.execute(stmt)
-            
+
         return user.scalars().first()
 
 

backend/app/admin/model/user.py

@@ -5,7 +5,7 @@
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import VARBINARY, Boolean, DateTime, ForeignKey, String, Index
+from sqlalchemy import VARBINARY, Boolean, DateTime, ForeignKey, String
 from sqlalchemy.dialects.postgresql import BYTEA, INTEGER
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 

backend/app/admin/service/user_service.py

@@ -301,9 +301,7 @@ async def update_multi_login(*, request: Request, pk: int) -> int:
             if pk == user_id:
                 if not latest_multi_login:
                     key_prefix = f'{settings.TOKEN_REDIS_PREFIX}:{pk}'
-                    await redis_client.delete_prefix(
-                        key_prefix, exclude=f'{key_prefix}:{token_payload.session_uuid}'
-                    )
+                    await redis_client.delete_prefix(key_prefix, exclude=f'{key_prefix}:{token_payload.session_uuid}')
                     refresh_token = request.cookies.get(settings.COOKIE_REFRESH_TOKEN_KEY)
                     if refresh_token:
                         key_prefix = f'{settings.TOKEN_REFRESH_REDIS_PREFIX}:{pk}'

backend/common/enums.py

@@ -2,27 +2,38 @@
 # -*- coding: utf-8 -*-
 from enum import Enum
 from enum import IntEnum as SourceIntEnum
-from typing import Type
+from typing import Any, Type, TypeVar
+
+T = TypeVar('T', bound=Enum)
 
 
 class _EnumBase:
+    """枚举基类，提供通用方法"""
+
     @classmethod
-    def get_member_keys(cls: Type[Enum]) -> list[str]:
+    def get_member_keys(cls: Type[T]) -> list[str]:
+        """获取枚举成员名称列表"""
         return [name for name in cls.__members__.keys()]
 
     @classmethod
-    def get_member_values(cls: Type[Enum]) -> list:
+    def get_member_values(cls: Type[T]) -> list:
+        """获取枚举成员值列表"""
         return [item.value for item in cls.__members__.values()]
 
+    @classmethod
+    def get_member_dict(cls: Type[T]) -> dict[str, Any]:
+        """获取枚举成员字典"""
+        return {name: item.value for name, item in cls.__members__.items()}
+
 
 class IntEnum(_EnumBase, SourceIntEnum):
-    """整型枚举"""
+    """整型枚举基类"""
 
     pass
 
 
 class StrEnum(_EnumBase, str, Enum):
-    """字符串枚举"""
+    """字符串枚举基类"""
 
     pass
 
@@ -56,7 +67,7 @@ class RoleDataRuleExpressionType(IntEnum):
 
 
 class MethodType(StrEnum):
-    """请求方法"""
+    """HTTP 请求方法"""
 
     GET = 'GET'
     POST = 'POST'
@@ -67,7 +78,7 @@ class MethodType(StrEnum):
 
 
 class LoginLogStatusType(IntEnum):
-    """登陆日志状态"""
+    """登录日志状态"""
 
     fail = 0
     success = 1
@@ -176,7 +187,7 @@ class GenModelMySQLColumnType(StrEnum):
 
 
 class GenModelPostgreSQLColumnType(StrEnum):
-    """代码生成模型列类型（PostgreSQL），仅作为数据保留，并未实施"""
+    """代码生成模型列类型（PostgreSQL）"""
 
     # Python 类型映射
     BIGINT = 'int'

backend/common/exception/exception_handler.py

@@ -3,7 +3,6 @@
 from fastapi import FastAPI, Request
 from fastapi.exceptions import RequestValidationError
 from pydantic import ValidationError
-from pydantic.errors import PydanticUserError
 from starlette.exceptions import HTTPException
 from starlette.middleware.cors import CORSMiddleware
 from uvicorn.protocols.http.h11_impl import STATUS_PHRASES
@@ -12,44 +11,41 @@
 from backend.common.response.response_code import CustomResponseCode, StandardResponseCode
 from backend.common.response.response_schema import response_base
 from backend.common.schema import (
-    CUSTOM_USAGE_ERROR_MESSAGES,
     CUSTOM_VALIDATION_ERROR_MESSAGES,
 )
 from backend.core.conf import settings
 from backend.utils.serializers import MsgSpecJSONResponse
 from backend.utils.trace_id import get_request_trace_id
 
 
-def _get_exception_code(status_code: int):
+def _get_exception_code(status_code: int) -> int:
     """
-    获取返回状态码, OpenAPI, Uvicorn... 可用状态码基于 RFC 定义, 详细代码见下方链接
+    获取返回状态码（可用状态码基于 RFC 定义）
 
-    `python 状态码标准支持 <https://github.com/python/cpython/blob/6e3cc72afeaee2532b4327776501eb8234ac787b/Lib/http
-    /__init__.py#L7>`__
+    `python 状态码标准支持 <https://github.com/python/cpython/blob/6e3cc72afeaee2532b4327776501eb8234ac787b/Lib/http/__init__.py#L7>`__
 
     `IANA 状态码注册表 <https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml>`__
 
-    :param status_code:
+    :param status_code: HTTP 状态码
     :return:
     """
     try:
         STATUS_PHRASES[status_code]
+        return status_code
     except Exception:
-        code = StandardResponseCode.HTTP_400
-    else:
-        code = status_code
-    return code
+        return StandardResponseCode.HTTP_400
 
 
-async def _validation_exception_handler(request: Request, e: RequestValidationError | ValidationError):
+async def _validation_exception_handler(request: Request, exc: RequestValidationError | ValidationError):
     """
     数据验证异常处理
 
-    :param e:
+    :param request: 请求对象
+    :param exc: 验证异常
     :return:
     """
     errors = []
-    for error in e.errors():
+    for error in exc.errors():
         custom_message = CUSTOM_VALIDATION_ERROR_MESSAGES.get(error['type'])
         if custom_message:
             ctx = error.get('ctx')
@@ -87,10 +83,10 @@ def register_exception(app: FastAPI):
     @app.exception_handler(HTTPException)
     async def http_exception_handler(request: Request, exc: HTTPException):
         """
-        全局HTTP异常处理
+        全局 HTTP 异常处理
 
-        :param request:
-        :param exc:
+        :param request: FastAPI 请求对象
+        :param exc: HTTP 异常
         :return:
         """
         if settings.ENVIRONMENT == 'dev':
@@ -113,53 +109,32 @@ async def http_exception_handler(request: Request, exc: HTTPException):
     @app.exception_handler(RequestValidationError)
     async def fastapi_validation_exception_handler(request: Request, exc: RequestValidationError):
         """
-        fastapi 数据验证异常处理
+        FastAPI 数据验证异常处理
 
-        :param request:
-        :param exc:
+        :param request: FastAPI 请求对象
+        :param exc: 验证异常
         :return:
         """
         return await _validation_exception_handler(request, exc)
 
     @app.exception_handler(ValidationError)
     async def pydantic_validation_exception_handler(request: Request, exc: ValidationError):
         """
-        pydantic 数据验证异常处理
+        Pydantic 数据验证异常处理
 
-        :param request:
-        :param exc:
+        :param request: 请求对象
+        :param exc: 验证异常
         :return:
         """
         return await _validation_exception_handler(request, exc)
 
-    @app.exception_handler(PydanticUserError)
-    async def pydantic_user_error_handler(request: Request, exc: PydanticUserError):
-        """
-        Pydantic 用户异常处理
-
-        :param request:
-        :param exc:
-        :return:
-        """
-        content = {
-            'code': StandardResponseCode.HTTP_500,
-            'msg': CUSTOM_USAGE_ERROR_MESSAGES.get(exc.code),
-            'data': None,
-        }
-        request.state.__request_pydantic_user_error__ = content
-        content.update(trace_id=get_request_trace_id(request))
-        return MsgSpecJSONResponse(
-            status_code=StandardResponseCode.HTTP_500,
-            content=content,
-        )
-
     @app.exception_handler(AssertionError)
     async def assertion_error_handler(request: Request, exc: AssertionError):
         """
         断言错误处理
 
-        :param request:
-        :param exc:
+        :param request: FastAPI 请求对象
+        :param exc: 断言错误
         :return:
         """
         if settings.ENVIRONMENT == 'dev':
@@ -183,8 +158,8 @@ async def custom_exception_handler(request: Request, exc: BaseExceptionMixin):
         """
         全局自定义异常处理
 
-        :param request:
-        :param exc:
+        :param request: FastAPI 请求对象
+        :param exc: 自定义异常
         :return:
         """
         content = {
@@ -205,8 +180,8 @@ async def all_unknown_exception_handler(request: Request, exc: Exception):
         """
         全局未知异常处理
 
-        :param request:
-        :param exc:
+        :param request: FastAPI 请求对象
+        :param exc: 未知异常
         :return:
         """
         if settings.ENVIRONMENT == 'dev':
@@ -233,10 +208,11 @@ async def cors_custom_code_500_exception_handler(request, exc):
             跨域自定义 500 异常处理
 
             `Related issue <https://github.com/encode/starlette/issues/1175>`_
+
             `Solution <https://github.com/fastapi/fastapi/discussions/7847#discussioncomment-5144709>`_
 
-            :param request:
-            :param exc:
+            :param request: FastAPI 请求对象
+            :param exc: 自定义异常
             :return:
             """
             if isinstance(exc, BaseExceptionMixin):

backend/common/log.py

@@ -14,9 +14,9 @@
 
 class InterceptHandler(logging.Handler):
     """
-    默认处理器，来自 loguru 文档示例
+    日志拦截处理器，用于将标准库的日志重定向到 loguru
 
-    参见 https://loguru.readthedocs.io/en/stable/overview.html#entirely-compatible-with-standard-logging
+    参考：https://loguru.readthedocs.io/en/stable/overview.html#entirely-compatible-with-standard-logging
     """
 
     def emit(self, record: logging.LogRecord):
@@ -35,10 +35,10 @@ def emit(self, record: logging.LogRecord):
         logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
 
 
-def setup_logging():
+def setup_logging() -> None:
     """
     设置日志处理器
-    
+
     参考：
     - https://github.com/benoitc/gunicorn/issues/1572#issuecomment-638391953
     - https://github.com/pawamoy/pawamoy.github.io/issues/17
@@ -47,7 +47,7 @@ def setup_logging():
     logging.root.handlers = [InterceptHandler()]
     logging.root.setLevel(settings.LOG_STD_LEVEL)
 
-    # 移除所有日志处理器并传播到根日志记录器
+    # 配置日志传播规则
     for name in logging.root.manager.loggerDict.keys():
         logging.getLogger(name).handlers = []
         if 'uvicorn.access' in name or 'watchfiles.main' in name:
@@ -65,10 +65,8 @@ def correlation_id_filter(record):
         record['correlation_id'] = cid[: settings.LOG_CID_UUID_LENGTH]
         return record
 
-    # 移除默认 loguru 日志记录器
-    logger.remove()
-
-    # 设置 loguru 默认处理器
+    # 配置 loguru 处理器
+    logger.remove()  # 移除默认处理器
     logger.configure(
         handlers=[
             {
@@ -81,7 +79,7 @@ def correlation_id_filter(record):
     )
 
 
-def set_custom_logfile():
+def set_custom_logfile() -> None:
     """设置自定义日志文件"""
     log_path = path_conf.LOG_DIR
     if not os.path.exists(log_path):
@@ -91,7 +89,7 @@ def set_custom_logfile():
     log_access_file = os.path.join(log_path, settings.LOG_ACCESS_FILENAME)
     log_error_file = os.path.join(log_path, settings.LOG_ERROR_FILENAME)
 
-    # 设置 loguru 日志记录器默认配置
+    # 日志文件通用配置
     # https://loguru.readthedocs.io/en/stable/api/logger.html#loguru._logger.Logger.add
     log_config = {
         'format': settings.LOG_FILE_FORMAT,
@@ -122,4 +120,5 @@ def set_custom_logfile():
     )
 
 
+# 创建 logger 实例
 log = logger