# fastapi-template

**Repository Path**: ggxx/fastapi-template

## Basic Information

- **Project Name**: fastapi-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-15
- **Last Updated**: 2025-12-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 脚手架, Python

## README

# FastAPI Template

一个结构清晰、功能完整的 FastAPI 项目模板，采用异步编程和现代 Python 最佳实践。

## 功能特性

- 异步 API（async/await）
- 用户认证（注册、登录、Token 验证）
- 管理员后台认证
- 文件上传（按日期/用户分目录存储）
- Pydantic Schema 数据验证
- 统一响应格式和全局异常处理
- 多环境配置支持（pydantic-settings）
- 内置 API 测试页面

## 技术栈

| 类别 | 技术 |
|------|------|
| Web 框架 | FastAPI 0.104.1 |
| ASGI 服务器 | Uvicorn 0.24.0 |
| ORM | SQLAlchemy 2.0.23（异步） |
| 数据库 | SQLite + aiosqlite（默认） |
| 数据验证 | Pydantic 2.5.2 |
| 配置管理 | pydantic-settings 2.1.0 |
| 认证 | Token 认证 |

## 项目结构

```
fastapi-template/
├── Application.py          # 开发模式启动入口
├── start_app.py            # 生产模式启动入口
├── requirements.txt        # Python 依赖
├── .env                    # 环境变量配置（可选）
├── app/                    # 主应用目录
│   ├── __init__.py         # 应用工厂函数 + 全局异常处理器
│   ├── config.py           # 配置类（pydantic-settings）
│   ├── database.py         # 异步数据库连接管理
│   ├── db_utils.py         # 异步数据库工具函数
│   ├── models.py           # SQLAlchemy 2.0 数据模型
│   ├── schemas/            # Pydantic Schema
│   │   ├── __init__.py     # Schema 导出
│   │   ├── common.py       # 通用响应模型
│   │   ├── user.py         # 用户相关 Schema
│   │   └── upload.py       # 上传相关 Schema
│   ├── api/                # 前端 API 路由
│   │   ├── __init__.py     # API 路由注册
│   │   ├── users.py        # 用户 API
│   │   └── uploads.py      # 文件上传 API
│   └── controller/         # 管理后台路由
│       ├── __init__.py     # Admin 路由注册
│       └── auth.py         # 管理员认证
├── data/                   # 数据目录
│   └── app.db              # SQLite 数据库
├── static/                 # 静态文件
└── ui/                     # 前端测试页面
```

## 快速开始

### 安装依赖

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

### 启动服务

**开发模式**（支持热重载）：

```bash
python Application.py
```

**生产模式**：

```bash
uvicorn app:create_app --factory --host 0.0.0.0 --port 8127 --workers 4
```

服务默认运行在 `http://localhost:8127`

### 默认管理员账户

首次启动时自动创建：

- 用户名：`admin`
- 密码：`123456`

## API 文档

启动服务后访问：

- Swagger UI：`http://localhost:8127/docs`
- ReDoc：`http://localhost:8127/redoc`

### 用户 API

| 方法 | 端点 | 功能 | 请求模型 | 响应模型 |
|------|------|------|----------|----------|
| POST | `/api/user/register` | 用户注册 | `UserCreate` | `ResponseModel[UserResponse]` |
| POST | `/api/user/login` | 用户登录 | `UserLogin` | `ResponseModel[UserWithToken]` |
| GET | `/api/user/info` | 获取用户信息 | Header: token | `ResponseModel[UserResponse]` |
| POST | `/api/upload` | 文件上传 | FormData | `ResponseModel[UploadResponse]` |

### 管理员 API

| 方法 | 端点 | 功能 | 请求模型 | 响应模型 |
|------|------|------|----------|----------|
| POST | `/admin/api/login` | 管理员登录 | `AdminLogin` | `ResponseModel[AdminResponse]` |
| POST | `/admin/api/logout` | 管理员登出 | - | `ResponseModel` |
| GET | `/admin/api/info` | 获取管理员信息 | Header: Authorization | `ResponseModel[AdminResponse]` |

### 统一响应格式

所有 API 返回统一的 JSON 格式：

```json
{
  "code": 200,
  "message": "成功",
  "data": { ... }
}
```

## 配置说明

### 环境变量

创建 `.env` 文件配置环境变量：

```env
SECRET_KEY=your_secret_key
DATABASE_URL=sqlite+aiosqlite:///./data/app.db
BASE_URL=http://localhost:8127
DEBUG=true
```

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `SECRET_KEY` | 应用密钥 | `hard_to_guess_string` |
| `DATABASE_URL` | 异步数据库连接 URL | SQLite 本地文件 |
| `BASE_URL` | 服务器基础 URL | `http://localhost:8127` |
| `DEBUG` | 调试模式 | `true` |

### 文件上传配置

- 支持格式：png, jpg, jpeg, gif, webp
- 最大大小：16MB
- 存储路径：`static/uploads/{日期}/{用户}/`

## 架构特点

### 异步优先

所有数据库操作和 I/O 操作都使用 `async/await`：

```python
@api.post("/user/login", response_model=ResponseModel[UserWithToken])
async def login(
    data: UserLogin,
    db: AsyncSession = Depends(get_db)
) -> ResponseModel[UserWithToken]:
    user = await get_one(db, User, phone_number=data.phone_number)
    ...
```

### 类型安全

使用 Pydantic Schema 进行数据验证和序列化：

```python
class UserLogin(BaseModel):
    phone_number: str = Field(..., description="手机号")
    password: str = Field(..., description="密码")
```

### 依赖注入

通过 `Depends()` 管理数据库会话和认证：

```python
async def get_db() -> AsyncGenerator[AsyncSession, None]:
    async with AsyncSessionLocal() as session:
        yield session
```

### 全局异常处理

统一处理 HTTPException 和验证错误：

```python
@app.exception_handler(HTTPException)
async def http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"code": exc.status_code, "message": exc.detail, "data": None}
    )
```

## API 测试页面

访问 `http://localhost:8127/ui/index.html` 可使用内置的 API 测试页面。

## License

MIT