13 KiB

Raw Permalink Blame History

Backend.md 规范增强

日期: 2026-01-28
类型: 文档增强
影响范围: .claude/skills/jointo-tech-stack/references/backend.md

概述

对 backend.md 规范文档进行全面增强，补充缺失的章节和最佳实践，提升文档完整性和实用性。

优化内容

第一批：高优先级优化（已完成）

1. 补充目录项 - "时间与时区规范"

问题: 目录中缺少"时间与时区规范"章节的链接。

修复: 在目录中添加：

- [时间与时区规范](#时间与时区规范)

影响: 改善文档导航体验。

2. 补充统一响应格式规范

问题: 错误处理章节不完整，缺少详细的响应格式规范。

修复: 补充完整的统一响应格式规范（RFC-135）：

新增内容:

ApiResponse 泛型类定义
success_response 和 error_response 工厂方法
完整的自定义异常类（包括 InsufficientCreditsError）
全局异常处理器（HTTP 异常、参数验证错误、未捕获异常）
HTTP 状态码规范表格
响应示例（成功、错误、参数验证错误）

示例代码:

class ApiResponse(BaseModel, Generic[T]):
    """统一 API 响应格式"""
    success: bool
    code: int
    message: str
    data: Optional[T]
    timestamp: str

@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "success": False,
            "code": exc.status_code,
            "message": exc.detail,
            "data": None,
            "timestamp": datetime.now(timezone.utc).isoformat()
        }
    )

价值: 确保所有 API 响应格式一致，符合前后端约定。

3. 补充 Relationship 配置说明

问题: Repository 示例中使用了 FolderMember，但没有说明 Relationship 配置。

修复: 在 check_user_permission 方法后添加注意事项：

# 注意：FolderMember 需要在 Model 中配置 Relationship
# 详见 database.md > Relationship 配置规范

新增注意事项:

Relationship 配置：所有关联关系必须在 Model 层使用 Relationship 配置
引用完整性：Repository 层负责验证引用完整性
批量验证：对于批量操作，使用 batch_exists 方法优化性能

价值: 引导开发者查阅完整的 Relationship 配置规范。

第二批：中优先级优化（已完成）

4. 补充 UUID v7 生成规范

问题: 项目结构中提到了 utils/id_generator.py，但没有展示如何使用。

修复: 在"异步编程"章节后添加完整的 UUID v7 生成规范：

新增章节:

核心原则（性能、扩展性、一致性、可测试性）
UUID v7 生成器实现
Model 中使用示例
数据库迁移示例
禁止使用数据库函数的说明

示例代码:

# utils/id_generator.py
from uuid import UUID
from uuid6 import uuid7

def generate_uuid() -> UUID:
    """生成 UUID v7（时间排序）"""
    return uuid7()

# Model 中使用
class User(SQLModel, table=True):
    user_id: UUID = Field(
        sa_column=Column(
            PG_UUID(as_uuid=True),
            primary_key=True,
            default=generate_uuid  # 应用层生成
        )
    )

价值: 提供完整的 UUID v7 实现指南，确保开发者正确使用。

5. 补充事务处理规范

问题: Service 层示例中没有展示事务处理。

修复: 新增"事务处理"章节：

新增内容:

Service 层事务管理（使用 async with self.session.begin()）
创建文件夹并添加成员的事务示例
批量移动项目的事务示例
事务最佳实践（4 条）

示例代码:

async def create_folder_with_members(
    self,
    user_id: str,
    folder_data: FolderCreate,
    member_ids: List[str]
) -> Folder:
    """创建文件夹并添加成员（事务处理）"""
    async with self.session.begin():
        # 1. 创建文件夹
        folder = Folder(...)
        self.session.add(folder)
        await self.session.flush()  # 获取 folder.id
        
        # 2. 添加成员
        for member_id in member_ids:
            member = FolderMember(...)
            self.session.add(member)
        
        # 3. 记录操作日志
        log = AuditLog(...)
        self.session.add(log)
        
        # 事务自动提交
    
    return folder

最佳实践:

使用 async with self.session.begin() 自动管理事务
使用 flush() 而非 commit() 在事务内获取自增 ID
异常自动回滚
避免嵌套事务

价值: 确保数据一致性，避免部分成功的脏数据。

6. 补充批量操作规范

问题: Repository 和 Service 层都缺少批量操作的最佳实践。

修复: 新增"批量操作"章节：

新增内容:

Repository 层批量查询（batch_get_by_ids, batch_exists, batch_update）
Service 层批量操作（batch_delete_folders）
批量操作最佳实践（4 条）

示例代码:

# Repository 层
async def batch_exists(
    self,
    folder_ids: List[UUID]
) -> Dict[UUID, bool]:
    """批量检查文件夹是否存在"""
    result = await self.session.execute(
        select(Folder.id).where(
            Folder.id.in_(folder_ids),
            Folder.deleted_at.is_(None)
        )
    )
    existing_ids = {row[0] for row in result.all()}
    return {id: id in existing_ids for id in folder_ids}

# Service 层
async def batch_delete_folders(
    self,
    user_id: str,
    folder_ids: List[UUID]
) -> int:
    """批量删除文件夹（软删除）"""
    # 1. 批量验证权限
    permissions = await self.repository.batch_check_permissions(...)
    
    # 2. 批量软删除
    async with self.session.begin():
        deleted_count = await self.repository.batch_soft_delete(folder_ids)
    
    return deleted_count

最佳实践:

使用 IN 查询减少数据库往返次数
分批处理大批量操作（如每批 100 条）
返回详细结果（成功/失败的 ID 列表）
事务保护确保原子性

价值: 提升批量操作性能，减少数据库压力。

7. 补充软删除规范

问题: BaseModel 中有 deleted_at 字段，但没有展示如何实现软删除。

修复: 新增"软删除规范"章节：

新增内容:

Model 层软删除字段定义
Repository 层软删除方法（soft_delete, restore, permanent_delete）
Service 层软删除业务逻辑（delete_folder, restore_folder, get_deleted_folders）
软删除最佳实践（4 条）
定时任务清理过期软删除记录

示例代码:

# Repository 层
async def get_by_id(
    self,
    folder_id: UUID,
    include_deleted: bool = False
) -> Optional[Folder]:
    """根据 ID 获取文件夹（默认排除软删除）"""
    query = select(Folder).where(Folder.id == folder_id)
    
    if not include_deleted:
        query = query.where(Folder.deleted_at.is_(None))
    
    result = await self.session.execute(query)
    return result.scalar_one_or_none()

async def soft_delete(self, folder_id: UUID) -> None:
    """软删除文件夹"""
    folder = await self.get_by_id(folder_id)
    if not folder:
        raise NotFoundError("文件夹不存在")
    
    folder.deleted_at = datetime.now(timezone.utc)
    await self.session.commit()

# 定时任务
@celery_app.task
async def cleanup_old_deleted_records():
    """清理超过 30 天的软删除记录"""
    cutoff_date = datetime.now(timezone.utc) - timedelta(days=30)
    # ... 清理逻辑

最佳实践:

默认排除软删除：所有查询默认排除 deleted_at IS NOT NULL 的记录
提供恢复功能：允许用户恢复误删除的数据
定期清理：使用定时任务清理超过 30 天的软删除记录
级联软删除：删除父记录时级联软删除子记录

价值: 提供完整的软删除实现方案，保护用户数据安全。

第三批：项目结构修正和补充（已完成）

8. 修正项目结构 - Alembic 迁移目录

问题: 项目结构中显示的是旧的 app/migrations/ 目录，实际项目使用 Alembic。

修复: 更新项目结构，明确 Alembic 迁移目录位置：

server/alembic/              # Alembic 迁移目录
├── versions/                # 迁移脚本
│   ├── 20260127_1931_xxx_initial_schema.py
│   └── 20260128_2100_xxx_create_attachments.py
├── env.py                   # Alembic 环境配置
└── script.py.mako           # 迁移脚本模板

server/scripts/              # 辅助脚本
└── db_migrate.py            # 数据库迁移工具

新增说明:

项目使用 Alembic 进行数据库迁移
server/app/migrations/ 是旧的迁移脚本（已废弃）
迁移文件命名格式：YYYYMMDD_HHMM_<revision>_<description>.py

价值: 避免开发者使用错误的迁移目录。

9. 补充 tasks 目录和 Celery 异步任务规范

问题: 项目结构中缺少 tasks/ 目录，且没有 Celery 使用规范。

修复: 补充完整的 Celery 异步任务规范：

新增项目结构:

├── tasks/                   # Celery 异步任务
│   ├── __init__.py
│   ├── celery_app.py        # Celery 应用配置
│   ├── ai_tasks.py          # AI 相关任务
│   ├── credit_tasks.py      # 积分相关任务
│   ├── export_tasks.py      # 导出任务
│   ├── cleanup.py           # 清理任务
│   └── maintenance_tasks.py # 维护任务

新增章节: "Celery 异步任务"（~200 行）

新增内容:

Celery 应用配置（broker、backend、超时设置）
定义异步任务（@shared_task 装饰器）
定时任务配置（beat_schedule）
Service 层调用异步任务
任务监控和管理
Celery 最佳实践（6 条）
Docker Compose 配置
常用命令

示例代码:

@shared_task(name='credit.expire_pending_consumptions')
async def expire_pending_consumptions():
    """过期未完成的积分消耗（每小时执行）"""
    async with get_session() as session:
        service = CreditService(session)
        expired_count = await service.expire_pending_consumptions(
            timeout_hours=24
        )
        logger.info(f"过期了 {expired_count} 条待处理的积分消耗记录")
        return expired_count

# Service 层调用
send_low_balance_notification.delay(
    str(user_id),
    user_credits.available_credits
)

最佳实践:

任务幂等性：任务应该是幂等的，多次执行结果相同
任务超时：设置合理的超时时间
任务重试：配置重试策略
任务监控：使用 Flower 监控任务执行状态
错误处理：捕获异常并记录日志
资源清理：任务结束后清理资源

价值: 提供完整的异步任务开发指南，确保任务可靠执行。

优化统计

批次	优先级	优化项数量	新增代码行数	新增章节
第一批	高	3	~150	0（增强现有章节）
第二批	中	4	~400	4（UUID v7、事务、批量、软删除）
第三批	补充	2	~200	1（Celery 异步任务）
总计	-	9	~750	5

文档结构变化

修改前

## 目录
- [核心库](#核心库)
- [项目结构](#项目结构)
- [异步编程](#异步编程)
- [仓储模式](#仓储模式)
- [依赖注入](#依赖注入)
- [错误处理](#错误处理)
- [日志规范](#日志规范)

修改后

## 目录
- [核心库](#核心库)
- [项目结构](#项目结构)
- [异步编程](#异步编程)
- [UUID v7 生成规范](#uuid-v7-生成规范)  <!-- 新增 -->
- [仓储模式](#仓储模式)
- [依赖注入](#依赖注入)
- [错误处理](#错误处理)
- [日志规范](#日志规范)
- [时间与时区规范](#时间与时区规范)  <!-- 新增 -->
- [事务处理](#事务处理)  <!-- 新增 -->
- [批量操作](#批量操作)  <!-- 新增 -->
- [软删除规范](#软删除规范)  <!-- 新增 -->

规范完整性提升

维度	优化前	优化后	提升
章节数量	7	11	+57%
代码示例	~20	~35	+75%
最佳实践	~5	~20	+300%
错误示例	~3	~8	+167%
交叉引用	0	3	-

后续建议

低优先级优化（可选）

以下优化项可根据实际需求决定是否补充：

分页规范: 统一的分页参数和响应格式
缓存策略: Redis 使用规范和缓存键命名
性能优化: 数据库查询优化、N+1 问题解决
测试规范: 单元测试和集成测试最佳实践

这些内容可以作为独立文档或在后续迭代中补充。

总结

本次优化全面增强了 backend.md 规范文档，补充了 7 个关键优化项，新增 4 个重要章节，提供了 ~550 行高质量代码示例和最佳实践。文档现在涵盖了从 UUID 生成、事务处理、批量操作到软删除的完整开发流程，为开发者提供了清晰、实用的技术指南。

13 KiB Raw Permalink Blame History

Backend.md 规范增强

概述

优化内容

第一批：高优先级优化（已完成）

1. 补充目录项 - "时间与时区规范"

2. 补充统一响应格式规范

3. 补充 Relationship 配置说明

第二批：中优先级优化（已完成）

4. 补充 UUID v7 生成规范

5. 补充事务处理规范

6. 补充批量操作规范

7. 补充软删除规范

第三批：项目结构修正和补充（已完成）

8. 修正项目结构 - Alembic 迁移目录

9. 补充 tasks 目录和 Celery 异步任务规范

优化统计

文档结构变化

修改前

修改后

规范完整性提升

相关文档

后续建议

低优先级优化（可选）

总结

13 KiB

Raw Permalink Blame History