15 KiB
15 KiB
错误处理与日志
**本文引用的文件** - [backend/app/main.py](file://backend/app/main.py) - [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/app/core/security.py](file://backend/app/core/security.py) - [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py) - [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py) - [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py) - [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py) - [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py) - [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py) - [backend/app/models/models.py](file://backend/app/models/models.py) - [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py) - [backend/app/services/department_service.py](file://backend/app/services/department_service.py) - [backend/FIX_SUMMARY.md](file://backend/FIX_SUMMARY.md)目录
简介
本指南面向“医院绩效系统”的后端工程团队，聚焦于错误处理与日志体系的设计与落地实践。内容涵盖：
- 全局异常处理机制与自定义异常类的使用
- 错误响应格式与统一返回结构
- 日志配置、日志级别、输出格式与轮转策略
- 结构化日志记录、上下文信息捕获与性能监控集成
- 错误追踪、堆栈信息收集与调试信息输出
- 日志轮转、文件管理与日志分析工具使用
- 生产环境日志监控、告警配置与故障诊断方法
- 安全日志记录、审计跟踪与合规性要求
项目结构
后端采用 FastAPI + SQLAlchemy 异步 ORM 的分层架构，错误处理与日志主要分布在应用入口、核心配置与日志模块中，并在各 API 路由中体现统一的异常抛出与响应格式。
graph TB
subgraph "应用入口"
MAIN["backend/app/main.py<br/>应用创建与全局异常处理器"]
CONFIG["backend/app/core/config.py<br/>应用配置"]
end
subgraph "日志与安全"
LOGCONF["backend/app/core/logging_config.py<br/>日志配置与轮转"]
SECURITY["backend/app/core/security.py<br/>认证与权限校验"]
end
subgraph "API 层"
API_INIT["backend/app/api/v1/__init__.py<br/>路由聚合"]
AUTH["backend/app/api/v1/auth.py<br/>认证接口"]
STAFF["backend/app/api/v1/staff.py<br/>员工接口"]
DEPT["backend/app/api/v1/departments.py<br/>科室接口"]
ASSESS["backend/app/api/v1/assessments.py<br/>考核接口"]
end
subgraph "领域模型与服务"
MODELS["backend/app/models/models.py<br/>数据模型"]
SCHEMAS["backend/app/schemas/schemas.py<br/>Pydantic 模式"]
SVC_STAFF["backend/app/services/staff_service.py"]
SVC_DEPT["backend/app/services/department_service.py"]
end
MAIN --> LOGCONF
MAIN --> CONFIG
MAIN --> API_INIT
API_INIT --> AUTH
API_INIT --> STAFF
API_INIT --> DEPT
API_INIT --> ASSESS
AUTH --> SECURITY
STAFF --> SVC_STAFF
DEPT --> SVC_DEPT
ASSESS --> SVC_STAFF
ASSESS --> SVC_DEPT
SVC_STAFF --> MODELS
SVC_DEPT --> MODELS
AUTH --> MODELS
STAFF --> MODELS
DEPT --> MODELS
ASSESS --> MODELS
SCHEMAS --> MODELS
图表来源
- backend/app/main.py
- backend/app/core/logging_config.py
- backend/app/core/config.py
- backend/app/core/security.py
- backend/app/api/v1/init.py
- backend/app/api/v1/auth.py
- backend/app/api/v1/staff.py
- backend/app/api/v1/departments.py
- backend/app/api/v1/assessments.py
- backend/app/models/models.py
- backend/app/schemas/schemas.py
- backend/app/services/staff_service.py
- backend/app/services/department_service.py
章节来源
核心组件
- 全局异常处理：在应用入口集中注册 HTTP 异常、请求验证异常与全局异常处理器，统一记录日志并向上抛出。
- 日志系统：集中配置控制台与文件输出，按级别分离，支持日志轮转与日期命名。
- 统一响应结构：在各 API 路由中返回统一的响应体结构，便于前端与监控系统解析。
- 安全与权限：在认证与权限校验中抛出标准化 HTTP 异常，确保错误语义清晰。
章节来源
架构总览
下图展示从请求进入应用到异常处理与日志记录的关键交互路径。
sequenceDiagram
participant Client as "客户端"
participant FastAPI as "FastAPI 应用"
participant Router as "API 路由"
participant Service as "业务服务"
participant DB as "数据库"
participant Logger as "日志系统"
Client->>FastAPI : "HTTP 请求"
FastAPI->>Router : "路由匹配与依赖注入"
Router->>Service : "调用业务逻辑"
Service->>DB : "SQLAlchemy 异步查询/写入"
DB-->>Service : "结果或异常"
alt "正常响应"
Service-->>Router : "业务结果"
Router-->>Client : "统一响应体"
else "异常场景"
Service-->>Router : "抛出 HTTP 异常"
Router-->>FastAPI : "异常冒泡"
FastAPI->>Logger : "记录异常日志(含堆栈)"
FastAPI-->>Client : "异常响应"
end
图表来源
- backend/app/main.py
- backend/app/api/v1/auth.py
- backend/app/api/v1/staff.py
- backend/app/api/v1/departments.py
- backend/app/api/v1/assessments.py
- backend/app/core/logging_config.py
详细组件分析
全局异常处理机制
- HTTP 异常处理器：记录请求方法、URL、状态码与详情，便于快速定位资源访问问题。
- 请求验证异常处理器：记录请求与验证错误，便于前端与接口调试。
- 全局异常处理器：记录未知异常并打印堆栈信息，确保问题可追溯。
flowchart TD
Start(["请求进入"]) --> Route["路由匹配与依赖注入"]
Route --> CallSvc["调用业务服务"]
CallSvc --> SvcOK{"业务执行成功?"}
SvcOK --> |是| BuildResp["构造统一响应"]
SvcOK --> |否| ThrowHTTP["抛出 HTTP 异常"]
ThrowHTTP --> GlobalLog["全局异常处理器记录日志(含堆栈)"]
GlobalLog --> RaiseExc["向上抛出异常"]
BuildResp --> End(["返回响应"])
RaiseExc --> End
图表来源
章节来源
自定义异常类与错误响应格式
- 统一响应基类：包含状态码与消息字段，便于前端统一处理。
- 分页响应：扩展统一基类，增加总数、页码与页大小字段。
- API 路由中的错误响应：在业务逻辑中抛出 HTTP 异常，由全局异常处理器统一记录与返回。
classDiagram
class ResponseBase {
+int code
+string message
}
class PaginatedResponse {
+int total
+int page
+int page_size
}
ResponseBase <|-- PaginatedResponse
图表来源
章节来源
- backend/app/schemas/schemas.py
- backend/app/api/v1/auth.py
- backend/app/api/v1/staff.py
- backend/app/api/v1/departments.py
- backend/app/api/v1/assessments.py
日志配置与输出格式
- 日志目录：自动创建 logs 目录，按日期生成日志文件。
- 输出目标：控制台 INFO 级别输出；应用日志文件 DEBUG 级别滚动保存；错误日志文件 ERROR 级别单独滚动保存。
- 格式：包含时间戳、记录器名称、级别与消息；日期格式统一。
flowchart TD
Init["初始化日志系统"] --> MakeDir["创建 logs 目录"]
MakeDir --> Paths["生成日期文件路径"]
Paths --> SetupConsole["配置控制台处理器(INFO)"]
Paths --> SetupAppFile["配置应用文件处理器(DEBUG)<br/>10MB 大小限制，保留7份"]
Paths --> SetupErrorFile["配置错误文件处理器(ERROR)<br/>10MB 大小限制，保留7份"]
SetupConsole --> GetLogger["提供子记录器"]
SetupAppFile --> GetLogger
SetupErrorFile --> GetLogger
GetLogger --> Ready["日志系统就绪"]
图表来源
章节来源
上下文信息捕获与性能监控集成
- 请求上下文：全局异常处理器记录请求方法与 URL，便于定位具体接口与参数。
- 堆栈信息：全局异常处理器开启堆栈打印，便于定位异常根因。
- 性能监控：建议在业务服务层埋点耗时指标，结合日志进行性能分析。
章节来源
安全日志与审计跟踪
- 认证与权限：在安全模块中对无效凭据、禁用用户、权限不足等情况抛出标准化异常，便于统一记录与审计。
- 审计建议：对关键操作（如创建、更新、删除）记录操作人、对象、变更前后摘要等信息，结合日志系统进行持久化与检索。
章节来源
日志轮转、文件管理与分析
- 轮转策略：单文件最大 10MB，保留最近 7 份备份，按日期命名，便于按天检索。
- 文件位置：应用日志与错误日志分别存放，便于区分与分析。
- 分析工具：建议配合系统日志采集工具（如 Filebeat/Fluent Bit）与可视化平台（如 ELK/Graylog）进行集中分析。
章节来源
依赖关系分析
- 应用入口依赖日志配置模块以初始化日志系统。
- API 路由依赖安全模块进行权限校验，异常统一由全局处理器处理。
- 业务服务层依赖数据库会话与模型，异常通过路由抛出。
- 统一响应结构由 Pydantic 模式定义，保证前后端契约一致。
graph LR
MAIN["main.py"] --> LOGCONF["logging_config.py"]
MAIN --> API_INIT["api/v1/__init__.py"]
API_INIT --> AUTH["auth.py"]
API_INIT --> STAFF["staff.py"]
API_INIT --> DEPT["departments.py"]
API_INIT --> ASSESS["assessments.py"]
AUTH --> SECURITY["security.py"]
STAFF --> SVC_STAFF["staff_service.py"]
DEPT --> SVC_DEPT["department_service.py"]
ASSESS --> SVC_STAFF
ASSESS --> SVC_DEPT
SVC_STAFF --> MODELS["models.py"]
SVC_DEPT --> MODELS
AUTH --> MODELS
STAFF --> MODELS
DEPT --> MODELS
ASSESS --> MODELS
SCHEMAS["schemas.py"] --> MODELS
图表来源
- backend/app/main.py
- backend/app/core/logging_config.py
- backend/app/api/v1/init.py
- backend/app/api/v1/auth.py
- backend/app/api/v1/staff.py
- backend/app/api/v1/departments.py
- backend/app/api/v1/assessments.py
- backend/app/core/security.py
- backend/app/services/staff_service.py
- backend/app/services/department_service.py
- backend/app/models/models.py
- backend/app/schemas/schemas.py
章节来源
性能考量
- 日志级别与频率：生产环境建议降低 DEBUG 级别日志量，仅在问题定位阶段临时提升。
- 文件轮转：合理设置单文件大小与备份数量，避免磁盘占用过高。
- 异常处理链路：尽量在业务层尽早捕获并抛出语义明确的 HTTP 异常，减少全局异常处理的开销。
- 监控指标：在关键业务路径埋点耗时与错误率，结合日志进行聚合分析。
故障排查指南
- 快速定位：查看全局异常处理器记录的请求方法与 URL，结合错误日志文件定位问题。
- 堆栈分析：全局异常处理器开启堆栈打印，便于定位异常根因。
- 常见错误：参考测试与修复文档中的常见错误与处理建议，定位前端与后端问题。
- 日志位置：应用日志与错误日志按日期命名，便于按天检索与分析。
章节来源
结论
通过在应用入口集中配置全局异常处理器与日志系统，结合统一的响应结构与安全模块的标准化异常抛出，本项目实现了清晰、可追踪且可维护的错误处理与日志体系。建议在生产环境中进一步完善性能监控埋点、日志采集与可视化分析，并强化安全审计与合规性检查，以满足医院绩效系统的高可靠运行需求。
附录
- 配置项参考：应用名称、版本、API 前缀、数据库连接、JWT 参数、跨域配置等。
- 模块职责：日志配置负责日志输出与轮转；安全模块负责认证与权限校验；API 路由负责业务编排与异常抛出；服务层负责业务逻辑与数据访问；模型与模式定义数据结构与约束。
章节来源