Skip to content

Developer's

Jump to bottom
n0pashkov edited this page Mar 2, 2025 · 1 revision

Руководство разработчика

Это руководство предназначено для разработчиков, которые хотят внести свой вклад в проект системы заявок на ремонт техники или расширить его функциональность.

Структура проекта

ticket-system/
├── alembic/                  # Миграции базы данных
│   ├── versions/             # Версии миграций
│   ├── env.py                # Окружение Alembic
│   └── alembic.ini           # Конфигурация Alembic
├── app/                      # Основной код приложения
│   ├── api/                  # API эндпоинты
│   │   ├── deps.py           # Зависимости для API (авторизация и т.д.)
│   │   ├── endpoints/        # Обработчики API эндпоинтов
│   │   └── router.py         # Маршрутизация API
│   ├── core/                 # Ядро приложения
│   │   ├── config.py         # Конфигурация приложения
│   │   └── security.py       # Функции безопасности (JWT, пароли)
│   ├── db/                   # Работа с базой данных
│   │   ├── base_class.py     # Базовый класс для моделей
│   │   └── database.py       # Настройка подключения к БД
│   ├── models/               # Модели SQLAlchemy
│   │   ├── models.py         # Модель пользователя
│   │   └── ticket.py         # Модели заявок и комментариев
│   ├── schemas/              # Схемы Pydantic
│   │   ├── comment.py        # Схемы для комментариев
│   │   ├── schemas.py        # Общие схемы
│   │   ├── ticket.py         # Схемы для заявок
│   │   └── user.py           # Схемы для пользователей
│   ├── initial_data.py       # Скрипт для создания начальных данных
│   └── main.py               # Точка входа в приложение
├── tests/                    # Тесты
│   ├── conftest.py           # Конфигурация тестов
│   ├── test_auth.py          # Тесты аутентификации
│   ├── test_comments.py      # Тесты комментариев
│   ├── test_tickets.py       # Тесты заявок
│   └── test_users.py         # Тесты пользователей
├── .env                      # Переменные окружения (не в репозитории)
├── .gitignore                # Игнорируемые файлы Git
├── requirements.txt          # Зависимости проекта
└── README.md                 # Описание проекта

Настройка окружения разработки

Настройка pre-commit хуков

Для обеспечения качества кода рекомендуется настроить pre-commit хуки:

  1. Установите pre-commit:

    pip install pre-commit

  2. Создайте файл .pre-commit-config.yaml в корне проекта:

    repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer
    -   id: check-yaml
    -   id: check-added-large-files

-   repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
    -   id: isort

-   repo: https://github.com/pycqa/flake8
    rev: 6.0.0
    hooks:
    -   id: flake8
        additional_dependencies: [flake8-docstrings]

-   repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
    -   id: black

  3. Инициализируйте pre-commit:

    pre-commit install

Настройка линтеров и форматтеров

Для поддержания единого стиля кода рекомендуется использовать:

  1. Black - форматтер кода:

    pip install black

  2. isort - сортировка импортов:

    pip install isort

  3. flake8 - линтер:

    pip install flake8

Создайте файл setup.cfg для настройки линтеров:

[flake8]
max-line-length = 88
extend-ignore = E203
exclude = .git,__pycache__,build,dist,venv,alembic

[isort]
profile = black
line_length = 88

Рабочий процесс разработки

Создание новой функциональности

  1. Создайте новую ветку от main:

    git checkout -b feature/your-feature-name

  2. Внесите необходимые изменения в код.

  3. Если изменения затрагивают модели данных, создайте миграцию:

    alembic revision --autogenerate -m "Description of changes"

  4. Напишите тесты для новой функциональности.

  5. Запустите тесты:

    pytest -v

  6. Отформатируйте код:

    black app tests
isort app tests

  7. Создайте коммит и отправьте изменения:

    git add .
git commit -m "Add your feature description"
git push origin feature/your-feature-name

  8. Создайте Pull Request в GitHub.

Исправление ошибок

  1. Создайте новую ветку от main:

    git checkout -b fix/bug-description

  2. Внесите необходимые исправления.

  3. Добавьте тест, воспроизводящий ошибку.

  4. Убедитесь, что тесты проходят:

    pytest -v

  5. Создайте коммит и отправьте изменения:

    git add .
git commit -m "Fix bug description"
git push origin fix/bug-description

  6. Создайте Pull Request в GitHub.

Добавление новых API эндпоинтов

  1. Создайте новый файл в директории app/api/endpoints/ или добавьте функцию в существующий файл.

  2. Определите функцию-обработчик с декоратором маршрута:

    from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session

from app.api import deps
from app.models import models
from app.schemas import schemas

router = APIRouter()

@router.get("/{item_id}", response_model=schemas.ItemResponse)
def read_item(
    item_id: int,
    db: Session = Depends(deps.get_db),
    current_user: models.User = Depends(deps.get_current_user),
):
    # Логика обработки запроса
    return item

  3. Добавьте маршрут в app/api/router.py:

    from app.api.endpoints import items

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

  4. Добавьте схемы Pydantic в директорию app/schemas/.

  5. Напишите тесты для нового эндпоинта.

Добавление новых моделей данных

  1. Создайте новую модель в директории app/models/:

    from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.orm import relationship

from app.db.base_class import Base

class Item(Base):
    __tablename__ = "items"
    
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    description = Column(String)
    owner_id = Column(Integer, ForeignKey("users.id"))
    
    owner = relationship("User", back_populates="items")

  2. Добавьте связь в существующие модели, если необходимо:

    # В модели User
items = relationship("Item", back_populates="owner")

  3. Создайте схемы Pydantic в директории app/schemas/:

    from pydantic import BaseModel, ConfigDict

class ItemBase(BaseModel):
    name: str
    description: str = None

class ItemCreate(ItemBase):
    pass

class ItemUpdate(BaseModel):
    name: str = None
    description: str = None

class ItemResponse(ItemBase):
    id: int
    owner_id: int
    
    model_config = ConfigDict(from_attributes=True)

  4. Создайте миграцию:

    alembic revision --autogenerate -m "Add Item model"

  5. Примените миграцию:

    alembic upgrade head

  6. Создайте API эндпоинты для работы с новой моделью.

  7. Напишите тесты для новой модели и эндпоинтов.

Советы по отладке

Логирование

Для отладки используйте логирование:

import logging

logger = logging.getLogger(__name__)

def some_function():
    logger.debug("Debug message")
    logger.info("Info message")
    logger.warning("Warning message")
    logger.error("Error message")

Отладка тестов

Для отладки тестов используйте флаг -s:

pytest -s tests/test_specific_file.py::test_specific_function

Использование pdb

Для интерактивной отладки используйте pdb:

import pdb

def some_function():
    # Код
    pdb.set_trace()  # Точка останова
    # Продолжение кода

Рекомендации по производительности

  1. Используйте индексы для часто запрашиваемых полей.

  2. Оптимизируйте запросы - используйте select_from, join и options для уменьшения количества запросов.

  3. Пагинация - всегда используйте пагинацию для больших наборов данных:

    @router.get("/", response_model=List[schemas.ItemResponse])
def read_items(
    skip: int = 0,
    limit: int = 100,
    db: Session = Depends(deps.get_db),
):
    items = db.query(models.Item).offset(skip).limit(limit).all()
    return items

  4. Кэширование - для часто запрашиваемых данных используйте кэширование (Redis, Memcached).

Рекомендации по безопасности

  1. Не храните секреты в коде - используйте переменные окружения.

  2. Валидируйте входные данные - используйте Pydantic для валидации.

  3. Проверяйте права доступа - всегда проверяйте, имеет ли пользователь права на выполнение операции.

  4. Используйте HTTPS - в продакшене всегда используйте HTTPS.

  5. Ограничивайте частоту запросов - используйте rate limiting для предотвращения DoS-атак.

Clone this wiki locally