# fastapi-template

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

## Basic Information

- **Project Name**: fastapi-template
- **Description**: fastapi 模版，包含基础的用户、角色和权限
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-30
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI 基础模板

一个功能完整的 FastAPI 项目模板，包含用户认证、RBAC 权限管理、数据库集成等企业级功能。

## 🚀 功能特性

- **用户认证系统**: JWT Token 认证，支持登录/注册
- **RBAC 权限管理**: 基于角色的访问控制，细粒度权限管理
- **数据库集成**: SQLAlchemy + Alembic 数据库迁移
- **API 文档**: 自动生成的 OpenAPI/Swagger 文档
- **分页支持**: 内置分页功能
- **CORS 支持**: 跨域资源共享配置
- **环境配置**: 基于 Pydantic Settings 的配置管理
- **代码结构**: 清晰的项目结构和模块化设计

## 📋 技术栈

- **框架**: FastAPI 0.119+
- **数据库**: SQLite (可轻松切换到 PostgreSQL/MySQL)
- **ORM**: SQLAlchemy 2.0+
- **认证**: JWT + pwdlib
- **密码加密**: Argon2
- **数据验证**: Pydantic 2.0+
- **数据库迁移**: Alembic
- **分页**: fastapi-pagination
- **Python**: 3.12+

## 🛠️ 快速开始

### 环境要求

- Python 3.12+
- uv (推荐) 或 pip

### 安装依赖

使用 uv (推荐):
```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装项目依赖
uv sync
```

或使用 pip:
```bash
pip install -r requirements.txt
```

### 环境配置

创建 `.env` 文件:
```bash
cp .env.example .env
```

编辑 `.env` 文件，配置必要的环境变量:
```env
APP_NAME=FastAPI基础模板
DEBUG=true
DATABASE_URL=sqlite+aiosqlite:///./db.sqlite3
SECRET_KEY=your-super-secret-key-change-this-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=43200
```

### 数据库初始化

```bash
# 初始化数据库迁移
alembic upgrade head

# 初始化 RBAC 权限数据
python -m scripts.init_rbac_data

# 创建管理员用户 (可选)
python -m scripts.init_admin
```

### 启动服务

```bash
# 开发模式
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

服务启动后，访问:
- API 文档: http://localhost:8000/docs
- ReDoc 文档: http://localhost:8000/redoc

## 📁 项目结构

```
├── app/                    # 应用主目录
│   ├── apis/              # API 路由
│   │   └── v1/           # API v1 版本
│   │       ├── auth.py   # 认证相关 API
│   │       └── user.py   # 用户管理 API
│   ├── common/           # 公共模块
│   │   ├── jwt.py        # JWT 工具
│   │   └── rbac.py       # RBAC 权限验证
│   ├── core/             # 核心配置
│   │   ├── config.py     # 应用配置
│   │   └── db.py         # 数据库配置
│   ├── middlewares/      # 中间件
│   │   └── auth_middleware.py  # 认证中间件
│   ├── models/           # 数据模型
│   │   ├── base.py       # 基础模型
│   │   └── user.py       # 用户模型
│   ├── schemas/          # Pydantic 模式
│   │   ├── auth.py       # 认证相关模式
│   │   ├── role.py       # 角色模式
│   │   └── user.py       # 用户模式
│   ├── services/         # 业务逻辑层
│   │   ├── auth_service.py      # 认证服务
│   │   ├── permission_service.py # 权限服务
│   │   ├── role_service.py      # 角色服务
│   │   └── user_service.py      # 用户服务
│   └── main.py           # 应用入口
├── alembic/              # 数据库迁移
├── scripts/              # 工具脚本
│   ├── init_admin.py     # 初始化管理员
│   └── init_rbac_data.py # 初始化权限数据
├── pyproject.toml        # 项目配置
└── README.md            # 项目文档
```

## 🔐 认证系统

### 用户注册
```bash
curl -X POST "http://localhost:8000/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "password123",
    "email": "test@example.com"
  }'
```

### 用户登录
```bash
curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "password123"
  }'
```

### 访问受保护的 API
```bash
curl -X GET "http://localhost:8000/api/v1/user/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## 🛡️ RBAC 权限系统

本项目实现了完整的 RBAC (基于角色的访问控制) 系统:

### 权限结构
- **资源 (Resource)**: 如 `user`, `role`, `permission`
- **对象 (Object)**: 具体的资源实例
- **操作 (Action)**: `read`, `write`, `update`, `delete`

### 权限格式
权限字符串格式: `resource:object:action`

示例:
- `user:user:read` - 读取用户信息
- `user:user:write` - 创建用户
- `role:role:update` - 更新角色

### 使用权限验证
```python
from app.common.rbac import rbac_verify

@router.get("/users", dependencies=[
    Depends(security), 
    Depends(rbac_verify("user", "user", "read"))
])
async def list_users():
    # 只有拥有 user:user:read 权限的用户才能访问
    pass
```

## 🗄️ 数据库操作

### 创建迁移
```bash
alembic revision --autogenerate -m "描述你的更改"
```

### 应用迁移
```bash
alembic upgrade head
```

### 回滚迁移
```bash
alembic downgrade -1
```

## 🧪 开发指南

### 添加新的 API 端点

1. 在 `app/schemas/` 中定义 Pydantic 模式
2. 在 `app/models/` 中定义数据库模型
3. 在 `app/services/` 中实现业务逻辑
4. 在 `app/apis/v1/` 中创建 API 路由
5. 在需要的地方添加权限验证

### 代码风格

项目使用以下工具保证代码质量:
- **类型检查**: 使用类型注解
- **代码格式化**: 建议使用 black 或 ruff
- **导入排序**: 建议使用 isort

## 🚀 部署

### Docker 部署 (推荐)

创建 `Dockerfile`:
```dockerfile
FROM python:3.12-slim

WORKDIR /app

# 安装 uv
RUN pip install uv

# 复制依赖文件
COPY pyproject.toml uv.lock ./

# 安装依赖
RUN uv sync --frozen

# 复制应用代码
COPY . .

# 运行数据库迁移
RUN uv run alembic upgrade head

# 初始化数据
RUN uv run python -m scripts.init_rbac_data

EXPOSE 8000

CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### 生产环境配置

1. 设置 `DEBUG=false`
2. 使用强密码作为 `SECRET_KEY`
3. 配置生产数据库 (PostgreSQL/MySQL)
4. 设置适当的 CORS 策略
5. 使用 HTTPS

## 📝 API 文档

启动服务后，可以通过以下地址访问 API 文档:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **OpenAPI JSON**: http://localhost:8000/openapi.json

## 🤝 贡献

欢迎提交 Issue 和 Pull Request!

## 📄 许可证

MIT License

## 📞 支持

如有问题，请提交 Issue 或联系维护者。