# nzh-fastapi

**Repository Path**: nzh1992/nzh-fastapi

## Basic Information

- **Project Name**: nzh-fastapi
- **Description**: 封装一套基于fastapi的后台框架
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-27
- **Last Updated**: 2025-12-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 1.描述
基于FastAPI开发的后台框架


# 2.安装步骤
### 2.1 安装python依赖包
```
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
```

### 2.2 安装alembic
##### 2.2.1 初始化alembic
```
alembic init alembic
```

##### 2.2.2 修改alembic.ini中数据库连接配置
```
sqlalchemy.url = mysql+pymysql://root:123456@localhost:3306/nzh-fastapi?charset=utf8mb4
```

##### 2.2.3 修改alembic/env.py
```
# target_metadata = None
from app.db import Base
target_metadata = Base.metadata
```

##### 2.2.4 生成数据库迁移文件
```
alembic revision --autogenerate -m "update_{count}"
```

##### 2.2.5 执行数据库迁移
```
alembic upgrade head
```

# 3.多环境配置
项目支持多环境配置，可以根据需要切换不同的环境：

### 3.1 环境配置文件
- `.env.development` - 开发环境配置
- `.env.testing` - 测试环境配置  
- `.env.production` - 生产环境配置
- `.env` - 当前使用的配置（通过切换工具自动生成）

### 3.2 环境切换方法

#### 方法1：使用环境管理工具（推荐）
```bash
# 查看所有可用环境
python env_manager.py list

# 切换到开发环境
python env_manager.py switch development

# 切换到测试环境
python env_manager.py switch testing

# 切换到生产环境
python env_manager.py switch production

# 查看当前配置
python env_manager.py show

# 对比两个环境的配置
python env_manager.py compare development production

# 验证环境配置
python env_manager.py validate development
```

#### 方法2：使用简易切换脚本
```bash
# 切换到开发环境
python switch_env.py development

# 切换到测试环境
python switch_env.py testing

# 切换到生产环境
python switch_env.py production
```

#### 方法3：直接设置环境变量
```bash
# Windows
set ENV=development

# Linux/Mac
export ENV=development
```

### 3.3 各环境特点

| 环境 | 调试模式 | 日志级别 | 数据库 | 特点 |
|------|----------|----------|---------|------|
| development | 开启 | DEBUG | nzh-fastapi-dev | 详细的调试信息，便于开发 |
| testing | 关闭 | INFO | nzh-fastapi-test | 适中的日志，用于测试 |
| production | 关闭 | WARNING | nzh-fastapi-prod | 最少日志，性能优化 |

# 4.项目结构
```
nzh-fastapi/
├── app/                          # 主要应用代码
│   ├── api/                      # API路由
│   │   ├── auth.py               # 认证相关接口
│   │   └── user.py               # 用户相关接口
│   ├── core/                     # 核心配置
│   │   ├── config.py             # 配置管理
│   │   └── security.py           # 安全配置
│   ├── db/                       # 数据库相关
│   │   └── session.py            # 数据库会话管理
│   ├── deps/                     # 依赖注入
│   │   ├── db.py                 # 数据库依赖
│   │   └── login.py              # 登录依赖
│   ├── exceptions/               # 异常处理
│   │   ├── auth.py               # 认证异常
│   │   └── base.py               # 基础异常
│   ├── models/                   # 数据模型
│   │   ├── base.py               # 基础模型
│   │   ├── data_dict.py          # 数据字典模型
│   │   └── user.py               # 用户模型
│   ├── schemas/                  # 数据验证模式
│   │   ├── auth.py               # 认证模式
│   │   └── user.py               # 用户模式
│   ├── service/                  # 业务逻辑层
│   │   ├── auth.py               # 认证服务
│   │   └── user.py               # 用户服务
│   ├── utils/                    # 工具函数
│   │   ├── check.py              # 检查工具
│   │   ├── log.py                # 日志工具
│   │   ├── password.py           # 密码工具
│   │   └── response.py           # 响应工具
│   └── main.py                   # 应用主文件
├── alembic/                      # 数据库迁移
├── update/                       # 更新脚本
├── .env                          # 环境变量配置
├── alembic.ini                   # Alembic配置
└── requirements.txt              # 项目依赖
```

# 4.技术栈
- **Python 3.12**: 编程语言
- **FastAPI**: Web框架
- **SQLAlchemy**: ORM框架
- **Alembic**: 数据库迁移工具
- **Pydantic**: 数据验证
- **Uvicorn**: ASGI服务器
- **loguru**: 日志记录
- **PyJWT**: JWT认证
- **bcrypt**: 密码加密

# 5.开发规范
- 采用分层架构：API层、Service层、Model层
- 使用Pydantic进行数据验证
- 使用SQLAlchemy进行数据库操作
- 使用Alembic管理数据库迁移
- 使用loguru记录日志
- 使用JWT进行用户认证
- 使用bcrypt进行密码加密

# 6.启动项目
### 6.1 激活虚拟环境
```bash
# Windows
.venv\Scripts\activate

# macOS/Linux
source venv/bin/activate
```

### 6.3 选择环境（重要）
在启动服务前，请先选择要使用的环境：
```bash
# 切换到开发环境（默认）
python env_manager.py switch development

# 或者切换到测试环境
python env_manager.py switch testing

# 或者切换到生产环境
python env_manager.py switch production
```

### 6.4 执行数据库迁移
```bash
# 根据当前环境生成迁移文件
alembic revision --autogenerate -m "update_{count}"

# 执行数据库迁移
alembic upgrade head
```

### 6.5 启动服务
```bash
# 开发环境启动（带热重载）
uvicorn app.main:app --reload

# 或者按照项目规则启动
uvicorn app.main:app --host 0.0.0.0 --port 7000 --reload
```

### 6.6 访问API文档
启动后访问：http://localhost:7000/docs

# 7.环境变量配置
项目使用多环境配置，主要环境变量配置在各环境的`.env.{environment}`文件中：

### 7.1 基本配置
- `APP_NAME`: 应用名称
- `APP_TITLE`: 应用标题  
- `APP_VERSION`: 应用版本
- `APP_DESCRIPTION`: 应用描述

### 7.2 系统配置
- `DEBUG`: 调试模式 (true/false)
- `LOG_LEVEL`: 日志级别 (DEBUG/INFO/WARNING/ERROR)
- `LOG_COLORIZE`: 日志颜色化 (true/false)

### 7.3 数据库配置
- `DB_HOST`: 数据库主机地址
- `DB_PORT`: 数据库端口
- `DB_USER`: 数据库用户名
- `DB_PASSWORD`: 数据库密码
- `DB_NAME`: 数据库名称
- `DB_CHARSET`: 数据库字符集
- `DB_POOL_SIZE`: 数据库连接池大小
- `DB_ECHO`: SQL语句回显 (true/false)

### 7.4 环境变量优先级
1. 系统环境变量（最高优先级）
2. 当前`.env`文件中的配置
3. 默认`.env.development`文件中的配置（最低优先级）

# 8.注意事项
- 确保已安装Python 3.12
- 确保已创建并激活虚拟环境
- **重要：启动前务必选择正确的环境配置**
- 确保数据库配置正确
- 启动前务必执行数据库迁移
- 开发模式下使用`--reload`参数

# 9.多环境配置使用建议

### 9.1 开发环境（development）
- 开启调试模式，便于调试
- 使用DEBUG级别日志，详细信息
- 数据库使用开发库，避免影响其他环境
- 启用SQL回显，方便查看SQL执行情况

### 9.2 测试环境（testing）
- 关闭调试模式，模拟生产环境
- 使用INFO级别日志，适中的信息量
- 使用独立的测试数据库
- 关闭SQL回显，提高性能

### 9.3 生产环境（production）
- 关闭调试模式，确保安全性
- 使用WARNING级别日志，减少日志量
- 使用生产数据库，确保数据安全
- 关闭日志颜色化，避免日志文件污染

### 9.4 最佳实践
1. **开发阶段**：使用development环境，便于调试和开发
2. **测试阶段**：切换到testing环境，进行功能测试
3. **部署阶段**：切换到production环境，确保系统稳定性
4. **环境隔离**：不同环境使用不同的数据库，避免数据冲突
5. **配置管理**：使用版本控制管理环境配置文件