# backend_fastapi_model

**Repository Path**: runler/backend_fastapi_model

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-06
- **Last Updated**: 2026-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI 后端模板项目

一个功能完善的 FastAPI 项目模板，包含用户认证、数据库操作、异常处理、日志等基础功能。

## 技术栈

- **Web 框架**: FastAPI
- **数据库**: SQLAlchemy 2.x（开发环境 SQLite，生产环境 PostgreSQL）
- **认证**: JWT (PyJWT) + Argon2 密码哈希
- **配置管理**: Pydantic Settings
- **包管理**: uv
- **代码质量**: Ruff (lint + format)

## 项目结构

```
backend/
├── src/
│   ├── __init__.py
│   ├── main.py                 # 应用入口
│   ├── auth/                   # 认证模块
│   │   ├── __init__.py
│   │   ├── router.py           # 路由
│   │   ├── schemas.py          # Pydantic 模型
│   │   ├── models.py           # SQLAlchemy 模型
│   │   ├── crud.py             # CRUD 操作
│   │   ├── services.py         # 业务逻辑层
│   │   └── deps.py             # 依赖注入
│   ├── core/                   # 核心模块
│   │   ├── __init__.py
│   │   ├── config.py           # 配置管理
│   │   ├── security.py         # 安全相关（JWT、密码哈希）
│   │   ├── exceptions.py       # 自定义异常
│   │   ├── error_handlers.py   # 全局异常处理器
│   │   ├── middleware.py       # 中间件
│   │   ├── logging_config.py   # 日志配置
│   │   └── response.py         # 统一响应模型
│   └── db/                     # 数据库模块
│       ├── __init__.py
│       ├── base.py             # 基类和 CRUD 基类
│       ├── session.py          # 数据库会话
│       └── init_db.py          # 数据库初始化
├── .env                        # 环境变量（不提交到 git）
├── .env.example                # 环境变量示例
├── .gitignore
├── pyproject.toml              # 项目配置
└── README.md
```

## 快速开始

### 环境要求

- Python >= 3.11
- uv

### 安装依赖

```bash
# 创建虚拟环境并安装依赖
uv sync

# 安装开发依赖（可选，包含 pytest、ruff 等）
uv sync --extra dev
```

### 配置环境变量

```bash
# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，根据需要修改配置
```

### 启动开发服务器

```bash
# 使用 FastAPI CLI（推荐，支持热重载）
fastapi dev src/main.py

# 或使用 uvicorn
uvicorn src.main:app --reload
```

启动后访问：
- API 文档: http://localhost:8000/docs
- ReDoc 文档: http://localhost:8000/redoc
- 健康检查: http://localhost:8000/health

## 主要功能

### 1. 用户认证

- 用户注册
- 用户登录（JWT Token）
- Token 刷新
- 修改密码
- 获取当前用户信息
- Token 版本控制（支持强制下线）

### 2. 核心功能

- 统一异常处理
- 请求 ID 追踪
- 访问日志
- CORS 中间件
- GZip 压缩
- 统一响应模型
- 分页支持

### 3. 数据库

- SQLAlchemy ORM
- 开发环境 SQLite（开箱即用）
- 生产环境 PostgreSQL
- CRUD 基类，快速开发

## 常用命令

```bash
# 代码格式化
uv run ruff format .

# 代码检查
uv run ruff check .

# 自动修复 lint 问题
uv run ruff check --fix .

# 运行测试
uv run pytest
```

## API 接口

### 认证接口

| 方法 | 路径 | 说明 | 认证 |
|------|------|------|------|
| POST | `/api/v1/auth/register` | 用户注册 | 否 |
| POST | `/api/v1/auth/login` | 登录获取 token | 否 |
| GET | `/api/v1/auth/me` | 获取当前用户信息 | 是 |
| POST | `/api/v1/auth/change-password` | 修改密码 | 是 |
| POST | `/api/v1/auth/refresh` | 刷新 token | 否 |

### 系统接口

| 方法 | 路径 | 说明 | 认证 |
|------|------|------|------|
| GET | `/health` | 健康检查 | 否 |

## 统一响应与错误码

所有接口（包括登录、健康检查）都返回同一套响应结构，前端只需实现一种解析逻辑。

### 成功响应

```json
{
  "code": 0,
  "message": "登录成功",
  "data": { "access_token": "...", "refresh_token": "...", "token_type": "bearer", "expires_in": 86400 },
  "request_id": "9fd11e01d7e0"
}
```

### 失败响应

```json
{
  "code": 12002,
  "message": "用户名已被占用",
  "data": null,
  "request_id": "c6af13d3632b",
  "errors": [{ "field": "username", "reason": "用户名已被占用" }]
}
```

| 字段 | 说明 |
|------|------|
| `code` | 业务码，`0` 表示成功，非 0 见下方错误码分段 |
| `message` | 提示语，可直接展示给用户 |
| `data` | 业务数据，失败时固定为 `null` |
| `request_id` | 请求 ID，与响应头 `X-Request-ID` 一致，报障时提供给后端 |
| `errors` | 字段级错误明细，仅失败时出现 |

### 错误码分段

| 区间 | 含义 | 示例 |
|------|------|------|
| `0` | 成功 | `0` |
| `10000-10999` | 通用错误 | `10000` 系统内部错误、`10002` 参数校验失败、`10003` 资源不存在 |
| `11000-11999` | 认证与授权 | `11001` 未认证、`11002` 登录已过期、`11004` 权限不足、`11005` 账号已禁用 |
| `12000-12999` | 用户与账号 | `12002` 用户名已被占用、`12003` 邮箱已被注册、`12004` 旧密码错误 |

完整错误码见 [exceptions.py](src/core/exceptions.py) 中的 `ErrorCode`。

### 如何在业务代码中使用

业务代码只抛异常，不手工拼响应，全局处理器会自动转成标准结构：

```python
from src.core.exceptions import ErrorCode, NotFoundError, ConflictError
from src.core.response import success

# 抛业务异常
raise ConflictError(code=ErrorCode.USERNAME_TAKEN, field="username")

# 返回成功响应
return success(user, message="注册成功")
```

新增错误码时，在 `ErrorCode` 对应区间接续编号即可。

> 文档认证使用 HTTPBearer：登录返回的 token 在 `data.access_token` 中，
> 在 Swagger 的 Authorize 弹窗里粘贴该 token 即可调试受保护接口。

## 开发说明

### 添加新模块

1. 在 `src/` 下创建新模块目录
2. 创建 `models.py`（SQLAlchemy 模型）
3. 创建 `schemas.py`（Pydantic 模型）
4. 创建 `crud.py`（继承 CRUDBase）
5. 创建 `services.py`（业务逻辑）
6. 创建 `router.py`（路由）
7. 在 `main.py` 中注册路由

### 环境变量说明

详见 `.env.example` 文件，主要配置项：

- `APP_NAME`: 应用名称
- `ENVIRONMENT`: 运行环境（development/testing/production）
- `DEBUG`: 是否开启调试模式
- `SECRET_KEY`: JWT 签名密钥（生产环境必须修改）
- `ACCESS_TOKEN_EXPIRE_MINUTES`: Access Token 有效期
- `REFRESH_TOKEN_EXPIRE_DAYS`: Refresh Token 有效期
- `CORS_ORIGINS`: 允许的跨域源

## 生产部署

1. 设置 `ENVIRONMENT=production`
2. 设置强密钥 `SECRET_KEY`
3. 配置 PostgreSQL 数据库
4. 使用 `fastapi run` 启动生产服务器
5. 建议使用 Nginx 反向代理

## License

MIT