@stephen-lord/docs 1.0.0 → 1.0.1

package/dist-repo/fastapi-backend/.claude/skills/tortoise-orm-best-practice/SKILL.md

@@ -0,0 +1,690 @@
+---
+name: tortoise-orm-best-practices
+description: Tortoise-ORM 最佳实践指南,涵盖模型定义、查询优化、事务管理、性能调优及无物理外键场景的关系处理。
+license: MIT
+metadata:
+  author: tortoise-orm-community
+  version: "1.0"
+  last_updated: "2026-01-18"
+  tortoise_version: ">=0.20.0"
+  quick_reference:
+    - "使用 prefetch_related 避免 N+1 查询"
+    - "db_constraint=False 实现逻辑外键"
+    - "@atomic() 装饰器管理事务"
+    - "bulk_create/bulk_update 批量操作"
+    - "为逻辑外键字段创建索引"
+    - "values/values_list 减少数据传输"
+---
+
+# Tortoise-ORM 最佳实践指南
+
+## 概述
+
+本指南提供 Tortoise-ORM 开发的最佳实践,专注高并发场景的性能优化与数据一致性。重点解决在禁用物理外键时,如何正确维护 ORM 层面的逻辑关系。
+
+## 核心原则
+
+### 异步优先
+- 所有数据库操作使用 `async/await` 语法
+- 避免异步上下文中的同步调用
+- 合理配置连接池,避免连接泄漏
+
+### 性能优化
+- 使用 `select_related` 和 `prefetch_related` 预加载关联数据
+- 使用 `values/values_list` 只获取所需字段
+- 批量操作提升大量数据处理效率
+- 为高频查询字段创建索引
+
+### 数据安全
+- 事务保障复杂操作的原子性
+- 应用层保证引用完整性(无物理外键时)
+- 环境变量管理敏感配置,禁止硬编码
+
+### 工程化规范
+- Schema 与模型分离,独立管理 Pydantic 模型
+- 使用 lifespan 事件管理应用生命周期
+- 完善的日志和监控体系
+
+## 生产环境配置
+
+### 应用生命周期管理 (推荐 lifespan)
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from tortoise import Tortoise
+from utils.cache import cache_manager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """应用生命周期管理"""
+    # 启动时执行
+    await Tortoise.init(
+        db_url="postgres://user:pass@localhost:5432/dbname",
+        modules={"models": ["app.models"]},
+    )
+    await Tortoise.generate_schemas()
+    await cache_manager.connect()
+    yield
+    # 关闭时执行
+    await Tortoise.close_connections()
+    await cache_manager.disconnect()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+### 环境变量配置
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=True,
+        extra="ignore",
+    )
+
+    # 数据库配置 - 从环境变量读取
+    DB_ENGINE: str = "postgres"
+    DB_HOST: str
+    DB_PORT: int = 5432
+    DB_USER: str
+    DB_PASSWORD: str
+    DB_NAME: str
+
+    @property
+    def TORTOISE_ORM(self) -> dict:
+        """动态生成 Tortoise ORM 配置"""
+        return {
+            "connections": {
+                "default": {
+                    "engine": f"tortoise.backends.{self.DB_ENGINE}",
+                    "credentials": {
+                        "host": self.DB_HOST,
+                        "port": self.DB_PORT,
+                        "user": self.DB_USER,
+                        "password": self.DB_PASSWORD,
+                        "database": self.DB_NAME,
+                        # 连接池精细化管理
+                        "minsize": 5,          # 最小连接数
+                        "maxsize": 20,         # 最大连接数
+                        "max_queries": 50000,  # 连接回收阈值
+                        "max_inactive_connection_lifetime": 300,  # 最大空闲时间(秒)
+                        "timeout": 60,         # 连接超时
+                        "command_timeout": 60, # 命令超时
+                    },
+                }
+            },
+            "apps": {
+                "models": {
+                    "models": ["app.models"],
+                    "default_connection": "default",
+                }
+            },
+            "use_tz": False,
+            "timezone": "Asia/Shanghai",
+        }
+
+settings = Settings()
+```
+
+### 连接池配置要点
+
+| 参数 | 说明 | 建议值 | 适用场景 |
+|-----|-----|-------|---------|
+| `minsize` | 最小连接数 | 5-10 | 保持基础连接池 |
+| `maxsize` | 最大连接数 | 20-50 | 根据并发量调整 |
+| `max_queries` | 连接回收阈值 | 50000 | 防止长连接问题 |
+| `max_inactive_connection_lifetime` | 最大空闲时间 | 300 | 自动回收空闲连接 |
+| `timeout` | 连接超时 | 60 | 避免连接挂起 |
+
+## 模型定义
+
+### 基础模型
+
+```python
+from tortoise.models import Model
+from tortoise import fields
+
+class User(Model):
+    id = fields.IntField(pk=True)
+    username = fields.CharField(max_length=50, unique=True, index=True)
+    email = fields.CharField(max_length=255, unique=True, index=True)
+    is_active = fields.BooleanField(default=True)
+    created_at = fields.DatetimeField(auto_now_add=True)
+    updated_at = fields.DatetimeField(auto_now=True)
+
+    class Meta:
+        table = "users"
+        table_description = "用户信息表"
+```
+
+### 逻辑外键关系(无物理约束)
+
+```python
+class Author(Model):
+    id = fields.IntField(pk=True)
+    name = fields.CharField(max_length=100)
+    email = fields.CharField(max_length=255, unique=True)
+
+class Book(Model):
+    id = fields.IntField(pk=True)
+    title = fields.CharField(max_length=200)
+    # 逻辑外键:显式声明字段 + 索引
+    author_id = fields.IntField(index=True)
+    author = fields.ForeignKeyField(
+        'models.Author',
+        related_name='books',
+        db_constraint=False  # 禁用数据库外键约束
+    )
+
+    class Meta:
+        indexes = [
+            ("author_id", "created_at"),  # 复合索引
+        ]
+```
+
+**关键点**:
+- `db_constraint=False` 禁用物理外键,但 ORM 关系完全可用
+- 逻辑外键字段必须手动创建索引以保障查询性能
+- `prefetch_related`、双下划线查询等特性正常工作
+
+### 一对一关系
+
+```python
+class Profile(Model):
+    id = fields.IntField(pk=True)
+    bio = fields.TextField()
+    user = fields.OneToOneField(
+        'models.User',
+        related_name='profile',
+        db_constraint=False
+    )
+```
+
+### 多对多关系
+
+```python
+class Student(Model):
+    id = fields.IntField(pk=True)
+    name = fields.CharField(max_length=255)
+    courses = fields.ManyToManyField(
+        'models.Course',
+        related_name='students',
+        through='student_course',
+        db_constraint=False  # 禁用中间表的外键约束
+    )
+
+class Course(Model):
+    id = fields.IntField(pk=True)
+    title = fields.CharField(max_length=255)
+```
+
+### 自定义中间表
+
+```python
+class PostTag(Model):
+    id = fields.IntField(pk=True)
+    post = fields.ForeignKeyField('models.Post', related_name='post_tags')
+    tag = fields.ForeignKeyField('models.Tag', related_name='tag_posts')
+    created_at = fields.DatetimeField(auto_now_add=True)
+
+    class Meta:
+        unique_together = (("post", "tag"),)
+```
+
+## 查询优化
+
+### 避免隐藏的 N+1 查询
+
+```python
+# ❌ 错误：N+1 查询
+authors = await Author.all()
+for author in authors:
+    books = await author.books.all()  # 每次循环都查询数据库
+
+# ✅ 正确：预加载关联数据
+authors = await Author.all().prefetch_related('books')
+for author in authors:
+    for book in author.books:  # 内存中访问,无额外查询
+        print(book.title)
+```
+
+### 字段选择优化
+
+```python
+# 只获取需要的字段,减少网络传输和内存占用
+user_list = await User.filter(is_active=True).values('id', 'username', 'email')
+
+# 获取列表页所需字段 + 关联数据
+users = await User.all().values(
+    'id', 'username', 'email',
+    profile__bio,  # 关联字段
+    dept__name     # 跨表查询
+)
+
+# values_list: 返回元组列表
+user_ids = await User.all().values_list('id', flat=True)
+
+# 配合 prefetch_related 使用
+users = await User.all().prefetch_related('profile').values('id', 'username', 'profile__bio')
+```
+
+### select_related vs prefetch_related
+
+| 方法 | 适用关系 | 查询方式 | 使用场景 |
+|-----|---------|---------|---------|
+| `select_related` | 一对一、多对一 | JOIN 查询 | 获取单个关联对象 |
+| `prefetch_related` | 一对多、多对多 | 独立查询 | 获取关联对象集合 |
+
+```python
+# select_related: 一对一/多对一关系
+user = await User.get(id=1).select_related('profile')
+print(user.profile.bio)  # 无额外查询
+
+# prefetch_related: 一对多/多对多关系
+user = await User.get(id=1).prefetch_related('posts')
+for post in user.posts:  # 无额外查询
+    print(post.title)
+
+# 嵌套使用
+author = await Author.get(id=1).prefetch_related('books__tags')
+```
+
+### 复杂查询
+
+```python
+from tortoise.expressions import Q
+from tortoise.functions import Count, Avg, Sum
+
+# 组合条件
+active_users = await User.filter(
+    Q(is_active=True) & Q(created_at__gte=datetime(2024, 1, 1))
+).prefetch_related('posts')
+
+# 聚合查询
+user_stats = await User.annotate(
+    post_count=Count('posts'),
+    avg_post_length=Avg('posts__content__length')
+).filter(post_count__gt=5)
+
+# 分组统计
+dept_stats = await User.annotate(
+    user_count=Count('id')
+).group_by('dept_id').values('dept_id', 'user_count')
+```
+
+### 分页查询
+
+```python
+async def get_paginated_users(page: int = 1, page_size: int = 20):
+    offset = (page - 1) * page_size
+    users = await User.all().offset(offset).limit(page_size).prefetch_related('profile')
+    total_count = await User.all().count()
+    return users, total_count
+```
+
+## 事务管理
+
+### 上下文管理器
+
+```python
+from tortoise import transactions
+
+async def transfer_points(from_user_id: int, to_user_id: int, points: int):
+    async with transactions.in_transaction() as connection:
+        from_user = await User.get(id=from_user_id).using_db(connection)
+        if from_user.points < points:
+            raise ValueError("积分不足")
+        from_user.points -= points
+        await from_user.save(using_db=connection)
+
+        to_user = await User.get(id=to_user_id).using_db(connection)
+        to_user.points += points
+        await to_user.save(using_db=connection)
+
+        await Transaction.create(
+            from_user_id=from_user_id,
+            to_user_id=to_user_id,
+            points=points,
+            using_db=connection
+        )
+```
+
+### 装饰器
+
+```python
+from tortoise.transactions import atomic
+
+@atomic()
+async def create_user_with_profile(username: str, email: str, profile_data: dict):
+    user = await User.create(username=username, email=email)
+    profile = await UserProfile.create(user=user, **profile_data)
+    return user, profile
+```
+
+### 无物理外键的数据一致性
+
+```python
+@atomic()
+async def create_book_safely(title: str, author_id: int):
+    """创建书籍前验证作者存在性"""
+    author_exists = await Author.filter(id=author_id).exists()
+    if not author_exists:
+        raise ValueError(f"Author {author_id} does not exist")
+    return await Book.create(title=title, author_id=author_id)
+
+@atomic()
+async def delete_author_cascade(author_id: int):
+    """
+    应用层级联删除
+    注意:这是应用层实现的级联删除,而非数据库级联
+    """
+    await Book.filter(author_id=author_id).delete()
+    await Author.filter(id=author_id).delete()
+```
+
+## 性能优化
+
+### 批量操作
+
+```python
+# 批量创建
+users_data = [{"username": f"user{i}", "email": f"user{i}@example.com"} for i in range(1000)]
+users = [User(**data) for data in users_data]
+await User.bulk_create(users, batch_size=100)
+
+# 批量更新
+await User.filter(is_active=False).update(is_active=True)
+
+# 批量删除
+await User.filter(last_login__lt=datetime(2023, 1, 1)).delete()
+```
+
+### 索引策略
+
+```python
+class OptimizedModel(Model):
+    id = fields.IntField(pk=True)
+    name = fields.CharField(max_length=100, index=True)
+    category = fields.CharField(max_length=50, index=True)
+    status = fields.CharField(max_length=20, index=True)
+    priority = fields.IntField()
+    created_at = fields.DatetimeField(auto_now_add=True, index=True)
+
+    class Meta:
+        indexes = [
+            ("category", "created_at"),
+            ("status", "priority", "created_at")
+        ]
+        unique_together = (("field1", "field2"),)
+```
+
+### 性能监控与日志
+
+#### 开启查询日志(开发/调试)
+
+```python
+import logging
+from log import logger
+
+# 开发环境启用 SQL 日志
+if settings.APP_ENV == "development":
+    logging.basicConfig(level=logging.DEBUG)
+    tortoise_logger = logging.getLogger("tortoise")
+    tortoise_logger.setLevel(logging.DEBUG)
+```
+
+#### 慢查询监控
+
+```python
+import time
+from functools import wraps
+from log import logger
+
+def slow_query_threshold(threshold_seconds: float = 1.0):
+    """慢查询监控装饰器"""
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            start_time = time.time()
+            try:
+                result = await func(*args, **kwargs)
+                return result
+            finally:
+                elapsed_time = time.time() - start_time
+                if elapsed_time > threshold_seconds:
+                    logger.warning(
+                        f"慢查询检测: {func.__name__} "
+                        f"耗时 {elapsed_time:.2f}s (阈值: {threshold_seconds}s)"
+                    )
+        return wrapper
+    return decorator
+
+@slow_query_threshold(threshold_seconds=1.0)
+async def get_complex_data():
+    return await User.all().prefetch_related('posts', 'profile')
+```
+
+#### 缓存策略
+
+```python
+from functools import wraps
+from utils.cache import cache_manager
+
+def cache_result(ttl: int = 3600):
+    """缓存查询结果"""
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # 生成缓存键
+            cache_key = f"{func.__name__}:{str(args)}:{str(kwargs)}"
+            # 尝试从缓存获取
+            cached = await cache_manager.get(cache_key)
+            if cached:
+                return cached
+
+            # 执行查询并缓存结果
+            result = await func(*args, **kwargs)
+            await cache_manager.set(cache_key, result, ttl)
+            return result
+        return wrapper
+    return decorator
+
+@cache_result(ttl=600)
+async def get_user_roles(user_id: int):
+    user = await User.get(id=user_id).prefetch_related('roles')
+    return user.roles
+```
+
+## FastAPI 集成
+
+### 基本配置
+
+```python
+from fastapi import FastAPI
+from tortoise.contrib.fastapi import register_tortoise
+
+app = FastAPI()
+
+register_tortoise(
+    app,
+    db_url="sqlite://db.sqlite3",
+    modules={"models": ["app.models"]},
+    generate_schemas=False,  # 生产环境设为 False
+    add_exception_handlers=True,
+)
+```
+
+### Schema 与模型分离
+
+#### 目录结构
+```
+app/
+├── models/
+│   ├── __init__.py
+│   └── user.py       # Tortoise 模型
+├── schemas/
+│   ├── __init__.py
+│   └── user.py       # Pydantic Schema
+└── v1/
+    └── user.py       # 路由
+```
+
+#### schemas/user.py
+```python
+from tortoise.contrib.pydantic import pydantic_model_creator
+from app.models.user import User
+
+# 使用 pydantic_model_creator
+UserPydantic = pydantic_model_creator(User, name="User")
+UserInPydantic = pydantic_model_creator(User, name="UserIn", exclude_readonly=True)
+
+# 或自定义 Schema
+from pydantic import BaseModel, EmailStr
+
+class UserCreate(BaseModel):
+    username: str
+    email: EmailStr
+    password: str
+
+class UserResponse(BaseModel):
+    id: int
+    username: str
+    email: str
+    is_active: bool
+
+    class Config:
+        from_attributes = True
+```
+
+#### 路由中使用
+```python
+from app.schemas.user import UserCreate, UserResponse
+from app.models.user import User
+
+@app.post("/users/", response_model=UserResponse)
+async def create_user(user: UserCreate):
+    user_obj = await User.create(**user.model_dump())
+    return await UserResponse.from_orm(user_obj)
+
+@app.get("/users/{user_id}/", response_model=UserResponse)
+async def get_user(user_id: int):
+    user = await User.get(id=user_id).prefetch_related('posts', 'profile')
+    return await UserResponse.from_orm(user)
+```
+
+### 健康检查
+
+```python
+@app.get("/health")
+async def health_check():
+    """数据库健康检查"""
+    try:
+        await User.all().first()
+        return {"status": "healthy", "database": "connected"}
+    except Exception as e:
+        return {"status": "unhealthy", "error": str(e)}
+```
+
+## 测试
+
+### 测试配置
+
+```python
+import pytest
+from tortoise.contrib.test import initializer, finalizer
+
+@pytest.fixture(scope="module")
+async def database():
+    initializer(["app.models"], db_url="sqlite://:memory:")
+    yield
+    finalizer()
+
+@pytest.mark.asyncio
+async def test_user_creation(database):
+    user = await User.create(username="testuser", email="test@example.com")
+    assert user.id is not None
+```
+
+### 事务测试
+
+```python
+@pytest.mark.asyncio
+async def test_transaction_rollback(database):
+    try:
+        async with transactions.in_transaction():
+            await User.create(username="testuser", email="test@example.com")
+            raise ValueError("强制回滚")
+    except ValueError:
+        pass
+
+    user_exists = await User.filter(username="testuser").exists()
+    assert not user_exists
+```
+
+## 安全最佳实践
+
+### 环境变量管理
+
+```bash
+# .env 文件 (不提交到版本控制)
+DB_ENGINE=postgres
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=your_user
+DB_PASSWORD=your_secure_password
+DB_NAME=your_database
+SECRET_KEY=your_very_long_and_secure_secret_key_at_least_32_chars
+```
+
+### 生产环境检查
+
+```python
+from pydantic import field_validator
+
+class Settings(BaseSettings):
+    # ...其他配置
+
+    @field_validator("DB_PASSWORD")
+    @classmethod
+    def validate_db_password(cls, v):
+        """生产环境必须设置数据库密码"""
+        if cls.APP_ENV == "production" and not v:
+            raise ValueError("生产环境必须设置数据库密码")
+        return v
+
+    @field_validator("SECRET_KEY")
+    @classmethod
+    def validate_secret_key(cls, v):
+        """SECRET_KEY 强度验证"""
+        if len(v) < 32:
+            raise ValueError("SECRET_KEY 长度至少 32 字符")
+        return v
+```
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|-----|-----|---------|
+| N+1 查询 | 循环中执行数据库查询 | 使用 `prefetch_related` 预加载 |
+| 连接池耗尽 | 连接未正确关闭 | 检查连接池配置和应用关闭逻辑 |
+| 数据不一致 | 跨操作无事务保护 | 使用 `@atomic()` 或 `in_transaction()` |
+| 关联查询失效 | 逻辑外键未正确定义 | 确保 `related_name` 和关系字段正确 |
+| 查询性能差 | 获取了不需要的字段 | 使用 `values/values_list` 只获取必要字段 |
+| 内存占用高 | 一次性加载大量数据 | 使用分页或批量处理 |
+
+## 关键要点
+
+1. **异步优先**: 所有数据库操作必须使用 `async/await`
+2. **预加载优化**: 使用 `prefetch_related` 避免 N+1 查询
+3. **字段选择**: 使用 `values/values_list` 减少数据传输
+4. **事务保护**: 复杂操作使用事务保证原子性
+5. **逻辑外键**: `db_constraint=False` 不影响 ORM 关系功能
+6. **索引策略**: 为逻辑外键和高频查询字段创建索引
+7. **批量操作**: 大量数据使用 `bulk_create` 等批量方法
+8. **生命周期**: 使用 lifespan 事件管理应用生命周期
+9. **安全配置**: 使用环境变量管理敏感信息
+10. **监控日志**: 开发环境启用 SQL 日志,生产环境监控慢查询

package/dist-repo/fastapi-backend/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+
+[*.py]
+indent_style = space     # 用空格（PEP 8 要求）
+indent_size = 4          # 4 空格缩进（PEP 8 强制）
+trim_trailing_whitespace = true  # 删除行尾空格（PEP 8 建议）
+insert_final_newline = true      # 文件末尾保留空行（PEP 8 建议）
+max_line_length = 88     # 行宽（black 默认值，PEP 8 建议 79）