Enhance CI workflow and implement global exception handling

.github/workflows/python-tests.yml

@@ -28,7 +28,9 @@ jobs:
         run: uv sync --frozen
 
       - name: Lint
-        run: uv run ruff check . --output-format=github
+        run: |
+          uv run ruff check . --output-format=github
 
       - name: Test with pytest
-        run: uv run pytest
+        run: |
+          uv run pytest

api/core/__init__.py

@@ -1,3 +1,3 @@
-from . import cache, quote_service, quote_repository, security
+from . import cache, config, database, security
 
-__all__ = ["cache", "quote_service", "quote_repository", "security"]
+__all__ = ["cache", "config", "database", "security"]

api/core/security.py

@@ -14,7 +14,7 @@
 )
 
 
-def verify_api_key(api_key: str = Security(api_key_header)) -> str:
+def verify_api_key(api_key: str | None = Security(api_key_header)) -> str:
     if not api_key:
         logger.warning("Chave de API ausente.")
         raise HTTPException(

api/exceptions/__init__.py

@@ -0,0 +1,3 @@
+from . import custom_exceptions, handlers
+
+__all__ = ["custom_exceptions", "handlers"]

api/exceptions/custom_exceptions.py

@@ -0,0 +1,8 @@
+class ResourceNotFoundException(Exception):
+    def __init__(self, message: str) -> None:
+        self.message = message
+
+
+class DomainValidationException(Exception):
+    def __init__(self, message: str) -> None:
+        self.message = message

api/exceptions/handlers.py

@@ -0,0 +1,67 @@
+from http import HTTPStatus
+
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError, HTTPException
+from fastapi.responses import JSONResponse
+from loguru import logger
+from schemas.error_schema import ErrorResponse
+
+from .custom_exceptions import DomainValidationException, ResourceNotFoundException
+
+
+def _json_error_response(error: ErrorResponse) -> JSONResponse:
+    return JSONResponse(
+        status_code=error.status_code, content=error.model_dump(exclude_none=True)
+    )
+
+
+async def resource_not_found_handler(
+    _: Request, exc: ResourceNotFoundException
+) -> JSONResponse:
+    return _json_error_response(
+        ErrorResponse.from_http_status(
+            status_code=HTTPStatus.NOT_FOUND, message=exc.message
+        )
+    )
+
+
+async def domain_validation_handler(
+    _: Request, exc: DomainValidationException
+) -> JSONResponse:
+    return _json_error_response(
+        ErrorResponse.from_http_status(
+            status_code=HTTPStatus.BAD_REQUEST, message=exc.message
+        )
+    )
+
+
+async def request_validation_handler(
+    _: Request, exc: RequestValidationError
+) -> JSONResponse:
+    return _json_error_response(
+        ErrorResponse.from_http_status(
+            status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
+            message="Erro de validação nos dados enviados",
+            details=exc.errors(),
+        )
+    )
+
+
+async def http_handler(_: Request, exc: HTTPException) -> JSONResponse:
+    return _json_error_response(
+        ErrorResponse.from_http_status(
+            HTTPStatus(exc.status_code),
+            message=exc.detail,
+        )
+    )
+
+
+async def global_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    logger.error(f"Erro inesperado em {request.url}: {repr(exc)}")
+
+    return _json_error_response(
+        ErrorResponse.from_http_status(
+            HTTPStatus.INTERNAL_SERVER_ERROR,
+            message="Ocorreu um erro interno no servidor. Por favor, tente novamente mais tarde.",
+        )
+    )

api/main.py

@@ -2,8 +2,21 @@
 
 from core.database import init_db
 from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError, HTTPException
 from routers.quotes import api_router as quotes_router
 
+from exceptions.custom_exceptions import (
+    DomainValidationException,
+    ResourceNotFoundException,
+)
+from exceptions.handlers import (
+    http_handler,
+    domain_validation_handler,
+    resource_not_found_handler,
+    request_validation_handler,
+    global_exception_handler,
+)
+
 tags_metadata = [
     {
         "name": "Frases",
@@ -13,7 +26,7 @@
 
 
 @asynccontextmanager
-async def lifespan(app: FastAPI):
+async def lifespan(_: FastAPI):
     await init_db()
     yield
 
@@ -47,4 +60,10 @@ async def lifespan(app: FastAPI):
     lifespan=lifespan,
 )
 
+app.add_exception_handler(HTTPException, http_handler)  # type: ignore
+app.add_exception_handler(DomainValidationException, domain_validation_handler)  # type: ignore
+app.add_exception_handler(ResourceNotFoundException, resource_not_found_handler)  # type: ignore
+app.add_exception_handler(RequestValidationError, request_validation_handler)  # type: ignore
+app.add_exception_handler(Exception, global_exception_handler)
+
 app.include_router(quotes_router, prefix="/api")

api/routers/quotes.py

@@ -28,7 +28,7 @@ async def post_quote(
     new_quote: CreateQuoteRequest,
     service: QuoteService = Depends(),
     repo: QuoteRepository = Depends(),
-    _: str = Depends(verify_api_key),
+    _: str | None = Depends(verify_api_key),
 ) -> Quote:
     return await service.create_quote(quote=new_quote, repo=repo)
 
@@ -57,7 +57,7 @@ async def get_all_quotes(
     ),
     limit: int = Query(
         default=0,
-        ge=1,
+        ge=0,
         le=100,
         description="Número máximo de citações a serem retornadas.",
     ),

api/schemas/__init__.py

@@ -1,3 +1,3 @@
-from . import pagination, quote_schema
+from . import error_schema, pagination, quote_schema
 
-__all__ = ["pagination", "quote_schema"]
+__all__ = ["error_schema", "pagination", "quote_schema"]

api/schemas/error_schema.py

@@ -0,0 +1,25 @@
+from pydantic import BaseModel
+from http import HTTPStatus
+from typing import Any, Sequence
+
+
+class ErrorResponse(BaseModel):
+    status_code: HTTPStatus
+    error: str
+    message: str
+    details: Sequence[Any] | dict[str, Any] | list[Any] | None = None
+
+    @classmethod
+    def from_http_status(
+        cls,
+        status_code: HTTPStatus,
+        message: str,
+        details: Sequence[Any] | dict[str, Any] | list[Any] | None = None,
+        error: str | None = None,
+    ) -> "ErrorResponse":
+        return ErrorResponse(
+            status_code=status_code,
+            error=error or status_code.phrase,
+            message=message,
+            details=details,
+        )