backend-development

后端开发规范

项目结构和架构原则

后端包结构规范

• 后端包结构: 所有后端代码在backend包中，确保__init__.py存在
• 相对导入: 后端模块间使用相对导入：from .module_name import ClassName
• 启动脚本: 使用绝对导入：from backend.module_name import ClassName
• 工具脚本: 所有工具脚本放置在tools/目录下
• 启动方式: 必须在项目根目录运行 python start_game.py

开发原则

• DRY原则: 避免重复代码，提取公共逻辑
• 单一职责: 每个函数/类只完成一个明确的功能
• 对象封装: 使用数据对象简化函数参数
• 业务逻辑内聚: 相关逻辑封装在同一个类中

命名约定

• Python: 蛇形命名法 (snake_case)
• 文件命名: 小写字母加下划线，描述性命名
• 类命名: 帕斯卡命名法 (PascalCase)
• 常量命名: 全大写加下划线 (UPPER_SNAKE_CASE)

FastAPI应用架构

标准应用结构

# backend/app.py - 主应用入口
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from fastapi.staticfiles import StaticFiles
from .routes import game, admin, history, websocket, common

app = FastAPI(title="AI侦探游戏", version="1.6.0")

# 中间件配置
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 路由注册
app.include_router(game.router, prefix="/api/game", tags=["游戏"])
app.include_router(admin.router, prefix="/api/admin", tags=["管理"])
app.include_router(history.router, prefix="/api/history", tags=["历史"])
app.include_router(websocket.router, prefix="/ws", tags=["WebSocket"])
app.include_router(common.router, prefix="/api", tags=["通用"])

# 静态文件服务
app.mount("/", StaticFiles(directory="frontend", html=True), name="static")

路由模块化

# backend/routes/game.py
from fastapi import APIRouter, HTTPException, Depends
from ..models import QuestionRequest, GameResponse
from ..game_engine import GameEngine

router = APIRouter()

@router.post("/start", response_model=GameResponse)
async def start_game(case_id: str):
    """开始新游戏会话"""
    try:
        game_engine = GameEngine(case_id)
        session_id = game_engine.create_session()
        
        return GameResponse(
            success=True,
            data={"session_id": session_id, "case": game_engine.get_case_info()}
        )
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@router.post("/question", response_model=GameResponse)
async def ask_question(request: QuestionRequest):
    """向角色提问"""
    try:
        # 获取游戏会话
        if request.session_id not in game_sessions:
            raise HTTPException(status_code=404, detail="游戏会话不存在")
        
        game_engine = game_sessions[request.session_id]
        
        # 异步处理AI响应
        response = await game_engine.process_question(
            request.character_name, 
            request.question
        )
        
        return GameResponse(success=True, data=response)
        
    except Exception as e:
        logger.error(f"处理问题时出错: {str(e)}")
        return GameResponse(success=False, error=str(e))