16 KiB
16 KiB
后端开发指南
**本文档引用的文件** - [main.py](file://backend/app/main.py) - [config.py](file://backend/app/core/config.py) - [database.py](file://backend/app/core/database.py) - [security.py](file://backend/app/core/security.py) - [logging_config.py](file://backend/app/core/logging_config.py) - [__init__.py](file://backend/app/api/v1/__init__.py) - [models.py](file://backend/app/models/models.py) - [schemas.py](file://backend/app/schemas/schemas.py) - [assessment_service.py](file://backend/app/services/assessment_service.py) - [staff_service.py](file://backend/app/services/staff_service.py) - [auth.py](file://backend/app/api/v1/auth.py) - [staff.py](file://backend/app/api/v1/staff.py) - [init_db.py](file://backend/init_db.py)目录
简介
本指南面向后端开发者，系统讲解医院绩效管理系统的FastAPI后端开发实践，涵盖：
- FastAPI框架使用与路由组织
- 数据模型设计与业务实体映射
- 服务层架构、依赖注入与异步编程
- API路由配置、错误处理与日志规范
- 业务服务开发、数据验证与安全控制
- 数据库连接管理、事务处理与性能优化
- 单元测试与集成测试设计、代码质量保证
项目结构
后端采用分层架构：入口应用层、核心配置与基础设施层、数据模型与Schema层、服务层、API路由层。整体结构清晰，职责分离明确。
graph TB
subgraph "应用入口"
MAIN["main.py"]
end
subgraph "核心配置与基础设施"
CFG["config.py"]
DB["database.py"]
SEC["security.py"]
LOG["logging_config.py"]
end
subgraph "数据与接口定义"
MODELS["models.py"]
SCHEMAS["schemas.py"]
end
subgraph "服务层"
SVC_ASSESS["assessment_service.py"]
SVC_STAFF["staff_service.py"]
end
subgraph "API路由"
API_V1["api/v1/__init__.py"]
AUTH["api/v1/auth.py"]
STAFF["api/v1/staff.py"]
end
MAIN --> API_V1
API_V1 --> AUTH
API_V1 --> STAFF
AUTH --> SEC
STAFF --> SVC_STAFF
SVC_STAFF --> MODELS
SVC_ASSESS --> MODELS
SEC --> DB
DB --> MODELS
MODELS --> SCHEMAS
图表来源
- main.py
- config.py
- database.py
- security.py
- logging_config.py
- models.py
- schemas.py
- assessment_service.py
- staff_service.py
- init.py
- auth.py
- staff.py
章节来源
核心组件
- 应用实例与中间件：创建FastAPI实例、CORS跨域、健康检查端点、全局异常处理器。
- 配置中心：应用名、版本、API前缀、数据库连接池、JWT密钥与过期时间、CORS白名单、分页参数等。
- 数据库层：异步SQLAlchemy引擎、会话工厂、模型基类、依赖注入式会话获取与自动事务提交/回滚。
- 安全模块：OAuth2密码流、密码哈希与校验、JWT签发与解析、当前用户解析与权限校验（管理员/经理/激活用户）。
- 日志模块：控制台与文件（按日滚动）双通道，错误级别单独文件，统一格式化输出。
- 数据模型与Schema：涵盖科室、员工、指标、考核、明细、工资、用户、计划、菜单、模板等实体与枚举。
- 服务层：封装业务逻辑，如员工管理、考核流程（草稿/提交/审核/确认）、批量创建等。
- API路由：认证、员工管理等模块化路由，统一返回结构与权限控制。
章节来源
- main.py
- config.py
- database.py
- security.py
- logging_config.py
- models.py
- schemas.py
- assessment_service.py
- staff_service.py
架构总览
系统采用“路由层-服务层-数据层”的三层架构，配合依赖注入与异步IO，确保高并发下的稳定与性能。
graph TB
CLIENT["客户端"] --> ROUTER["API路由层<br/>auth.py / staff.py"]
ROUTER --> DEP_DB["依赖注入: get_db()"]
ROUTER --> DEP_SEC["依赖注入: 当前用户/权限"]
ROUTER --> SVC["服务层<br/>staff_service.py / assessment_service.py"]
SVC --> MODEL["数据模型层<br/>models.py"]
MODEL --> DB["数据库引擎<br/>database.py"]
ROUTER --> LOG["日志记录<br/>logging_config.py"]
ROUTER --> CFG["配置中心<br/>config.py"]
图表来源
详细组件分析
FastAPI应用与路由组织
- 应用创建：设置标题、版本、OpenAPI文档路径、CORS策略、健康检查端点。
- 异常处理：HTTP异常、请求验证异常、全局异常，均记录日志并抛出。
- 路由注册：v1路由聚合器统一include各模块路由。
sequenceDiagram
participant Client as "客户端"
participant App as "FastAPI应用"
participant Router as "API路由"
participant Service as "服务层"
participant DB as "数据库"
Client->>App : 请求 /api/v1/staff
App->>Router : 分发到 staff.py
Router->>Service : 调用 StaffService
Service->>DB : 查询/写入
DB-->>Service : 返回结果
Service-->>Router : 业务结果
Router-->>Client : 统一响应结构
图表来源
章节来源
数据模型设计与业务实体
- 实体覆盖：科室、员工、指标、考核、明细、工资、用户、计划、菜单、模板等。
- 枚举类型：科室类型、平衡计分卡维度、员工状态、考核状态、指标类型、计划层级/状态、菜单类型、模板类型等。
- 约束与索引：权重正数约束、多字段索引、唯一组合索引等，提升查询效率与数据一致性。
- 关系映射：一对多/多对多、外键约束、级联删除等，确保业务完整性。
erDiagram
DEPARTMENTS ||--o{ STAFF : "拥有"
STAFF ||--o{ ASSESSMENTS : "被考核"
STAFF ||--o{ SALARY_RECORDS : "薪资记录"
INDICATORS ||--o{ ASSESSMENT_DETAILS : "被用于"
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : "关联指标"
INDICATORS ||--o{ PLAN_KPI_RELATIONS : "被关联"
USERS ||--o{ ASSESSMENTS : "审核/复核"
图表来源
章节来源
Schema与数据验证
- Pydantic模型：统一定义请求/响应结构，内置字段长度、范围、枚举校验。
- 通用响应：统一code/message结构；分页响应包含总数、页码、页大小。
- 类型安全：枚举类型与数据库枚举保持一致，避免非法值进入数据库。
章节来源
服务层架构与依赖注入
- 服务类：以静态方法封装业务逻辑，便于测试与复用。
- 依赖注入：通过AsyncSession注入数据库会话；通过Depends注入当前用户与权限。
- 异步编程：所有数据库操作使用异步IO，提高并发吞吐。
classDiagram
class StaffService {
+get_list(db, department_id, status, keyword, page, page_size)
+get_by_id(db, staff_id)
+get_by_employee_id(db, employee_id)
+create(db, staff_data)
+update(db, staff_id, staff_data)
+delete(db, staff_id)
+get_by_department(db, department_id)
}
class AssessmentService {
+get_list(db, staff_id, department_id, period_year, period_month, status, page, page_size)
+get_by_id(db, assessment_id)
+create(db, assessment_data, assessor_id)
+update(db, assessment_id, assessment_data)
+submit(db, assessment_id)
+review(db, assessment_id, reviewer_id, approved, remark)
+finalize(db, assessment_id)
+batch_create_for_department(db, department_id, period_year, period_month, indicators)
}
class Assessment {
+total_score
+weighted_score
+status
}
StaffService --> Assessment : "关联"
AssessmentService --> Assessment : "管理"
图表来源
章节来源
安全与认证
- OAuth2密码模式：tokenUrl指向登录接口。
- 密码处理：bcrypt哈希与校验。
- JWT：签发含过期时间，解析校验失败则拒绝。
- 权限控制：当前用户、激活用户、管理员、经理权限装饰器。
sequenceDiagram
participant Client as "客户端"
participant Auth as "认证路由"
participant DB as "数据库"
participant Sec as "安全模块"
Client->>Auth : POST /api/v1/auth/login
Auth->>DB : 查询用户
DB-->>Auth : 用户对象
Auth->>Sec : 校验密码
Sec-->>Auth : 校验结果
Auth->>Sec : 生成JWT
Sec-->>Auth : access_token
Auth-->>Client : Token
图表来源
章节来源
数据库连接管理与事务
- 异步引擎：基于asyncpg驱动，支持连接池配置。
- 会话工厂：AsyncSession，expire_on_commit=False减少刷新开销。
- 依赖注入：get_db提供上下文生命周期的会话，自动commit/rollback/关闭。
- 事务语义：异常时回滚，finally确保关闭，避免资源泄漏。
flowchart TD
Start(["获取会话"]) --> Exec["执行数据库操作"]
Exec --> Success{"是否异常?"}
Success --> |否| Commit["提交事务"]
Success --> |是| Rollback["回滚事务"]
Commit --> Close["关闭会话"]
Rollback --> Close
Close --> End(["结束"])
图表来源
章节来源
API路由配置与统一响应
- 路由前缀：/api/v1，统一文档路径。
- 权限装饰器：仅管理员/经理可创建/更新/删除敏感资源。
- 统一响应：code/message/data/分页字段，便于前端处理。
章节来源
错误处理与日志记录
- 异常处理：HTTP异常、请求验证异常、全局异常，均记录日志并向上抛出。
- 日志策略：控制台INFO级别、文件DEBUG级别、错误单独ERROR文件，按日滚动。
- 日志获取：统一logger与子logger getChild，便于模块化追踪。
章节来源
依赖关系分析
- 路由层依赖服务层与安全模块；服务层依赖数据模型与数据库会话；安全模块依赖配置与数据库；日志模块独立但被路由层使用。
- 低耦合高内聚：每个模块职责单一，通过依赖注入解耦。
graph LR
AUTH["auth.py"] --> SEC["security.py"]
AUTH --> SVC_STAFF["staff_service.py"]
STAFF["staff.py"] --> SVC_STAFF
SVC_STAFF --> MODELS["models.py"]
SVC_ASSESS["assessment_service.py"] --> MODELS
SEC --> DB["database.py"]
DB --> MODELS
MAIN["main.py"] --> API_V1["api/v1/__init__.py"]
API_V1 --> AUTH
API_V1 --> STAFF
MAIN --> LOG["logging_config.py"]
MAIN --> CFG["config.py"]
图表来源
- auth.py
- staff.py
- staff_service.py
- assessment_service.py
- security.py
- database.py
- models.py
- main.py
- init.py
- logging_config.py
- config.py
章节来源
性能考虑
- 异步IO：使用SQLAlchemy 2.0异步引擎与AsyncSession，提升并发能力。
- 连接池：通过配置项设置池大小与溢出，平衡内存与并发。
- 查询优化：合理使用selectinload预加载关联，避免N+1问题；为高频查询字段添加索引。
- 缓存策略：可结合Redis缓存热点数据（如字典、模板），降低数据库压力。
- 分页与限制：默认分页大小与最大分页限制，防止大查询导致阻塞。
- 日志级别：生产环境建议调整日志级别，减少磁盘IO与CPU消耗。
[本节为通用指导，无需列出具体文件来源]
故障排除指南
- 登录失败：检查用户名是否存在、密码是否正确、账户是否激活。
- 权限不足：确认当前用户角色（admin/manager/staff），以及是否处于激活状态。
- 数据库连接异常：检查DATABASE_URL、连接池配置、PostgreSQL服务状态。
- 事务未提交：确认服务层调用await db.flush()/commit()，异常时自动回滚。
- 日志排查：查看应用日志与错误日志，定位异常堆栈与请求上下文。
章节来源
结论
本指南梳理了医院绩效系统后端的架构与实现要点，强调了FastAPI的异步特性、依赖注入、安全认证与日志体系。通过清晰的分层与严格的Schema验证，系统具备良好的扩展性与可维护性。建议在后续迭代中完善单元测试与集成测试，持续优化查询与缓存策略，确保系统在高并发场景下的稳定性与性能。
[本节为总结性内容，无需列出具体文件来源]
附录
开发与运行指引
- 初始化数据库：运行数据库初始化脚本，创建表并插入测试数据。
- 启动应用：使用uvicorn启动FastAPI应用，默认监听0.0.0.0:8000。
- 访问文档：/api/v1/docs 或 /api/v1/redoc。
章节来源