# flask项目后端通用模版

**Repository Path**: test-lh/Backend-Template

## Basic Information

- **Project Name**: flask项目后端通用模版
- **Description**: flask项目后端通用模版
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-13
- **Last Updated**: 2025-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TT2 Flask Backend

基于 Flask 的前后端分离后端示例，内置 RESTX 文档、JWT 鉴权、Flask-Security-Too 角色权限以及数据库迁移。

## 功能模块
- **Flask-RESTX**：提供 `/api/docs` Swagger 文档与 Namespaces。
- **Flask-JWT-Extended**：登录发行 Access/Refresh Token，`/api/auth/me` 获取当前用户。
- **Flask-Security-Too**：管理用户、角色与密码哈希。
- **SQLAlchemy + Flask-Migrate**：ORM 与数据库迁移。

## 快速开始
```bash
cd ~/Desktop/xm/tt2/backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
flask db init
flask db migrate -m "create tables"
flask db upgrade
flask create-admin admin@example.com Admin123!
flask run
```

启动后访问 `http://localhost:5000/api/docs` 查看 Swagger 文档。

## 环境配置
应用在 `app/__init__.py` 顶部调用 `_load_environment()`，加载优先级如下：
1. 若设置 `ENV_FILE` 环境变量，优先读取对应文件。
2. 否则尝试 `.env`，再回退到 `.env.dev`。

常见命令示例：
```bash
# 默认使用 .env.dev
python manage.py runserver

# 显式使用开发配置
ENV_FILE=.env.dev python manage.py runserver

# 使用测试配置运行单元测试
ENV_FILE=.env.test pytest

# 使用生产配置启动 Gunicorn（示例）
ENV_FILE=.env.prod gunicorn 'manage:app'
```

仓库中已提供 `.env.dev`、`.env.test`、`.env.prod` 三份示例文件，按环境替换为真实密钥与数据库连接即可。

## 演示接口与权限
新增 `demo` 命名空间以说明 REST API 与角色控制：
- `GET /api/demo/ping`：无需鉴权，返回 `pong` 与当前 `FLASK_ENV` 值。
- `GET /api/demo/secure-info`：需携带 JWT 且拥有 `admin` 角色，返回当前用户信息。

公共权限校验封装在 `app/utils/auth.py` 中的 `require_role`/`require_roles`，需要限制权限时可直接调用。

## 主要命令
- `flask db <command>`：数据库迁移相关（init/migrate/upgrade/downgrade）。
- `flask create-admin <email> <password>`：创建管理员账号（自动创建 `admin` 与 `user` 角色）。
- `pytest`：可按需添加测试并运行。

## Token 使用示例
```bash
# 登录获取访问令牌
curl -X POST http://localhost:5000/api/auth/login   -H "Content-Type: application/json"   -d '{"email": "admin@example.com", "password": "Admin123!"}'

# 携带 token 访问受保护资源
curl http://localhost:5000/api/users   -H "Authorization: Bearer <ACCESS_TOKEN>"
```

1. `POST /api/auth/login`，Body：`{"email": "admin@example.com", "password": "Admin123!"}`。
2. 得到 `access_token` 后，在需要鉴权的接口设置 `Authorization: Bearer <token>`。
3. 管理员可调用 `GET /api/users` 查看全部用户，`POST /api/users` 新增用户。

## 项目结构
```
backend/
  app/
    __init__.py            # Flask 工厂与扩展注册
    config.py              # 配置项
    extensions.py          # SQLAlchemy、RESTX、JWT、Security 实例
    models/                # ORM 模型包
      __init__.py
      associations.py      # 多对多表声明
      role.py              # Role 实体
      user.py              # User 实体
    resources/             # RESTX 接口定义
      __init__.py
      auth.py
      demo.py
      user.py
    utils/                 # 通用工具函数
      __init__.py
      auth.py              # 权限校验 helper
  instance/                # 实例配置与运行时文件
  migrations/              # Flask-Migrate 版本库
  manage.py                # 运行入口
  requirements.txt
  README.md
```