# 错误处理与日志

<cite>
**本文引用的文件**
- [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)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向“医院绩效系统”的后端工程团队，聚焦于错误处理与日志体系的设计与落地实践。内容涵盖：
- 全局异常处理机制与自定义异常类的使用
- 错误响应格式与统一返回结构
- 日志配置、日志级别、输出格式与轮转策略
- 结构化日志记录、上下文信息捕获与性能监控集成
- 错误追踪、堆栈信息收集与调试信息输出
- 日志轮转、文件管理与日志分析工具使用
- 生产环境日志监控、告警配置与故障诊断方法
- 安全日志记录、审计跟踪与合规性要求

## 项目结构
后端采用 FastAPI + SQLAlchemy 异步 ORM 的分层架构，错误处理与日志主要分布在应用入口、核心配置与日志模块中，并在各 API 路由中体现统一的异常抛出与响应格式。

```mermaid
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](file://backend/app/main.py#L15-L77)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)

## 核心组件
- 全局异常处理：在应用入口集中注册 HTTP 异常、请求验证异常与全局异常处理器，统一记录日志并向上抛出。
- 日志系统：集中配置控制台与文件输出，按级别分离，支持日志轮转与日期命名。
- 统一响应结构：在各 API 路由中返回统一的响应体结构，便于前端与监控系统解析。
- 安全与权限：在认证与权限校验中抛出标准化 HTTP 异常，确保错误语义清晰。

章节来源
- [backend/app/main.py](file://backend/app/main.py#L58-L74)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L26-L59)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L60)

## 架构总览
下图展示从请求进入应用到异常处理与日志记录的关键交互路径。

```mermaid
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](file://backend/app/main.py#L58-L74)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L68-L81)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L67-L80)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L80-L88)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L26-L59)

## 详细组件分析

### 全局异常处理机制
- HTTP 异常处理器：记录请求方法、URL、状态码与详情，便于快速定位资源访问问题。
- 请求验证异常处理器：记录请求与验证错误，便于前端与接口调试。
- 全局异常处理器：记录未知异常并打印堆栈信息，确保问题可追溯。

```mermaid
flowchart TD
Start(["请求进入"]) --> Route["路由匹配与依赖注入"]
Route --> CallSvc["调用业务服务"]
CallSvc --> SvcOK{"业务执行成功?"}
SvcOK --> |是| BuildResp["构造统一响应"]
SvcOK --> |否| ThrowHTTP["抛出 HTTP 异常"]
ThrowHTTP --> GlobalLog["全局异常处理器记录日志(含堆栈)"]
GlobalLog --> RaiseExc["向上抛出异常"]
BuildResp --> End(["返回响应"])
RaiseExc --> End
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L58-L74)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L58-L74)

### 自定义异常类与错误响应格式
- 统一响应基类：包含状态码与消息字段，便于前端统一处理。
- 分页响应：扩展统一基类，增加总数、页码与页大小字段。
- API 路由中的错误响应：在业务逻辑中抛出 HTTP 异常，由全局异常处理器统一记录与返回。

```mermaid
classDiagram
class ResponseBase {
+int code
+string message
}
class PaginatedResponse {
+int total
+int page
+int page_size
}
ResponseBase <|-- PaginatedResponse
```

图表来源
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L60)

章节来源
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L60)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L37)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L76-L81)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L74-L80)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L86-L88)

### 日志配置与输出格式
- 日志目录：自动创建 logs 目录，按日期生成日志文件。
- 输出目标：控制台 INFO 级别输出；应用日志文件 DEBUG 级别滚动保存；错误日志文件 ERROR 级别单独滚动保存。
- 格式：包含时间戳、记录器名称、级别与消息；日期格式统一。

```mermaid
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["日志系统就绪"]
```

图表来源
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L10-L64)

章节来源
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L10-L64)

### 上下文信息捕获与性能监控集成
- 请求上下文：全局异常处理器记录请求方法与 URL，便于定位具体接口与参数。
- 堆栈信息：全局异常处理器开启堆栈打印，便于定位异常根因。
- 性能监控：建议在业务服务层埋点耗时指标，结合日志进行性能分析。

章节来源
- [backend/app/main.py](file://backend/app/main.py#L60-L73)

### 安全日志与审计跟踪
- 认证与权限：在安全模块中对无效凭据、禁用用户、权限不足等情况抛出标准化异常，便于统一记录与审计。
- 审计建议：对关键操作（如创建、更新、删除）记录操作人、对象、变更前后摘要等信息，结合日志系统进行持久化与检索。

章节来源
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L109)

### 日志轮转、文件管理与分析
- 轮转策略：单文件最大 10MB，保留最近 7 份备份，按日期命名，便于按天检索。
- 文件位置：应用日志与错误日志分别存放，便于区分与分析。
- 分析工具：建议配合系统日志采集工具（如 Filebeat/Fluent Bit）与可视化平台（如 ELK/Graylog）进行集中分析。

章节来源
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L40-L59)
- [backend/FIX_SUMMARY.md](file://backend/FIX_SUMMARY.md#L121-L124)

## 依赖关系分析
- 应用入口依赖日志配置模块以初始化日志系统。
- API 路由依赖安全模块进行权限校验，异常统一由全局处理器处理。
- 业务服务层依赖数据库会话与模型，异常通过路由抛出。
- 统一响应结构由 Pydantic 模式定义，保证前后端契约一致。

```mermaid
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](file://backend/app/main.py#L1-L92)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)

## 性能考量
- 日志级别与频率：生产环境建议降低 DEBUG 级别日志量，仅在问题定位阶段临时提升。
- 文件轮转：合理设置单文件大小与备份数量，避免磁盘占用过高。
- 异常处理链路：尽量在业务层尽早捕获并抛出语义明确的 HTTP 异常，减少全局异常处理的开销。
- 监控指标：在关键业务路径埋点耗时与错误率，结合日志进行聚合分析。

## 故障排查指南
- 快速定位：查看全局异常处理器记录的请求方法与 URL，结合错误日志文件定位问题。
- 堆栈分析：全局异常处理器开启堆栈打印，便于定位异常根因。
- 常见错误：参考测试与修复文档中的常见错误与处理建议，定位前端与后端问题。
- 日志位置：应用日志与错误日志按日期命名，便于按天检索与分析。

章节来源
- [backend/app/main.py](file://backend/app/main.py#L60-L73)
- [backend/FIX_SUMMARY.md](file://backend/FIX_SUMMARY.md#L116-L124)

## 结论
通过在应用入口集中配置全局异常处理器与日志系统，结合统一的响应结构与安全模块的标准化异常抛出，本项目实现了清晰、可追踪且可维护的错误处理与日志体系。建议在生产环境中进一步完善性能监控埋点、日志采集与可视化分析，并强化安全审计与合规性检查，以满足医院绩效系统的高可靠运行需求。

## 附录
- 配置项参考：应用名称、版本、API 前缀、数据库连接、JWT 参数、跨域配置等。
- 模块职责：日志配置负责日志输出与轮转；安全模块负责认证与权限校验；API 路由负责业务编排与异常抛出；服务层负责业务逻辑与数据访问；模型与模式定义数据结构与约束。

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)