143 lines
5.9 KiB
Plaintext
143 lines
5.9 KiB
Plaintext
---
|
||
description: pythonbackend 项目总览、分层架构与运行方式
|
||
alwaysApply: true
|
||
---
|
||
|
||
# pythonbackend 项目约定
|
||
|
||
aiclient 的 Python 后端，为桌面/前端提供 HTTP API。默认监听 `http://127.0.0.1:8001`（见根目录 `main.py`）。
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 库 | 用途 |
|
||
|------|-----|------|
|
||
| Web | FastAPI + Uvicorn | 异步 HTTP、OpenAPI（`/docs`） |
|
||
| 校验/配置 | Pydantic v2、`pydantic-settings` | 请求/响应模型、`.env` 配置 |
|
||
| 数据库 | SQLAlchemy 2（async）+ **aiomysql** | MySQL 异步访问 |
|
||
| 迁移 | Alembic | 表结构版本管理（异步 `alembic/env.py`） |
|
||
| 缓存/会话 | **redis**（`redis.asyncio`） | JWT 会话存证、登出吊销 |
|
||
| 安全 | passlib（bcrypt）、python-jose | 密码哈希、JWT 签发/校验 |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
pythonbackend/
|
||
├── main.py # 开发入口：uvicorn 启动 app.main:app
|
||
├── requirements.txt
|
||
├── .env / .env.example # 环境变量（不入库 .env）
|
||
├── alembic.ini
|
||
├── alembic/
|
||
│ ├── env.py # 从 app.config 读 database_url，异步迁移
|
||
│ └── versions/ # 迁移脚本
|
||
└── app/
|
||
├── main.py # FastAPI 工厂、CORS、lifespan、路由挂载
|
||
├── config.py # Settings（get_settings 单例）
|
||
├── database.py # AsyncEngine、Session、Base、get_db
|
||
├── redis_client.py # init/close/get_redis、redis_dependency
|
||
├── dependencies.py # FastAPI Depends（DbSession、CurrentUser 等）
|
||
├── core/ # 与框架无关的工具（security）
|
||
├── models/ # SQLAlchemy ORM 模型
|
||
├── schemas/ # Pydantic 入参/出参、ApiResponse
|
||
├── services/ # 业务逻辑（不依赖 Request/Response）
|
||
└── api/v1/ # 路由层：薄控制器，组装 ApiResponse
|
||
```
|
||
|
||
## 分层架构（自上而下）
|
||
|
||
```
|
||
HTTP 请求
|
||
→ api/v1/*.py 路由：解析 body、注入 Depends、捕获业务异常 → ApiResponse
|
||
→ services/*.py 业务：查询/写入 DB、抛 AuthError 等，返回 schema 或模型
|
||
→ models/*.py ORM：表定义，仅在 services / dependencies 使用
|
||
→ database.py 连接池与 get_db（请求结束 commit，异常 rollback）
|
||
|
||
横切：
|
||
→ schemas/ 请求体验证、响应类型；对外 JSON 字段 snake_case（注册 confirmPassword 例外见 auth schema）
|
||
→ core/security.py 密码哈希、JWT、Redis session key 前缀
|
||
→ dependencies.py 鉴权：Redis session 优先，否则回退 JWT sub
|
||
→ redis_client.py lifespan 内 init_redis，路由经 redis_dependency 注入
|
||
```
|
||
|
||
**原则**
|
||
|
||
- `api/` 不写 SQL、不直接操作 Redis 细节；调用 `services/`。
|
||
- `services/` 不 import FastAPI 的 `Request`/`HTTPException`（业务错误用自定义异常，如 `AuthError`）。
|
||
- 新增表：先 `models/` → Alembic 迁移 → 再 `schemas` + `services` + `api`。
|
||
|
||
## 配置（app/config.py）
|
||
|
||
- 从项目根 `.env` 加载，字段见 `.env.example`。
|
||
- `database_url`：`mysql+aiomysql://...`
|
||
- `redis_url`、`secret_key`、`access_token_expire_minutes`、`cors_origins`（逗号分隔或 `*`）。
|
||
- 通过 `get_settings()` 获取，勿在模块顶层反复实例化 Settings。
|
||
|
||
## 数据库与会话
|
||
|
||
- `get_db()`：每个请求一个 `AsyncSession`，正常结束 `commit`，异常 `rollback`。
|
||
- 路由使用类型别名 `DbSession = Annotated[AsyncSession, Depends(get_db)]`。
|
||
- ORM 基类：`database.Base`；新模型须在 `alembic/env.py` 中 import 以纳入 `target_metadata`。
|
||
|
||
## Redis 与会话
|
||
|
||
- 应用 `lifespan`：`init_redis()` → 运行 → `close_redis()`。
|
||
- 登录/注册成功：`services.auth.store_session(redis, token, user_id)`，key `session:{token}`，TTL 与 JWT 过期一致。
|
||
- 登出：`revoke_session` 删除 key；鉴权时 Redis 无记录则回退解析 JWT（已登出会话失效）。
|
||
|
||
## 统一响应 ApiResponse
|
||
|
||
定义于 `app/schemas/common.py`：
|
||
|
||
- `ok: bool` — 业务是否成功
|
||
- `message: str` — 用户可见提示（中文）
|
||
- `data: T | None` — 成功载荷
|
||
|
||
业务失败（如用户名已存在）返回 **HTTP 200** + `ok: false`，勿抛未捕获异常。未认证访问受保护路由由 `dependencies.get_current_user` 抛 **401**（非 ApiResponse 信封）。
|
||
|
||
前端约定详见 aiclient 仓库 `.cursor/rules/aiclient-overview.mdc` 中「后端 API 约定」一节。
|
||
|
||
## 认证模块（当前实现）
|
||
|
||
| 层 | 文件 |
|
||
|----|------|
|
||
| 路由 | `app/api/v1/auth.py` |
|
||
| 业务 | `app/services/auth.py` |
|
||
| 模型 | `app/models/user.py` |
|
||
| Schema | `app/schemas/auth.py` |
|
||
| 挂载 | `app/api/v1/router.py` → `app/main.py` 前缀 `/api/v1` |
|
||
|
||
端点：`POST /auth/register|login|logout`，`GET /auth/me`；根路径 `GET /health`。
|
||
|
||
## Alembic
|
||
|
||
```bash
|
||
# 项目根目录，激活 venv 后
|
||
alembic upgrade head # 应用迁移
|
||
alembic revision -m "描述" # 新建迁移（需人工编写 upgrade/downgrade）
|
||
```
|
||
|
||
- `alembic/env.py` 使用异步引擎，URL 来自 `Settings.database_url`。
|
||
- 改表后必须提交 `alembic/versions/` 下的迁移文件。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
alembic upgrade head
|
||
python main.py # 或: uvicorn app.main:app --reload --port 8001
|
||
```
|
||
|
||
## 新增功能 checklist
|
||
|
||
1. `app/models/` 定义 ORM（如需持久化）
|
||
2. `alembic revision` + `upgrade head`
|
||
3. `app/schemas/` 请求/响应模型
|
||
4. `app/services/` 业务函数
|
||
5. `app/api/v1/` 路由，挂到 `router.py`
|
||
6. 需登录：`dependencies.CurrentUser`；需 Redis：参数 `RedisClient`
|
||
7. 对外 JSON 保持 `ApiResponse` 信封；错误文案简体中文
|
||
|
||
## 通用原则
|
||
|
||
- Python 3.11+ 类型注解；异步路由与 async service 一致。
|
||
- 密码仅存 `password_hash`，禁止日志或响应中输出明文密码。
|
||
- 生产环境必须修改 `SECRET_KEY`，勿提交 `.env`。
|