Python FastAPI klaidų valdymas: Kūrimas patikimų pasirinktinių išimčių valdiklių

Klaidų valdymas yra esminis aspektas kuriant tvirtas ir patikimas API. Python"FastAPI" bibliotekoje galite pasinaudoti pasirinktiniais išimčių valdikliais, kad elegantiškai valdytumėte klaidas ir teiktumėte informatyvius atsakymus klientams. Šis tinklaraščio įrašas padės jums sukurti pasirinktinius išimčių valdiklius "FastAPI" aplinkoje, leisdamas kurti atsparesnes ir patogesnes programas.

Kodėl verta naudoti pasirinktinius išimčių valdiklius?

FastAPI teikia integruotą palaikymą išimčių valdymui. Tačiau vien tik numatytųjų klaidų atsakymų naudojimas gali palikti klientus su neaiškia arba nenaudinga informacija. Pasirinktiniai išimčių valdikliai suteikia keletą privalumų:

• Geresnė vartotojo patirtis: Pateikite aiškius ir informatyvius klaidų pranešimus, pritaikytus konkretiems klaidų scenarijams.
• Centralizuotas klaidų valdymas: Konsoliduokite klaidų valdymo logiką vienoje vietoje, todėl jūsų kodas tampa lengviau palaikomas.
• Nuoseklūs klaidų atsakymai: Užtikrinkite, kad klaidų atsakymai atitiktų nuoseklų formatą, pagerindami API patogumą.
• Padidintas saugumas: Neleiskite, kad jautri informacija būtų atskleista klaidų pranešimuose.
• Pasirinktinis registravimas: Registruokite išsamią klaidų informaciją derinimo ir stebėjimo tikslais.

FastAPI išimčių valdymo supratimas

FastAPI naudoja Python integruotų išimčių valdymo mechanizmų ir savo priklausomybių injekcijos sistemos derinį klaidoms valdyti. Kai išimtis įvyksta maršruto ar priklausomybės viduje, FastAPI ieško tinkamo išimties valdiklio jai apdoroti.

Išimčių valdikliai yra funkcijos, pažymėtos dekoratoriumi @app.exception_handler(), kurios priima du argumentus: išimties tipą ir užklausos objektą. Valdiklis yra atsakingas už tinkamo HTTP atsakymo grąžinimą.

Pasirinktinių išimčių kūrimas

Prieš apibrėžiant pasirinktinius išimčių valdiklius, dažnai naudinga sukurti pasirinktines išimčių klases, kurios atspindi konkrečias klaidų sąlygas jūsų programoje. Tai pagerina kodo skaitomumą ir palengvina įvairių tipų klaidų valdymą.

Pavyzdžiui, tarkime, kad kuriate e-komercijos API ir jums reikia valdyti atvejus, kai produkto nėra sandėlyje. Galite apibrėžti pasirinktinę išimties klasę, pavadintą OutOfStockError:

            
class OutOfStockError(Exception):
    def __init__(self, product_id: int):
        self.product_id = product_id
        self.message = f"Product with ID {product_id} is out of stock."

            

              
                Copy
              
            
          

Ši pasirinktinė išimties klasė paveldi iš bazinės Exception klasės ir apima product_id atributą bei pasirinktinį klaidos pranešimą.

Pasirinktinių išimčių valdiklių diegimas

Dabar sukurkime pasirinktinį išimties valdiklį OutOfStockError. Šis valdiklis pagaus išimtį ir grąžins HTTP 400 (Bad Request) atsakymą su JSON turiniu, kuriame bus klaidos pranešimas.

            
from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import JSONResponse

app = FastAPI()

class OutOfStockError(Exception):
    def __init__(self, product_id: int):
        self.product_id = product_id
        self.message = f"Product with ID {product_id} is out of stock."

@app.exception_handler(OutOfStockError)
async def out_of_stock_exception_handler(request: Request, exc: OutOfStockError):
    return JSONResponse(
        status_code=400,
        content={"message": exc.message},
    )

@app.get("/products/{product_id}")
async def get_product(product_id: int):
    # Simulate checking product stock
    if product_id == 123:
        raise OutOfStockError(product_id=product_id)
    return {"product_id": product_id, "name": "Example Product", "price": 29.99}

            

              
                Copy
              
            
          

Šiame pavyzdyje dekoratorius @app.exception_handler(OutOfStockError) registruoja funkciją out_of_stock_exception_handler, kad ji tvarkytų OutOfStockError išimtis. Kai maršrute get_product yra iškeliama OutOfStockError, išimties valdiklis iškviečiamas. Tada valdiklis grąžina JSONResponse su 400 statuso kodu ir JSON turiniu, kuriame yra klaidos pranešimas.

Kelių išimčių tipų valdymas

Galite apibrėžti kelis išimčių valdiklius skirtingiems išimčių tipams valdyti. Pavyzdžiui, galbūt norėsite tvarkyti ValueError išimtis, kurios atsiranda analizuojant vartotojo įvestį.

            
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(ValueError)
async def value_error_exception_handler(request: Request, exc: ValueError):
    return JSONResponse(
        status_code=400,
        content={"message": str(exc)},
    )

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    # Simulate invalid item_id
    if item_id < 0:
        raise ValueError("Item ID must be a positive integer.")
    return {"item_id": item_id, "name": "Example Item"}

            

              
                Copy
              
            
          

Šiame pavyzdyje funkcija value_error_exception_handler tvarko ValueError išimtis. Ji išgauna klaidos pranešimą iš išimties objekto ir grąžina jį JSON atsakyme.

HTTPException naudojimas

FastAPI teikia integruotą išimties klasę, pavadintą HTTPException, kurią galima naudoti HTTP specifinėms klaidoms iškelti. Tai gali būti naudinga valdant dažnus klaidų scenarijus, tokius kaip neteisėta prieiga ar nerastas resursas.

            
from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    # Simulate user not found
    if user_id == 999:
        raise HTTPException(status_code=404, detail="User not found")
    return {"user_id": user_id, "name": "Example User"}

            

              
                Copy
              
            
          

Šiame pavyzdyje HTTPException yra iškeliama su 404 (nerasta) statuso kodu ir detaliu pranešimu. FastAPI automatiškai tvarko HTTPException išimtis ir grąžina JSON atsakymą su nurodytu statuso kodu ir detaliu pranešimu.

Globalūs išimčių valdikliai

Taip pat galite apibrėžti globalius išimčių valdiklius, kurie pagauna visas neapdorotas išimtis. Tai gali būti naudinga klaidų registravimui arba bendrojo klaidos pranešimo grąžinimui klientui.

            
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import logging

app = FastAPI()

logger = logging.getLogger(__name__)

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    logger.exception(f"Unhandled exception: {exc}")
    return JSONResponse(
        status_code=500,
        content={"message": "Internal server error"},
    )

@app.get("/error")
async def trigger_error():
    raise ValueError("This is a test error.")

            

              
                Copy
              
            
          

Šiame pavyzdyje funkcija global_exception_handler tvarko visas išimtis, kurios nėra tvarkomos kitų išimčių valdiklių. Ji registruoja klaidą ir grąžina 500 (vidinės serverio klaidos) atsakymą su bendriniu klaidos pranešimu.

Tarpinės programinės įrangos (Middleware) naudojimas išimčių valdymui

Kitas požiūris į išimčių valdymą yra tarpinės programinės įrangos (middleware) naudojimas. Tarpinės programinės įrangos funkcijos vykdomos prieš ir po kiekvienos užklausos, leidžiančios perimti ir tvarkyti išimtis aukštesniame lygmenyje. Tai gali būti naudinga tokioms užduotims kaip užklausų ir atsakymų registravimas arba pasirinktinės autentifikavimo ar autorizavimo logikos įgyvendinimas.

            
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import logging

app = FastAPI()

logger = logging.getLogger(__name__)

@app.middleware("http")
async def exception_middleware(request: Request, call_next):
    try:
        response = await call_next(request)
    except Exception as exc:
        logger.exception(f"Unhandled exception: {exc}")
        return JSONResponse(
            status_code=500,
            content={"message": "Internal server error"},
        )
    return response

@app.get("/error")
async def trigger_error():
    raise ValueError("This is a test error.")

            

              
                Copy
              
            
          

Šiame pavyzdyje funkcija exception_middleware apgaubia užklausos apdorojimo logiką try...except bloku. Jei užklausos apdorojimo metu įvyksta išimtis, tarpinė programinė įranga registruoja klaidą ir grąžina 500 (vidinės serverio klaidos) atsakymą.

Pavyzdys: internacionalizavimas (i18n) ir klaidų pranešimai

Kuriant API pasaulinei auditorijai, apsvarstykite klaidų pranešimų internacionalizavimą. Tai apima klaidų pranešimų teikimą skirtingomis kalbomis, atsižvelgiant į vartotojo lokalę. Nors viso i18n diegimas yra už šio straipsnio ribų, pateikiamas supaprastintas pavyzdys, demonstruojantis šią koncepciją:

            
from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import JSONResponse
from typing import Dict

app = FastAPI()

# Mock translation dictionary (replace with a real i18n library)
translations: Dict[str, Dict[str, str]] = {
    "en": {
        "product_not_found": "Product with ID {product_id} not found.",
        "invalid_input": "Invalid input: {error_message}",
    },
    "fr": {
        "product_not_found": "Produit avec l'ID {product_id} introuvable.",
        "invalid_input": "Entrée invalide : {error_message}",
    },
    "es": {
        "product_not_found": "Producto con ID {product_id} no encontrado.",
        "invalid_input": "Entrada inválida: {error_message}",
    },
    "de": {
        "product_not_found": "Produkt mit ID {product_id} nicht gefunden.",
        "invalid_input": "Ungültige Eingabe: {error_message}",
    }
}

def get_translation(locale: str, key: str, **kwargs) -> str:
    """Retrieves a translation for a given locale and key.
    If the locale or key is not found, returns a default message.
    """
    if locale in translations and key in translations[locale]:
        return translations[locale][key].format(**kwargs)
    return f"Translation missing for key '{key}' in locale '{locale}'."

@app.get("/products/{product_id}")
async def get_product(request: Request, product_id: int, locale: str = "en"):
    # Simulate product lookup
    if product_id > 100:
        message = get_translation(locale, "product_not_found", product_id=product_id)
        raise HTTPException(status_code=404, detail=message)

    if product_id < 0:
         message = get_translation(locale, "invalid_input", error_message="Product ID must be positive")
         raise HTTPException(status_code=400, detail=message)

    return {"product_id": product_id, "name": "Example Product"}

            

              
                Copy
              
            
          

Pagrindiniai i18n pavyzdžio patobulinimai:

• Lokalės parametras: Maršrutas dabar priima locale užklausos parametrą, leidžiantį klientams nurodyti pageidaujamą kalbą (numatytoji yra "en" anglų kalbai).
• Vertimų žodynas: translations žodynas (maketas) saugo klaidų pranešimus skirtingoms lokalėms (šiuo atveju anglų, prancūzų, ispanų, vokiečių). Realioje programoje naudotumėte specializuotą i18n biblioteką.
• get_translation funkcija: Ši pagalbinė funkcija gauna tinkamą vertimą pagal locale ir key. Ji taip pat palaiko eilutės formatavimą, kad įterptų dinamines reikšmes (pvz., product_id).
• Dinaminiai klaidų pranešimai: HTTPException dabar iškeliama su detail pranešimu, kuris dinamiškai sugeneruojamas naudojant get_translation funkciją.

Kai klientas užklauso /products/101?locale=fr, jis gaus klaidos pranešimą prancūzų kalba (jei yra vertimas). Kai užklausiama /products/-1?locale=es, bus gautas klaidos pranešimas apie neigiamą ID ispanų kalba (jei yra vertimas). Kai užklausiama /products/200?locale=xx (lokalė be vertimų), bus gautas pranešimas "Translation missing".

Geriausios klaidų valdymo praktikos

Štai keletas geriausių praktikų, kurių reikia laikytis diegiant klaidų valdymą FastAPI sistemoje:

• Naudokite pasirinktines išimtis: Apibrėžkite pasirinktines išimčių klases, kad atspindėtumėte konkrečias klaidų sąlygas jūsų programoje.
• Pateikite informatyvius klaidų pranešimus: Įtraukite aiškius ir glaustus klaidų pranešimus, kurie padėtų klientams suprasti klaidos priežastį.
• Naudokite tinkamus HTTP būsenos kodus: Grąžinkite HTTP būsenos kodus, kurie tiksliai atspindi klaidos pobūdį. Pavyzdžiui, naudokite 400 (bloga užklausa) netinkamai įvestai informacijai, 404 (nerasta) trūkstamiems resursams ir 500 (vidinė serverio klaida) netikėtoms klaidoms.
• Venkite atskleisti jautrią informaciją: Būkite atsargūs ir neatskleiskite jautrios informacijos, pvz., duomenų bazės prisijungimo duomenų ar API raktų, klaidų pranešimuose.
• Registruokite klaidas: Registruokite išsamią klaidų informaciją derinimo ir stebėjimo tikslais. Naudokite registravimo biblioteką, pvz., Python integruotą logging modulį.
• Centralizuokite klaidų valdymo logiką: Konsoliduokite klaidų valdymo logiką vienoje vietoje, pvz., pasirinktiniuose išimčių valdikliuose arba tarpinėje programinėje įrangoje (middleware).
• Išbandykite savo klaidų valdymą: Parašykite vienetinius testus, kad užtikrintumėte, jog jūsų klaidų valdymo logika veikia tinkamai.
• Apsvarstykite galimybę naudoti specializuotą klaidų stebėjimo paslaugą: Gamybinėse aplinkose apsvarstykite galimybę naudoti specializuotą klaidų stebėjimo paslaugą, pvz., Sentry ar Rollbar, klaidoms stebėti ir analizuoti. Šie įrankiai gali suteikti vertingos informacijos apie jūsų programos būklę ir padėti greitai nustatyti bei išspręsti problemas.

Išvada

Pasirinktiniai išimčių valdikliai yra galingas įrankis kuriant tvirtas ir patogias API naudojant FastAPI. Apibrėždami pasirinktines išimčių klases ir valdiklius, galite elegantiškai valdyti klaidas, teikti informatyvius atsakymus klientams ir pagerinti bendrą programos patikimumą bei palaikomumą. Pasirinktinių išimčių, HTTPException derinimas ir, kai taikoma, i18n principų panaudojimas paruošia jūsų API pasaulinei sėkmei.

Kurdami klaidų valdymo strategiją, nepamirškite atsižvelgti į vartotojo patirtį. Pateikite aiškius ir glaustus klaidų pranešimus, kurie padėtų vartotojams suprasti problemą ir kaip ją išspręsti. Efektyvus klaidų valdymas yra aukštos kokybės API kūrimo, atitinkančio įvairios pasaulinės auditorijos poreikius, kertinis akmuo.