3.4 KiB
后端开发
技术栈
Python 3.12 + FastAPI + SQLAlchemy + Alembic + loguru + httpx + chromadb uv (用于虚拟环境和依赖管理)
开发命令
启动命令之前确保目前在backend目录下，并且已经激活了虚拟环境。默认本地开发使用 SQLite（aiosqlite）文件数据库，Redis、ChromaDB、Neo4j 暂不启用
uv venv -p 3.12 # 创建虚拟环境
source .venv/bin/activate # 激活虚拟环境
uv add <pkg> # 添加依赖
uv remove <pkg> # 移除依赖
uv run python -m app.main # 按 .env 中 BACKEND_HOST/BACKEND_PORT 启动服务
uv run uvicorn app.main:app --reload --port 8000 # 手动指定端口启动服务（命令行 --port 会覆盖 .env）
# 数据库迁移
uv run alembic revision --autogenerate --rev-id=001 -m "描述" # 生成迁移
uv run alembic upgrade head # 执行迁移
uv run alembic downgrade -1 # 回滚一个版本
uv run alembic current # 查看当前版本
# 测试
uv run pytest # 运行测试
代码规范
在__init__文件中可以将模块内的类、函数等导出，方便其他模块导入使用 遵循 PEP 8 代码风格指南和更加pythonic的开发方式 遵循单一职责原则，每个文件、类、函数等都要只干一件事 使用 loguru 进行日志记录，避免使用 logging 模块 使用 Alembic 进行数据库迁移，禁止手动修改数据库表结构，文件命名以迁移版本号开头，例如 001_initial.py；迁移必须优先兼容 SQLite，涉及 PostgreSQL 专用 DDL 时必须提供 SQLite 分支或显式跳过 使用alembic init alembic命令初始化迁移环境，使用命令生成相关的迁移文件,不能直接生成迁移文件 使用 httpx 进行异步 HTTP 请求，禁止在路由函数内直接使用同步数据库会话或 httpx 客户端 所有的测试代码都写在tests目录下，测试文件命名以test_开头，测试函数命名以test_开头 所有敏感信息（如密钥、Token、数据库密码）必须通过环境变量或配置文件管理，禁止硬编码到代码中
代码审查
开发完成后必须使用以下命令进行代码检查：
uv run ruff check # Lint 检查
uv run ruff check --fix # 自动修复部分代码风格问题
uv run pre-commit run --all-files # 可选：完整运行 CI 级检查（包括类型检查）
确保没有任何 lint 错误后再提交。
绝对禁止事项
直接修改 pyproject.toml 文件添加或者移除依赖（必须使用 uv add/remove 命令）
在路由函数内直接使用同步数据库会话（必须通过 Depends 注入）
在路由函数内直接 async with httpx.AsyncClient()
使用 logging 模块（统一用 loguru）
硬编码密钥、Token、数据库密码到代码
手动创建/修改数据库表结构（必须使用 Alembic 迁移）
在 modules/ 中 import repositories / db / integrations / ai_provider / httpx / sqlalchemy（领域层禁止 IO，需要 IO 时上移到 services/application）
在业务目录（ai_provider / integrations 等）中持有 settings.py / config.py（配置统一进 core/config/）
使用 python-dotenv（.env 由 core/config 以绝对路径 _env_file 加载）