# python-backend

**Repository Path**: erheihei/python-backend

## Basic Information

- **Project Name**: python-backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-28
- **Last Updated**: 2025-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI 后端框架

基于 FastAPI 的 Python 后端框架，符合规范要求的项目结构和代码组织。

## 技术栈

- Python 3
- Web框架：FastAPI
- 缓存：Redis
- 数据签名与加密：itsdangerous
- 文件上传：python-multipart
- HTTP请求：requests
- ORM框架：SQLAlchemy
- 数据库驱动：MySQL Connector Python
- 配置管理：dynaconf

## 目录结构

```
.
├── config              # 配置文件目录
│   └── config.yaml     # 主配置文件
├── main.py             # 应用入口
├── requirements.txt    # 项目依赖
└── app
    ├── api             # API路由接口
    │   ├── __init__.py
    │   └── users.py    # 用户API示例
    ├── exception       # 全局异常处理
    │   ├── __init__.py
    │   └── handlers.py
    ├── models          # 数据库模型
    │   ├── __init__.py
    │   └── user.py     # 用户模型示例
    ├── services        # 业务服务层
    │   ├── __init__.py
    │   └── user_service.py  # 用户服务示例
    └── utils           # 工具类
        ├── __init__.py
        ├── pagination.py    # 分页工具
        ├── redis_util.py    # Redis工具
        ├── response.py      # 响应工具
        └── security.py      # 安全工具
```

## 统一响应格式

所有API遵循统一的响应格式：

```json
{
    "code": 0,          // 0表示成功，非0表示错误
    "errorMsg": "",     // 错误信息
    "data": {},         // 响应数据
    "total": null       // 数据总数（用于分页）
}
```

## 快速开始

1. 安装依赖：

```bash
pip install -r requirements.txt
```

2. 配置数据库和Redis：
   
编辑 `config/config.yaml` 文件，修改数据库和Redis连接信息。

3. 运行应用：

```bash
python main.py
```

或者使用uvicorn：

```bash
uvicorn main:app --reload
```

4. 访问API文档：

在浏览器中打开 `http://127.0.0.1:8000/docs`，查看自动生成的API文档。

## 开发指南

### 创建新的模型

在 `app/models` 目录下创建新文件，继承 `BaseModel`：

```python
from app.models import BaseModel
from sqlalchemy import Column, String

class NewModel(BaseModel):
    __tablename__ = "table_name"
    
    name = Column(String(50), nullable=False)
    # 其他字段...
```

### 创建新的服务

在 `app/services` 目录下创建新文件：

```python
class NewService:
    @staticmethod
    def some_method():
        # 实现业务逻辑
        pass
```

### 创建新的API接口

在 `app/api` 目录下创建新文件：

```python
from fastapi import APIRouter
from app.utils.response import Response

router = APIRouter(prefix="/resource", tags=["资源"])

@router.get("")
def get_resources():
    # 实现API逻辑
    return Response.success(data={"items": []})
```

然后在 `app/api/__init__.py` 中注册路由：

```python
from app.api.new_module import router as new_router
router.include_router(new_router)
```

### 分页用法

使用 `BasePage` 作为依赖项接收分页参数：

```python
from app.utils.pagination import BasePage

@router.get("")
def get_list(page_params: BasePage = Depends()):
    page = page_params.page
    page_size = page_params.page_size
    # 实现分页逻辑
    return Response.page_success(data=items, total=total)
```

## 错误处理

框架已集成全局异常处理，可以通过抛出对应的异常来返回统一格式的错误响应：

```python
from app.exception import ResourceNotFoundError, ValidationError

# 在适当的地方抛出异常
raise ResourceNotFoundError("资源不存在")
raise ValidationError("数据验证失败")
```