# TurboSkeleton

**Repository Path**: hailongchen/fastapi_webframework

## Basic Information

- **Project Name**: TurboSkeleton
- **Description**: 基于FastAPI+SQLAlchemy+Hypercon以分层设计实现的Web基础开发框架
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-05
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Turbo Skeleton
> FastAPI Web Framework

一个基于 FastAPI 的企业级 Web 应用基础开发异步框架，提供了基本完整的后端服务解决方案，
包括路由自动发现、ORM数据模型自动注册、统一返回码处理、统一异常处理、请求日志记录等功能。

## 🚀 特性

- 路由自动发现与注册
- 模型自动发现与注册
- 统一的异常处理机制
- 统一返回码设计
- 双日志分离设计（应用日志与服务器日志）
- 标准化的响应格式
- 数据库连接池管理（原生 or [推荐]异步）
- 多层架构设计（Controller/Service/Repository）

## 📁 项目结构

```
fastapi_webframework/
├── fastapi_webframework/           # 主应用包
│   ├── common/                     # 公共模块
│   │   ├── response.py             # 统一响应格式
│   │   └── response_code.py        # controller层业务响应状态码定义
│   ├── core/                       # 核心模块
│   │   ├── config.py               # 配置文件管理(兜底.env)
│   │   ├── dbutils_rawsql.py       # 数据库池化管理(DButils操作原生SQL)
│   │   ├── async_orm.py            # 异步数据库会话管理(aiomysql)
│   │   ├── db_init.py              # 数据库连接验证和表初始化
│   │   ├── exceptions.py           # Service层的返回码字典
│   │   ├── intercepter.py          # 自定义中间件-请求拦截器，自动记录业务级别请求与响应的信息
│   │   ├── log_utils.py            # 日志工具，确保服务器日志路径存在
│   │   ├── model_discovery.py      # 模型自动发现与注册
│   │   ├── router_auto_discover.py # 路由自动发现
│   │   └── exception_handler.py    # 全局异常处理注册
│   ├── models/                     # 数据模型(DO)
│   │   └── user/                   # 用户模型
│   ├── repositories/               # 数据访问层(DAO)
│   │   └── user_repo.py            # 用户数据访问
│   ├── api/                        # API层
│   │   └── user/                   # 用户模块路由
│   ├── schemas/                    # 前台数据模型-数据传输对象(DTO)
│   │   └── user.py                 # 用户DTO
│   ├── services/                   # 业务逻辑层(Service)
│   │   └── user_service.py         # 用户业务逻辑
│   ├── tasks/                      # 业务处理脚本包
│   │                                # 用于存放业务相关的脚本文件，如数据预处理、批量任务处理等
│   └── utils/                      # 工具类
│       ├── logger.py               # 日志管理(应用日志)
│       ├── converter.py            # 类型转换
│       ├── security.py             # token编解码与密码加密
│       ├── verify_password.py      # 工具-密码hash校验（冗余的）
│       └── tools.py                # 工具函数
├── migrations/                     # 数据库迁移目录(Alembic)
│   └── alembic.ini                 # Alembic配置文件
├── main.py                         # 项目入口
├── cli.py                          # CLI命令工具
├── scripts/                        # 程序启动脚本
│   ├── start_dev.py                # 开发环境启动脚本
│   ├── start_local.py              # 本地环境启动脚本
│   └── start_production.py         # 生产环境启动脚本
├── tests/                          # 测试用例目录
│   ├── testcases/                  # 测试用例实现
│   │   ├── api/                    # API测试
│   │   │   └── user/               # 用户API测试
│   │   ├── repositories/           # 数据访问层测试
│   │   ├── services/               # 业务逻辑层测试
│   │   └── utils/                  # 工具类测试
│   ├── __init__.py                 # 测试包初始化
│   └── conftest.py                 # 测试夹具配置
├── .env.example                    # .env 环境变量示例文件
├── pyproject.toml                  # 项目依赖
├── setup.py                        # 项目安装配置
├── uv.lock                         # 依赖锁文件
├── Dockerfile                      # Docker镜像构建文件
├── docker-compose.yml              # Docker容器编排配置
├── entrypoint.sh                   # Docker容器启动脚本
├── DEPLOYMENT.md                   # 部署文档
└── README.md                       # 项目文档
```
## 📊 分层调用关系（核心流程）
```text
客户端请求 → api 接收请求(参数<=schemas) 
→ 调用 service 处理业务 
→ service 调用 repository 操作数据库 
→ repository 操作 models 对应的数据库表 
→ 结果通过 schemas 格式化后返回客户端。
```

## 🛠️ 安装

1. 克隆项目
```bash
git clone https://gitee.com/hailongchen/fastapi_webframework.git
cd fastapi_webframework
```

2. 安装依赖（注意激活虚拟运行环境）
```bash
uv sync
```

3. 配置环境变量
```bash
cp .env.example .env
# 编辑 .env 文件，填入必要的配置信息
```

## 📖 使用说明

### 启动服务

本项目提供多种启动方式，包括直接启动、脚本启动和CLI命令启动，以适应不同的开发和部署场景。

#### 1. 直接启动（基础方式）

**本地开发环境：**
```bash
python main.py
```

**生产环境：**
```bash
# uvicorn
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 --log-level info

# hypercorn
hypercorn main:app --bind 0.0.0.0:8000 --workers 4 --access-log ./logs/access.log --error-log ./logs/error.log --log-level info
```

#### 2. 进程管理

在生产环境使用多进程启动后，可以使用以下命令管理进程：

##### 2.1 查询运行中的进程

**Windows：**
```bash
# 查询uvicorn进程
tasklist | findstr "uvicorn"

# 查询hypercorn进程
tasklist | findstr "hypercorn"
```

**Linux/Mac：**
```bash
# 查询uvicorn进程
ps aux | grep "uvicorn"

# 查询hypercorn进程
ps aux | grep "hypercorn"
```

##### 2.2 停止进程

**Windows：**
```bash
# 停止所有uvicorn进程
taskkill /F /IM uvicorn.exe

# 停止所有hypercorn进程
taskkill /F /IM hypercorn.exe

# 或者根据PID停止特定进程
taskkill /F /PID <进程ID>
```

**Linux/Mac：**
```bash
# 停止所有uvicorn进程
pkill -f uvicorn

# 停止所有hypercorn进程
pkill -f hypercorn

# 或者根据PID停止特定进程
kill -9 <进程ID>
```

#### 3. 脚本启动（快捷方式）

项目提供了环境专用的启动脚本，位于`scripts/`目录下：

**开发环境：**
```bash
python scripts/start_dev.py
```

**本地环境：**
```bash
python scripts/start_local.py
```

**生产环境：**
```bash
python scripts/start_production.py
```

#### 4. 直接命令启动（推荐方式）

项目已配置直接启动命令，安装后可直接使用：

**开发环境：**
```bash
start-dev
```

**本地环境：**
```bash
start-local
```

**生产环境：**
```bash
start-production
```

#### 5. CLI命令启动

项目提供了功能完整的CLI命令工具，支持多种环境启动：

**启动本地环境（默认）：**
```bash
python -m cli
```

**启动开发环境：**
```bash
python -m cli dev
```

**启动生产环境：**
```bash
python -m cli prod
```

CLI命令支持自动检测环境配置，生产环境会自动启用多进程模式和禁用自动重载功能。

### 部署方式（Linux服务器）

#### 使用 systemd 服务管理应用（推荐）

在 Linux 服务器上，可以使用 systemd 服务来管理 FastAPI 应用，实现开机自启、后台运行、状态监控等功能。

##### 1. 创建 systemd 服务文件

使用系统上已安装的文本编辑器（如 nano、vim、vi 或 cat）创建服务文件：

**方法1：使用 nano（如果已安装）**
```bash
sudo nano /etc/systemd/system/fastapi-webframework.service
```

**方法2：使用 vim（更通用，大多数Linux系统默认安装）**
```bash
sudo vim /etc/systemd/system/fastapi-webframework.service
```

**方法3：使用 cat 配合重定向创建文件**
```bash
sudo cat > /etc/systemd/system/fastapi-webframework.service << 'EOF'
[Unit]
Description=FastAPI Web Framework Service
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/path/to/fastapi_webframework
Environment="PATH=/path/to/venv/bin"
ExecStart=/path/to/venv/bin/start-production
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOF
```

**服务文件参数说明：**
- `Description`: 服务描述
- `User/Group`: 运行服务的用户和组
- `WorkingDirectory`: 项目根目录
- `Environment`: 设置环境变量（主要是Python虚拟环境路径）
- `ExecStart`: 启动命令（使用生产环境启动命令）
- `Restart`: 失败时重启策略
- `RestartSec`: 重启间隔时间

**注意：** 如果使用 方法1 或 方法2 创建文件，需要将上述配置内容添加到文件中；如果使用 方法3，配置内容已自动包含在命令中。

##### 2. 重新加载 systemd 配置

```bash
sudo systemctl daemon-reload
```

##### 3. 启动并启用服务

```bash
sudo systemctl start fastapi-webframework
sudo systemctl enable fastapi-webframework
```

##### 4. 管理服务

```bash
# 查看服务状态
sudo systemctl status fastapi-webframework

# 停止服务
sudo systemctl stop fastapi-webframework

# 重启服务
sudo systemctl restart fastapi-webframework

# 查看服务日志
sudo journalctl -u fastapi-webframework -f

# 查看最近的服务日志
sudo journalctl -u fastapi-webframework -n 100
```

#### 注意事项

1. 确保替换配置中的 `/path/to/fastapi_webframework` 和 `/path/to/venv` 为实际路径
2. 建议使用非 root 用户运行服务，如示例中的 `www-data`
3. 生产环境中应关闭自动重载功能（reload=False）
4. 定期查看服务日志，确保应用正常运行

### API 访问

- API 文档：`http://localhost:8000/api/docs`
- 健康检查：`http://localhost:8000/health`

### 路由规范
> app定义有默认前缀 "/api"
> 对于访问控制层，没有考虑 RESTful 风格，倾向于 POST 方法处理

所有业务路由都位于 `api` 目录下，遵循以下规范：
- 路由文件命名：`router.py` 或 `{module}_router.py`
- 路由变量命名：`{module_name}_router`
- 路由前缀：`/{module_name}`

示例 (以源码具体实现为准)：
```python
# api/user/router.py
from fastapi import APIRouter

user_router = APIRouter(prefix="/user", tags=["用户管理"])

@user_router.get("/user")
async def get_user():
    ...
```

## 📋 统一返回码规范

### 1. 返回码结构

所有API响应采用统一格式：
```json
{
    "code": "00000",
    "msg": "操作成功",
    "data": {},
    "timestamp": "2025-12-05 09:52:13 UTC"
}
```

### 2. 错误码分类

错误码采用三级分类：
- 第一级：系统分类（1-系统错误，2-权限异常，3-参数校验，4-业务逻辑，5-第三方服务）
- 第二级：模块编号（001-099）
- 第三级：具体错误（001-999）

示例：
- `40001`：业务逻辑-用户模块-用户不存在
- `20001`：权限异常-认证模块-未登录

### 3. 常用返回码

| 错误码 | 说明 | 使用场景 |
|--------|------|----------|
| 00000 | 操作成功 | 默认成功响应 |
| 20001 | 未登录，请先登录 | 需要登录的接口 |
| 20002 | 登录已过期 | Token过期 |
| 40001 | 用户不存在 | 用户相关操作 |
| 40002 | 密码错误 | 登录认证 |
| 10999 | 系统未知错误 | 系统异常 |

### 4. 使用示例

#### 成功响应
```python
from fastapi_webframework.common.response import BaseResponse

# 默认成功响应
return BaseResponse.success()

# 带数据的成功响应
return BaseResponse.success(data={"user_id": 123})

# 自定义成功消息
return BaseResponse.success(msg="创建成功", data={"id": 123})
```

#### 失败响应
```python
from fastapi_webframework.common.response import BaseResponse
from fastapi_webframework.common.response_code import ResponseCode

# 使用预定义错误码
return BaseResponse.fail(ResponseCode.USER_NOT_EXIST)

# 带附加数据的失败响应
return BaseResponse.fail(
    ResponseCode.AUTH_NO_PERMISSION,
    data={"required_permission": "admin"}
)
```

#### 业务异常
```python
from fastapi_webframework.core.exception_handler import BusinessException
from fastapi_webframework.common.response_code import ResponseCode

# 抛出业务异常
raise BusinessException(ResponseCode.USER_NOT_EXIST)

# 带附加数据的异常
raise BusinessException(
    ResponseCode.SYSTEM_UNKNOWN_ERROR,
    data={"error_detail": "数据库连接失败"}
)
```

## 🔧 核心功能

### 1. 路由自动发现

系统会自动发现 `api` 目录下(特定规约)的所有路由模块并注册，无需手动导入。
规约解析支持： /api/{module}/router.py 或 /api/{module}/{module}_router.py 两种模式

### 2. 模型自动发现与注册

系统会自动发现 `models` 目录下(特定规约)的所有ORM数据模块并注册，无需手动导入。
支持目录结构：/models/{module}/model.py 或 /models/{module}/{module}_model.py 两种模式

### 3. 统一异常处理

提供了全局异常处理机制，包括：
- 业务异常（BusinessException）
- 系统异常
- 参数校验异常
- HTTP异常

所有异常都会被统一格式化为标准响应格式返回给客户端。

### 4. 请求日志记录

通过中间件记录所有请求的详细信息(密码已脱敏处理)，包括：
- 请求方法
- 请求路径
- 请求参数
- 响应状态
- 处理耗时

### 5. 数据库管理

使用连接池管理数据库连接，支持：
- 连接池配置
- 自动重连
- 事务管理
- 异步会话支持

### 6. 双日志设计

项目采用双日志分离设计，可以避免应用发布时覆盖日志。

#### 6.1 应用日志
- **位置**：项目同级目录的 `logs` 文件夹
- **实现**：`utils/logger.py` 中的 `LogManager` 类
- **特性**：
  - 支持多进程安全写入
  - 控制台+文件双输出
  - 按天切割目录
  - 5GB单文件大小限制
  - 自定义规范的日志格式，并指向调用者信息，不致使调用内容被日志根吞掉

#### 6.2 服务器日志
- **位置**：由 `settings.LOG_PATH` 配置指定
- **实现**：`core/log_utils.py` 中的 `ensure_log_path_exists` 函数
- **特性**：
  - 确保日志目录和文件存在
  - 主要用于 Hypercorn 服务器的 `access.log` 和 `error.log`
  - 与应用日志分离，便于管理和分析

## 📦 依赖管理

### 1. 安装依赖

```bash
uv sync
```

### 2. 更新依赖

```bash
uv sync --upgrade
```

### 3. 可编辑包更新

当需要更新作为可编辑安装的包时，可以使用以下命令：

```bash
uv sync --upgrade --editable .
```

或者使用pip：

```bash
pip install -e . --upgrade
```

## ⚙️ 配置管理

项目使用 Pydantic Settings 进行配置管理，支持环境变量和 .env 文件。

### 1. 配置文件位置

- `.env.example`：环境变量示例文件
- `.env`：实际使用的环境变量文件（需自己创建）

### 2. 环境变量优先级

1. 命令行传入的环境变量
2. `.env` 文件中的环境变量
3. 系统环境变量
4. 默认值

### 3. 启动时指定配置文件

```bash
# 本地开发
ENV_FILE=.env.local python main.py

# 测试环境
ENV_FILE=.env.test python main.py

# 生产环境
ENV_FILE=.env.prod python main.py
```

## 其他

1. 时间处理，采用ISO 8601格式。
    - 所有时间均采用 UTC 时间
    - 客户端请求时间戳需包含时区信息，服务器端会自动转换为 UTC 时间
    - 所有时间在数据库中均以 UTC 时间存储
    - 客户端响应时间戳均为 UTC 时间
2. JWT 认证，采用了双Token模式。
   - **Access Token**：短期访问令牌，用于接口访问认证
   - **Refresh Token**：长期刷新令牌，用于获取新的访问令牌
   - **特性**：支持令牌轮转、重放攻击防护、令牌类型验证
   - **实现**：通过 `jti` 唯一标识符确保令牌唯一性，每次刷新时生成新的 Refresh Token

## 🧪 测试配置

### pytest 配置

项目使用 pytest 进行测试，配置位于 `pyproject.toml` 中：

```toml
[tool.pytest.ini_options]
testpaths = ["tests/testcases"]  # 测试目录指定
python_files = ["test_*.py", "*_test.py"]  # 测试文件命名规则
python_classes = ["Test*", "*TestCase"]  # 测试类命名规则
python_functions = ["test_*"]  # 测试函数命名规则

# 覆盖率配置
addopts = "--cov=fastapi_webframework --cov-report=term-missing --cov-report=html"
```

### 测试依赖安装

```bash
uv sync --dev
```

### 运行测试

```bash
# 运行所有测试
pytest

# 查看覆盖率报告
pytest --cov=fastapi_webframework --cov-report=html
```

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feature/AmazingFeature`
3. 提交更改：`git commit -m 'Add some AmazingFeature'`
4. 推送到分支：`git push origin feature/AmazingFeature`
5. 提交 Pull Request

## 📝 开发规范

1. 代码风格遵循 PEP 8
2. 所有函数和类都需要添加文档字符串
3. 提交信息需要清晰描述更改内容
4. 新功能应添加相应的测试用例

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 🙏 致谢

感谢所有为这个项目做出贡献的开发者。