refactor: 大规模代码重构与项目配置优化

- 调整前端路由前缀为 /web 并新增配置项
- 重构环境变量配置，替换旧环境文件为 dev/prod/test 版本
- 优化后端接口路由与参数校验，替换 dataclass 查询参数为 Pydantic 模型
- 整理后端导入顺序，延迟加载循环依赖模块
- 统一前端 API 调用命名，重构模块命名
- 新增多种响应类型支持，优化代码模板
- 简化后端路由装饰器写法，合并配置参数

backend/app/api/v1/module_monitor/cache/controller.py

@@ -14,12 +14,7 @@ from .service import CacheService
 CacheRouter = APIRouter(route_class=OperationLogRoute, prefix="/cache", tags=["缓存监控"])
 
 
-@CacheRouter.get(
-    "/info",
-    dependencies=[Depends(AuthPermission(["module_monitor:cache:query"]))],
-    summary="获取缓存监控信息",
-    response_model=ResponseSchema[CacheMonitorSchema],
-)
+@CacheRouter.get("/info", summary="获取缓存监控信息", response_model=ResponseSchema[CacheMonitorSchema], dependencies=[Depends(AuthPermission(["module_monitor:cache:query"]))])
 async def get_monitor_cache_info_controller(
     redis: Annotated[Redis, Depends(redis_getter)],
 ) -> JSONResponse:
@@ -27,23 +22,13 @@ async def get_monitor_cache_info_controller(
     return SuccessResponse(data=result, msg="获取缓存监控信息成功")
 
 
-@CacheRouter.get(
-    "/get/names",
-    dependencies=[Depends(AuthPermission(["module_monitor:cache:query"]))],
-    summary="获取缓存名称列表",
-    response_model=ResponseSchema[list[CacheInfoSchema]],
-)
+@CacheRouter.get("/get/names", summary="获取缓存名称列表", response_model=ResponseSchema[list[CacheInfoSchema]], dependencies=[Depends(AuthPermission(["module_monitor:cache:query"]))])
 async def get_monitor_cache_name_controller() -> JSONResponse:
     result = await CacheService.get_monitor_cache_names()
     return SuccessResponse(data=result, msg="获取缓存名称列表成功")
 
 
-@CacheRouter.get(
-    "/get/keys/{cache_name}",
-    dependencies=[Depends(AuthPermission(["module_monitor:cache:query"]))],
-    summary="获取缓存键名列表",
-    response_model=ResponseSchema[list[CacheInfoSchema]],
-)
+@CacheRouter.get("/get/keys/{cache_name}", summary="获取缓存键名列表", response_model=ResponseSchema[list[CacheInfoSchema]], dependencies=[Depends(AuthPermission(["module_monitor:cache:query"]))])
 async def get_monitor_cache_key_controller(
     cache_name: Annotated[str, Path(description="缓存名称")],
     redis: Annotated[Redis, Depends(redis_getter)]
@@ -52,12 +37,7 @@ async def get_monitor_cache_key_controller(
     return SuccessResponse(data=result, msg=f"获取缓存{cache_name}的键名列表成功")
 
 
-@CacheRouter.get(
-    "/get/value/{cache_name}/{cache_key}",
-    dependencies=[Depends(AuthPermission(["module_monitor:cache:query"]))],
-    summary="获取缓存值",
-    response_model=ResponseSchema[CacheInfoSchema],
-)
+@CacheRouter.get("/get/value/{cache_name}/{cache_key}", summary="获取缓存值", response_model=ResponseSchema[CacheInfoSchema], dependencies=[Depends(AuthPermission(["module_monitor:cache:query"]))])
 async def get_monitor_cache_value_controller(
     cache_name: Annotated[str, Path(description="缓存名称")],
     cache_key: Annotated[str, Path(description="缓存键名")],
@@ -67,12 +47,7 @@ async def get_monitor_cache_value_controller(
     return SuccessResponse(data=result, msg=f"获取缓存{cache_name}:{cache_key}的值成功")
 
 
-@CacheRouter.delete(
-    "/delete/name/{cache_name}",
-    dependencies=[Depends(AuthPermission(["module_monitor:cache:delete"]))],
-    summary="清除指定缓存名称的所有缓存",
-    response_model=ResponseSchema[None],
-)
+@CacheRouter.delete("/delete/name/{cache_name}", summary="清除指定缓存名称的所有缓存", response_model=ResponseSchema[None], dependencies=[Depends(AuthPermission(["module_monitor:cache:delete"]))])
 async def clear_monitor_cache_name_controller(
     cache_name: Annotated[str, Path(description="缓存名称")],
     redis: Annotated[Redis, Depends(redis_getter)]
@@ -81,12 +56,7 @@ async def clear_monitor_cache_name_controller(
     return SuccessResponse(msg=f"{cache_name}对应键值清除成功", data=result)
 
 
-@CacheRouter.delete(
-    "/delete/key/{cache_key}",
-    dependencies=[Depends(AuthPermission(["module_monitor:cache:delete"]))],
-    summary="清除指定缓存键",
-    response_model=ResponseSchema[None],
-)
+@CacheRouter.delete("/delete/key/{cache_key}", summary="清除指定缓存键", response_model=ResponseSchema[None], dependencies=[Depends(AuthPermission(["module_monitor:cache:delete"]))])
 async def clear_monitor_cache_key_controller(
     cache_key: Annotated[str, Path(description="缓存键名")],
     redis: Annotated[Redis, Depends(redis_getter)]
@@ -95,12 +65,7 @@ async def clear_monitor_cache_key_controller(
     return SuccessResponse(msg=f"{cache_key}清除成功", data=result)
 
 
-@CacheRouter.delete(
-    "/clear",
-    dependencies=[Depends(AuthPermission(["module_monitor:cache:delete"]))],
-    summary="清除所有缓存",
-    response_model=ResponseSchema[None],
-)
+@CacheRouter.delete("/clear", summary="清除所有缓存", response_model=ResponseSchema[None], dependencies=[Depends(AuthPermission(["module_monitor:cache:delete"]))])
 async def clear_monitor_cache_all_controller(
     redis: Annotated[Redis, Depends(redis_getter)],
 ) -> JSONResponse:

backend/app/api/v1/module_monitor/online/controller.py

@@ -6,7 +6,7 @@ from redis.asyncio.client import Redis
 
 from app.common.request import PaginationService
 from app.common.response import ResponseSchema, SuccessResponse
-from app.core.base_params import PaginationQueryParam
+from app.core.base_schema import PaginationQueryParam
 from app.core.dependencies import AuthPermission, redis_getter
 from app.core.router_class import OperationLogRoute
 
@@ -16,16 +16,11 @@ from .service import OnlineService
 OnlineRouter = APIRouter(route_class=OperationLogRoute, prefix="/online", tags=["在线用户"])
 
 
-@OnlineRouter.get(
-    "/list",
-    dependencies=[Depends(AuthPermission(["module_monitor:online:query"]))],
-    summary="获取在线用户列表",
-    response_model=ResponseSchema[list[OnlineOutSchema]],
-)
+@OnlineRouter.get("/list", summary="获取在线用户列表", response_model=ResponseSchema[list[OnlineOutSchema]], dependencies=[Depends(AuthPermission(["module_monitor:online:query"]))])
 async def get_online_list_controller(
     redis: Annotated[Redis, Depends(redis_getter)],
-    page: Annotated[PaginationQueryParam, Query()],
-    search: Annotated[OnlineQueryParam, Query()],
+    page: Annotated[PaginationQueryParam, Query(description="分页参数")],
+    search: Annotated[OnlineQueryParam, Query(description="在线用户查询参数")],
 ) -> JSONResponse:
     result_dict_list = await OnlineService.get_online_list(redis=redis, search=search)
     result_dict = await PaginationService.paginate(
@@ -36,12 +31,7 @@ async def get_online_list_controller(
     return SuccessResponse(data=result_dict, msg="获取成功")
 
 
-@OnlineRouter.delete(
-    "/delete",
-    dependencies=[Depends(AuthPermission(["module_monitor:online:delete"]))],
-    summary="强制下线",
-    response_model=ResponseSchema[None],
-)
+@OnlineRouter.delete("/delete", summary="强制下线", response_model=ResponseSchema[None], dependencies=[Depends(AuthPermission(["module_monitor:online:delete"]))])
 async def delete_online_controller(
     session_id: Annotated[str, Body(description="会话编号")],
     redis: Annotated[Redis, Depends(redis_getter)],
@@ -50,12 +40,7 @@ async def delete_online_controller(
     return SuccessResponse(msg="强制下线成功")
 
 
-@OnlineRouter.delete(
-    "/clear",
-    dependencies=[Depends(AuthPermission(["module_monitor:online:delete"]))],
-    summary="清除所有在线用户",
-    response_model=ResponseSchema[None],
-)
+@OnlineRouter.delete("/clear", summary="清除所有在线用户", response_model=ResponseSchema[None], dependencies=[Depends(AuthPermission(["module_monitor:online:delete"]))])
 async def clear_online_controller(
     redis: Annotated[Redis, Depends(redis_getter)],
 ) -> JSONResponse:

backend/app/api/v1/module_monitor/online/schema.py

@@ -1,7 +1,4 @@
-from dataclasses import dataclass
-
-from fastapi import Query
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 
 from app.common.enums import QueueEnum
 from app.core.validator import DateTimeStr
@@ -26,16 +23,16 @@ class OnlineOutSchema(BaseModel):
     login_type: str | None = Field(default=None, description="登录类型 PC端 | 移动端")
 
 
-@dataclass
-class OnlineQueryParam:
+class OnlineQueryParam(BaseModel):
     """在线用户查询参数"""
 
-    def __init__(
-        self,
-        name: str | None = Query(None, description="登录名称"),
-        ipaddr: str | None = Query(None, description="登陆IP地址"),
-        login_location: str | None = Query(None, description="登录所属地"),
-    ) -> None:
-        self.name = (QueueEnum.like.value, f"%{name}%") if name else None
-        self.login_location = (QueueEnum.like.value, f"%{login_location}%") if login_location else None
-        self.ipaddr = (QueueEnum.like.value, f"%{ipaddr}%") if ipaddr else None
+    name: str | None = Field(None, description="登录名称")
+    ipaddr: str | None = Field(None, description="登陆IP地址")
+    login_location: str | None = Field(None, description="登录所属地")
+
+    @model_validator(mode="after")
+    def validate_query_params(self) -> "OnlineQueryParam":
+        self.name = (QueueEnum.like.value, self.name) if self.name else None
+        self.login_location = (QueueEnum.like.value, self.login_location) if self.login_location else None
+        self.ipaddr = (QueueEnum.like.value, self.ipaddr) if self.ipaddr else None
+        return self

backend/app/api/v1/module_monitor/resource/controller.py

@@ -6,35 +6,22 @@ from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
 from app.api.v1.module_common.file.service import FileService
 from app.common.request import PaginationService
 from app.common.response import ResponseSchema, StreamResponse, SuccessResponse, UploadFileResponse
-from app.core.base_params import PaginationQueryParam
-from app.core.base_schema import UploadResponseSchema
+from app.core.base_schema import PaginationQueryParam, UploadResponseSchema
 from app.core.dependencies import AuthPermission
 from app.core.router_class import OperationLogRoute
 from app.utils.common_util import bytes2file_response
 
-from .schema import (
-    ResourceCopySchema,
-    ResourceCreateDirSchema,
-    ResourceItemSchema,
-    ResourceMoveSchema,
-    ResourceRenameSchema,
-    ResourceSearchQueryParam,
-)
+from .schema import ResourceCopySchema, ResourceCreateDirSchema, ResourceItemSchema, ResourceMoveSchema, ResourceRenameSchema, ResourceSearchQueryParam
 from .service import ResourceService
 
 ResourceRouter = APIRouter(route_class=OperationLogRoute, prefix="/resource", tags=["资源管理"])
 
 
-@ResourceRouter.get(
-    "/list",
-    summary="获取目录列表",
-    response_model=ResponseSchema[list[ResourceItemSchema]],
-    dependencies=[Depends(AuthPermission(["module_monitor:resource:query"]))],
-)
+@ResourceRouter.get("/list", summary="获取目录列表", response_model=ResponseSchema[list[ResourceItemSchema]], dependencies=[Depends(AuthPermission(["module_monitor:resource:query"]))])
 async def get_directory_list_controller(
     request: Request,
-    page: Annotated[PaginationQueryParam, Query()],
-    search: Annotated[ResourceSearchQueryParam, Query()],
+    page: Annotated[PaginationQueryParam, Query(description="分页参数")],
+    search: Annotated[ResourceSearchQueryParam, Query(description="资源查询参数")],
 ) -> JSONResponse:
     result_dict_list = await ResourceService.get_resources_list(search=search, base_url=str(request.base_url))
     result_dict = await PaginationService.paginate(
@@ -45,12 +32,7 @@ async def get_directory_list_controller(
     return SuccessResponse(data=result_dict, msg="获取目录列表成功")
 
 
-@ResourceRouter.post(
-    "/upload",
-    summary="上传文件",
-    response_model=ResponseSchema[UploadResponseSchema],
-    dependencies=[Depends(AuthPermission(["module_monitor:resource:upload"]))],
-)
+@ResourceRouter.post("/upload", summary="上传文件", response_model=ResponseSchema[UploadResponseSchema], dependencies=[Depends(AuthPermission(["module_monitor:resource:upload"]))])
 async def upload_file_controller(
     request: Request,
     file: Annotated[UploadFile, File(description="上传文件")],
@@ -65,10 +47,7 @@ async def upload_file_controller(
     return SuccessResponse(data=result, msg="上传文件成功")
 
 
-@ResourceRouter.get(
-    "/download",
-    summary="下载文件",
-    dependencies=[Depends(AuthPermission(["module_monitor:resource:download"]))],
+@ResourceRouter.get("/download", summary="下载文件", response_model=UploadFileResponse, dependencies=[Depends(AuthPermission(["module_monitor:resource:download"]))],
 )
 async def download_file_controller(
     path: Annotated[str, Query(description="文件路径")],
@@ -86,12 +65,7 @@ async def download_file_controller(
     )
 
 
-@ResourceRouter.delete(
-    "/delete",
-    summary="删除文件",
-    response_model=ResponseSchema[None],
-    dependencies=[Depends(AuthPermission(["module_monitor:resource:delete"]))],
-)
+@ResourceRouter.delete("/delete", summary="删除文件", response_model=ResponseSchema[None], dependencies=[Depends(AuthPermission(["module_monitor:resource:delete"]))])
 async def delete_files_controller(
     paths: Annotated[list[str], Body(description="文件路径列表")],
 ) -> JSONResponse:
@@ -99,12 +73,7 @@ async def delete_files_controller(
     return SuccessResponse(msg="删除文件成功")
 
 
-@ResourceRouter.post(
-    "/move",
-    summary="移动文件",
-    response_model=ResponseSchema[None],
-    dependencies=[Depends(AuthPermission(["module_monitor:resource:move"]))],
-)
+@ResourceRouter.post("/move", summary="移动文件", response_model=ResponseSchema[None], dependencies=[Depends(AuthPermission(["module_monitor:resource:move"]))])
 async def move_file_controller(
     data: Annotated[ResourceMoveSchema, Body(description="移动文件参数")],
 ) -> JSONResponse:
@@ -112,12 +81,7 @@ async def move_file_controller(
     return SuccessResponse(msg="移动文件成功")
 
 
-@ResourceRouter.post(
-    "/copy",
-    summary="复制文件",
-    response_model=ResponseSchema[None],
-    dependencies=[Depends(AuthPermission(["module_monitor:resource:copy"]))],
-)
+@ResourceRouter.post("/copy", summary="复制文件", response_model=ResponseSchema[None], dependencies=[Depends(AuthPermission(["module_monitor:resource:copy"]))])
 async def copy_file_controller(
     data: Annotated[ResourceCopySchema, Body(description="复制文件参数")],
 ) -> JSONResponse:
@@ -125,12 +89,7 @@ async def copy_file_controller(
     return SuccessResponse(msg="复制文件成功")
 
 
-@ResourceRouter.post(
-    "/rename",
-    summary="重命名文件",
-    response_model=ResponseSchema[None],
-    dependencies=[Depends(AuthPermission(["module_monitor:resource:rename"]))],
-)
+@ResourceRouter.post("/rename", summary="重命名文件", response_model=ResponseSchema[None], dependencies=[Depends(AuthPermission(["module_monitor:resource:rename"]))])
 async def rename_file_controller(
     data: Annotated[ResourceRenameSchema, Body(description="重命名文件参数")],
 ) -> JSONResponse:
@@ -138,12 +97,7 @@ async def rename_file_controller(
     return SuccessResponse(msg="重命名文件成功")
 
 
-@ResourceRouter.post(
-    "/mkdir",
-    summary="创建目录",
-    response_model=ResponseSchema[None],
-    dependencies=[Depends(AuthPermission(["module_monitor:resource:mkdir"]))],
-)
+@ResourceRouter.post("/mkdir", summary="创建目录", response_model=ResponseSchema[None], dependencies=[Depends(AuthPermission(["module_monitor:resource:mkdir"]))])
 async def create_directory_controller(
     data: Annotated[ResourceCreateDirSchema, Body(description="创建目录参数")],
 ) -> JSONResponse:
@@ -151,16 +105,11 @@ async def create_directory_controller(
     return SuccessResponse(msg="创建目录成功")
 
 
-@ResourceRouter.post(
-    "/export",
-    summary="导出资源列表",
-    response_model=ResponseSchema[None],
-    dependencies=[Depends(AuthPermission(["module_monitor:resource:export"]))],
-)
+@ResourceRouter.post("/export", summary="导出资源列表", dependencies=[Depends(AuthPermission(["module_monitor:resource:export"]))])
 async def export_resource_list_controller(
     request: Request,
-    search: Annotated[ResourceSearchQueryParam, Query()],
-) -> StreamingResponse:
+    search: Annotated[ResourceSearchQueryParam, Query(description="资源查询参数")],
+) -> StreamingResponse[bytes]:
     result_dict_list = await ResourceService.get_resources_list(search=search, base_url=str(request.base_url))
     export_result = await ResourceService.export_resource(data_list=result_dict_list)
 

backend/app/api/v1/module_monitor/resource/schema.py

@@ -1,8 +1,6 @@
-from dataclasses import dataclass
 from datetime import datetime
 from urllib.parse import urlparse
 
-from fastapi import Query
 from pydantic import (
     BaseModel,
     ConfigDict,
@@ -188,15 +186,13 @@ class ResourceCreateDirSchema(BaseModel):
         return value.strip()
 
 
-@dataclass
-class ResourceSearchQueryParam:
+class ResourceSearchQueryParam(BaseModel):
     """资源搜索查询参数"""
 
-    def __init__(
-        self,
-        name: str | None = Query(None, description="搜索关键词"),
-        path: str | None = Query(None, description="目录路径"),
-    ) -> None:
-        self.name = (QueueEnum.like.value, name) if name else None
+    name: str | None = Field(None, description="搜索关键词")
+    path: str | None = Field(None, description="目录路径")
 
-        self.path = path
+    @model_validator(mode="after")
+    def validate_query_params(self) -> "ResourceSearchQueryParam":
+        self.name = (QueueEnum.like.value, self.name) if self.name else None
+        return self

backend/app/api/v1/module_monitor/server/controller.py

@@ -11,12 +11,7 @@ from .service import ServerService
 ServerRouter = APIRouter(route_class=OperationLogRoute, prefix="/server", tags=["服务器监控"])
 
 
-@ServerRouter.get(
-    "/info",
-    summary="查询服务器监控信息",
-    dependencies=[Depends(AuthPermission(["module_monitor:server:query"]))],
-    response_model=ResponseSchema[ServerMonitorSchema],
-)
+@ServerRouter.get("/info", summary="查询服务器监控信息", response_model=ResponseSchema[ServerMonitorSchema], dependencies=[Depends(AuthPermission(["module_monitor:server:query"]))])
 async def get_monitor_server_info_controller() -> JSONResponse:
     result_dict = await ServerService.get_server_monitor_info()
     return SuccessResponse(data=result_dict, msg="获取服务器监控信息成功")