Kaip nustatyti būsenos kodus ir antraštės?

Question

Accepted Answer

FastAPI pagal numatytuosius nustatymus grąžina `200 OK`, tačiau galite valdyti **būsenos kodą** (per dekoratorių arba atsakymo objektą) ir **antraštės**, kai reikalingas kitas elgesys — svarbu teisingai suprasti REST semantiką.

## Numatytojo būsenos kodo nustatymas kelyje

```python
from fastapi import status

@app.post("/items", status_code=status.HTTP_201_CREATED)   # 201 for resource creation
def create_item(item: Item):
    return item                                             # returns with 201

@app.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)  # 204
def delete_item(id: int):
    ...
```

Dekoratoriaus parametras `status_code` nustato numatytąją sėkmės būseną. Naudojimas `status` konstanta (pvz., `status.HTTP_201_CREATED`) yra aiškesnė nei stebuklinga skaičiai. Teisingi kodai svarbūs: `201` sukurtam, `204` be turinio, ir tt.

## Dinaminiai būsenos kodai ir antraštės per Response objektą

```python
from fastapi import Response

@app.get("/items/{id}")
def get_item(id: int, response: Response):
    item = db.get(id)
    if not item:
        response.status_code = status.HTTP_404_NOT_FOUND   # set dynamically
        return {"error": "not found"}
    response.headers["X-Custom"] = "value"                  # set a custom header
    return item
```

Response parametro injekcija leidžia nustatyti būsenos kodą ir antraštės **sąlygiškai** veikimo metu.

## Klaidos: raise HTTPException

```python
from fastapi import HTTPException

@app.get("/items/{id}")
def get_item(id: int):
    item = db.get(id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found",
                            headers={"X-Error": "NotFound"})   # status + detail + headers
    return item
```

Klaidų atsakymams `raise HTTPException(...)` yra idiomatinis būdas — nustato būseną, JSON `detail` pranešimą ir nebūtinas antraštės.

## Grąžinti pagal poreikį paruoštą Response tiesiogiai

```python
from fastapi.responses import JSONResponse
return JSONResponse(content={...}, status_code=202, headers={"X-Custom": "v"})
```

## Kodėl tai svarbu

Teisingi būsenos kodai ir antraštės yra būtini tinkamiems ir gerai veikiančiams REST API sukūrimui — klientai ir įrankiai remiasi standartine HTTP semantika (201 sukurtam, 404 nerasta, 204 be turinio ir tt.), todėl grąžinti teisingą kodą yra API kokybės sutarties dalis.

FastAPI suteikia grynąjį valdymą: numatytasis `status_code` kelyje dėl bendro atvejo, injekciojamas `Response` objektas dėl dinaminio kodo/antraščių, ir `HTTPException` kaip idiomatinis būdas nustatyti klaidas su atitinkama būsena ir JSON detalės.

Šių mechanizmų supratimas — ir `status` konstant naudojimas aiškumui — yra kasdienės žinios kuriant API, kurie veikia teisingai ir aišku komunikuoja su savo vartotojais.