labweb/web/ws/backend/CONTRIBUTING.md

开发指南

快速开始

本地开发

# 1. 进入后端目录
cd /vol1/1000/docker_server/traefik/web/ws/backend

# 2. 使用启动脚本（自动创建虚拟环境、安装依赖）
./start.sh

# 或者手动启动
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

访问：

• API 文档: http://localhost:8000/docs
• 健康检查: http://localhost:8000/health

Docker 开发

cd /vol1/1000/docker_server/traefik/web/ws

# 构建镜像
docker compose build backend

# 启动服务
docker compose up -d backend

# 查看日志
docker compose logs -f backend

# 进入容器
docker compose exec backend bash

开发流程

1. 添加新的 API 端点

示例：添加实验数据 API

# 1. 创建端点文件
touch app/api/v1/endpoints/experiments.py

# app/api/v1/endpoints/experiments.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/")
async def get_experiments():
    """获取实验列表"""
    return {"experiments": []}

@router.get("/{experiment_id}")
async def get_experiment(experiment_id: str):
    """获取实验详情"""
    return {"id": experiment_id}

# 2. 在 app/api/v1/router.py 中注册
from app.api.v1.endpoints import experiments

api_router.include_router(
    experiments.router, 
    prefix="/experiments", 
    tags=["experiments"]
)

2. 添加数据模型

# 创建模型文件
touch app/models/experiment.py

# app/models/experiment.py
from sqlalchemy import Column, String, Integer, DateTime
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class Experiment(Base):
    __tablename__ = "experiments"
    
    id = Column(Integer, primary_key=True)
    name = Column(String(200))
    description = Column(String(1000))
    created_at = Column(DateTime)

3. 添加 Pydantic 模式

# 创建模式文件
touch app/schemas/experiment.py

# app/schemas/experiment.py
from pydantic import BaseModel
from datetime import datetime
from typing import Optional

class ExperimentBase(BaseModel):
    name: str
    description: Optional[str] = None

class ExperimentCreate(ExperimentBase):
    pass

class ExperimentResponse(ExperimentBase):
    id: int
    created_at: datetime
    
    class Config:
        from_attributes = True

4. 添加业务逻辑

# 创建服务文件
touch app/services/experiment_service.py

# app/services/experiment_service.py
from sqlalchemy.orm import Session
from app.models.experiment import Experiment
from app.schemas.experiment import ExperimentCreate

async def create_experiment(db: Session, data: ExperimentCreate):
    """创建实验"""
    experiment = Experiment(**data.dict())
    db.add(experiment)
    db.commit()
    db.refresh(experiment)
    return experiment

代码规范

Python 风格

• 遵循 PEP 8 规范
• 使用类型提示
• 函数添加文档字符串

async def get_strain_detail(strain_id: str) -> dict:
    """
    获取菌种详情
    
    Args:
        strain_id: 菌种 ID
        
    Returns:
        dict: 菌种详细信息
        
    Raises:
        HTTPException: 菌种不存在时
    """
    pass

命名规范

• 文件名：snake_case.py
• 类名：PascalCase
• 函数名：snake_case
• 常量：UPPER_CASE

目录组织

app/
├── api/v1/endpoints/    # 按功能模块组织
│   ├── strains.py       # 菌种相关
│   ├── genes.py         # 基因相关
│   └── upload.py        # 上传相关
├── models/              # 数据库模型
├── schemas/             # 数据验证模式
└── services/            # 业务逻辑

测试

单元测试

# 安装测试依赖
pip install pytest pytest-asyncio httpx

# 运行测试
pytest

API 测试

# 使用测试脚本
./test_api.sh

# 或使用 curl
curl http://localhost:8000/health

数据库迁移

# 安装 alembic
pip install alembic

# 初始化
alembic init alembic

# 创建迁移
alembic revision --autogenerate -m "Add experiments table"

# 执行迁移
alembic upgrade head

# 回滚
alembic downgrade -1

调试技巧

1. 日志输出

import logging

logger = logging.getLogger(__name__)

@router.get("/debug")
async def debug_endpoint():
    logger.info("Debug endpoint called")
    logger.debug(f"Data: {data}")
    return {"status": "ok"}

2. 断点调试

# 使用 pdb
import pdb; pdb.set_trace()

# 或使用 breakpoint()
breakpoint()

3. 查看 SQL 查询

# 在配置中启用 SQL 日志
DATABASE_URL = "postgresql://...?echo=true"

常见问题

Q: 导入错误？

确保在项目根目录运行，并使用正确的 Python 路径：

export PYTHONPATH=/vol1/1000/docker_server/traefik/web/ws/backend:$PYTHONPATH

Q: 数据库连接失败？

检查 .env 文件中的 DATABASE_URL 配置。

Q: CORS 错误？

在 app/core/config.py 中添加允许的源。

部署检查清单

• 修改生产环境 SECRET_KEY
• 配置正确的 DATABASE_URL
• 更新 ALLOWED_ORIGINS
• 运行数据库迁移
• 测试所有 API 端点
• 配置日志记录
• 设置监控和告警
• 备份数据库

贡献流程

1. 创建功能分支
2. 开发并测试
3. 提交代码（commit message 规范）
4. 提交 Pull Request
5. Code Review
6. 合并到主分支

联系方式

如有问题，请联系开发团队。