13 KiB
13 KiB
开发环境搭建
**本文档引用的文件** - [backend/.env.example](file://backend/.env.example) - [backend/requirements.txt](file://backend/requirements.txt) - [backend/alembic.ini](file://backend/alembic.ini) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/app/main.py](file://backend/app/main.py) - [backend/app/core/database.py](file://backend/app/core/database.py) - [backend/init_db.py](file://backend/init_db.py) - [backend/app/core/init_db.py](file://backend/app/core/init_db.py) - [backend/create_menu_tables.py](file://backend/create_menu_tables.py) - [backend/create_plan_tables.py](file://backend/create_plan_tables.py) - [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py) - [backend/migrate_indicators.py](file://backend/migrate_indicators.py) - [backend/test_api.py](file://backend/test_api.py) - [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py)目录
简介
本指南面向医院绩效系统后端开发团队，提供从零搭建开发环境的完整流程。内容涵盖Python环境要求、虚拟环境创建与依赖安装、环境变量与数据库配置、API配置参数、本地开发服务器启动与热重载、数据库初始化与迁移脚本执行、测试数据准备、IDE配置建议以及常见问题排查。
项目结构
后端采用FastAPI + SQLAlchemy 2.0 + 异步数据库连接的现代Python架构，主要目录与职责如下：
- app：核心业务逻辑，包含API路由、核心配置、数据库连接、服务层、模型与工具
- alembic：数据库迁移脚本与配置
- tests：测试用例（当前为空或未启用）
- scripts：初始化脚本与工具脚本
- 根目录：环境变量、依赖清单、迁移配置与数据库文件
graph TB
subgraph "后端根目录"
ENV[".env 环境变量"]
REQ["requirements.txt 依赖"]
ALEMBICINI["alembic.ini 迁移配置"]
DBFILE["hospital_performance.db SQLite 文件"]
end
subgraph "应用核心(app)"
MAIN["app/main.py 应用入口"]
CONFIG["app/core/config.py 配置"]
DB["app/core/database.py 数据库连接"]
MODELS["app/models/* 模型定义"]
SERVICES["app/services/* 服务层"]
APIS["app/api/v1/* API路由"]
SCRIPTS["app/scripts/* 初始化脚本"]
end
subgraph "迁移(alembic)"
ALEMBICENV["alembic/env.py 环境配置"]
VERSIONS["alembic/versions/* 迁移版本"]
end
ENV --> CONFIG
REQ --> MAIN
ALEMBICINI --> ALEMBICENV
CONFIG --> DB
DB --> MODELS
MAIN --> APIS
SCRIPTS --> MODELS
图表来源
章节来源
核心组件
- 应用入口与路由注册：负责创建FastAPI实例、配置CORS、注册路由前缀、健康检查与全局异常处理
- 配置模块：集中管理应用名称、版本、调试模式、API前缀、数据库连接、JWT密钥与算法、跨域来源、分页参数等
- 数据库连接：基于SQLAlchemy 2.0异步引擎与会话工厂，支持调试模式下的SQL回显
- 迁移配置：Alembic配置文件，指定迁移脚本位置、路径前缀与SQLAlchemy URL
章节来源
架构概览
后端采用分层架构，核心交互流程如下：
sequenceDiagram
participant Dev as "开发者"
participant Uvicorn as "Uvicorn 服务器"
participant FastAPI as "FastAPI 应用"
participant Router as "API 路由"
participant Service as "业务服务"
participant DB as "数据库"
Dev->>Uvicorn : 启动开发服务器(热重载)
Uvicorn->>FastAPI : 加载应用实例
FastAPI->>Router : 注册路由前缀 /api/v1
Dev->>FastAPI : 请求 /api/v1/health
FastAPI->>Router : 转发健康检查
Router->>FastAPI : 返回健康状态
FastAPI-->>Dev : 200 OK
Dev->>FastAPI : 认证请求
FastAPI->>Service : 调用认证服务
Service->>DB : 查询用户信息
DB-->>Service : 用户数据
Service-->>FastAPI : 认证结果
FastAPI-->>Dev : 返回访问令牌
图表来源
章节来源
详细组件分析
Python环境与依赖安装
- Python版本：推荐使用Python 3.10及以上版本
- 虚拟环境：建议使用venv创建隔离环境
- 依赖安装：通过requirements.txt安装所有后端依赖
- 开发服务器：使用uvicorn标准变体运行FastAPI应用
flowchart TD
Start(["开始"]) --> CreateEnv["创建虚拟环境"]
CreateEnv --> ActivateEnv["激活虚拟环境"]
ActivateEnv --> InstallDeps["安装依赖 requirements.txt"]
InstallDeps --> VerifyDeps{"依赖安装完成？"}
VerifyDeps --> |是| SetupEnv["配置环境变量 .env"]
VerifyDeps --> |否| FixDeps["检查并修复依赖问题"]
FixDeps --> InstallDeps
SetupEnv --> Ready["开发环境就绪"]
Ready --> End(["结束"])
图表来源
章节来源
环境变量与数据库配置
- 环境变量文件：.env.example提供了数据库URL、JWT密钥与调试开关的示例
- 数据库连接：默认使用PostgreSQL异步驱动，可通过DATABASE_URL覆盖
- Alembic配置：迁移脚本默认指向SQLite文件，便于本地开发与测试
- 配置优先级：应用配置从.env读取，同时支持运行时覆盖
flowchart TD
EnvFile[".env.example 示例"] --> LoadEnv["加载环境变量"]
LoadEnv --> ConfigClass["Settings 类解析"]
ConfigClass --> DBURL["DATABASE_URL"]
ConfigClass --> JWT["JWT 密钥/算法"]
ConfigClass --> Debug["DEBUG 调试模式"]
DBURL --> Engine["异步引擎创建"]
Engine --> Session["会话工厂"]
Session --> App["应用使用"]
图表来源
章节来源
API配置参数
- 应用名称与版本：用于OpenAPI文档展示
- API前缀：统一为/api/v1，便于版本管理
- CORS来源：允许前端开发服务器跨域访问
- 分页参数：默认每页条数与最大限制
- 异常处理：HTTP异常、请求验证异常与全局异常的统一处理
章节来源
本地开发服务器启动与热重载
- 启动命令：直接运行app/main.py，使用uvicorn标准变体
- 热重载：reload=True启用自动重启
- 主机与端口：默认监听0.0.0.0:8000
- 日志级别：info级别输出运行日志
sequenceDiagram
participant Dev as "开发者"
participant Python as "Python 解释器"
participant Uvicorn as "Uvicorn"
participant App as "FastAPI 应用"
Dev->>Python : python app/main.py
Python->>Uvicorn : 启动服务器(主机=0.0.0.0, 端口=8000, 热重载)
Uvicorn->>App : 加载应用实例
App-->>Uvicorn : 应用就绪
Uvicorn-->>Dev : 服务器启动完成
图表来源
章节来源
数据库初始化与迁移脚本
- 初始表创建：init_db.py与app/core/init_db.py分别提供不同初始化策略
- 菜单与计划表：create_menu_tables.py与create_plan_tables.py按需创建专用表
- 指标模板：init_indicator_templates.py批量导入平衡计分卡指标模板
- 迁移字段：migrate_indicators.py为现有指标表添加BS维度等新字段
- Alembic迁移：alembic.ini配置迁移脚本位置与SQLAlchemy URL
flowchart TD
InitStart["开始初始化"] --> CheckTables["检查表是否存在"]
CheckTables --> |不存在| CreateTable["创建基础表"]
CheckTables --> |存在| SkipInit["跳过初始化"]
CreateTable --> InsertData["插入测试/示例数据"]
InsertData --> InitComplete["初始化完成"]
SkipInit --> InitComplete
图表来源
章节来源
- backend/init_db.py
- backend/app/core/init_db.py
- backend/create_menu_tables.py
- backend/create_plan_tables.py
- backend/init_indicator_templates.py
- backend/migrate_indicators.py
- backend/alembic.ini
测试数据准备与API验证
- 登录测试：使用test_api.py模拟登录与获取模板数据
- 默认账户：admin/admin123用于快速验证接口
- 接口验证：通过健康检查与模板查询确认服务可用性
章节来源
IDE配置与代码规范
- Python版本：建议使用Python 3.10+
- 虚拟环境：使用venv创建独立环境
- 依赖管理：通过requirements.txt安装
- 代码格式化：建议使用Black或autopep8
- Linting：使用flake8或ruff
- IDE插件：启用Python语言服务器与格式化工具
依赖关系分析
后端依赖关系清晰，核心模块间耦合度低，便于维护与扩展：
graph LR
FastAPI["FastAPI 应用"] --> Config["配置模块"]
FastAPI --> Router["API 路由"]
Config --> DB["数据库连接"]
DB --> Models["ORM 模型"]
Router --> Services["业务服务"]
Services --> DB
Scripts["初始化脚本"] --> DB
Alembic["Alembic 迁移"] --> DB
图表来源
章节来源
性能考虑
- 异步数据库：使用SQLAlchemy异步引擎提升并发性能
- 连接池：通过配置数据库连接池大小与溢出数量控制资源使用
- 调试模式：仅在开发环境开启DEBUG，生产环境关闭以减少日志开销
- CORS范围：限制允许的来源与方法，避免不必要的跨域请求
故障排除指南
- 数据库连接失败
- 检查DATABASE_URL格式与凭据
- 确认PostgreSQL服务运行状态
- 如需SQLite，请调整Alembic配置与应用配置
- 端口被占用
- 修改app/main.py中的端口或停止占用进程
- 热重载无效
- 确认reload=True且文件保存
- 检查虚拟环境中uvicorn安装
- 权限错误
- 使用虚拟环境并确保pip安装权限
- Alembic迁移问题
- 检查alembic.ini中的SQLAlchemy URL
- 清理历史迁移并重新生成版本
章节来源
结论
通过本指南，您可以快速搭建医院绩效系统后端开发环境。建议严格遵循环境变量配置、数据库初始化与迁移脚本执行流程，并在开发过程中充分利用热重载与日志功能。遇到问题时，可依据故障排除指南逐项排查。
附录
- 快速检查清单
- Python 3.10+ 已安装
- 虚拟环境已创建并激活
- requirements.txt 依赖安装完成
- .env 环境变量配置正确
- 数据库服务运行正常
- 应用健康检查返回200
- 初始化脚本执行成功