Django REST Framework ViewSets: API-päätepisteiden organisoinnin hallinta

Nykyaikaisessa verkkokehityksessä vankkojen ja hyvin strukturoitujen API-rajapintojen rakentaminen on ensiarvoisen tärkeää. Django REST Framework (DRF) on tehokas työkalupakki RESTful-API-rajapintojen luomiseen Djangolla. Vaikka DRF tarjoaa useita työkaluja API-päätepisteiden luomiseen, ViewSetit tarjoavat elegantin tavan järjestää toisiinsa liittyvät näkymät yhdeksi luokaksi, mikä johtaa puhtaampaan ja helpommin ylläpidettävään koodiin. Tämä kattava opas tutkii ViewSettejä yksityiskohtaisesti, kattaen niiden hyödyt, käytön ja edistyneet mukautustekniikat.

Mitä ViewSetit ovat?

ViewSet on luokkapohjainen näkymä (View), joka tarjoaa toteutuksia standarditoiminnoille, kuten list, create, retrieve, update ja destroy. Sen sijaan, että määritettäisiin erillisiä näkymiä jokaiselle toiminnalle, ViewSet yhdistää ne yhdeksi luokaksi, mikä yksinkertaistaa API-rakennetta ja vähentää koodin toistuvuutta. ViewSetit ovat erityisen hyödyllisiä työskenneltäessä mallipohjaisten API-rajapintojen kanssa, joissa näitä standarditoimintoja yleensä tarvitaan. Ajattele ViewSettiä loogisena ryhmänä tiettyyn resurssiin kohdistuvista toiminnoista.

ViewSetien käytön edut

• Koodin uudelleenkäytettävyys: ViewSetit edistävät koodin uudelleenkäyttöä kapseloimalla yhteisen API-logiikan yhteen luokkaan. Tämä vähentää redundanssia ja tekee koodista helpommin ylläpidettävän.
• Yksinkertaistettu reititys: ViewSetit yksinkertaistavat reititystä ryhmittelemällä toisiinsa liittyvät näkymät yhden URL-etuliitteen alle. Tämä johtaa puhtaampaan ja järjestäytyneempään URL-rakenteeseen.
• Vähentynyt "Boilerplate"-koodi: ViewSetit vähentävät toistuvaa koodia tarjoamalla oletustoteutukset yleisille API-toiminnoille. Tämä antaa kehittäjille mahdollisuuden keskittyä sovelluskohtaisen mukautetun logiikan toteuttamiseen.
• Parempi luettavuus: ViewSetit parantavat koodin luettavuutta järjestämällä toisiinsa liittyvät näkymät yhteen luokkaan. Tämä tekee API-rakenteesta helpommin ymmärrettävän ja navigoitavan.
• Yhdenmukaisuus: ViewSetit auttavat varmistamaan yhdenmukaisuuden API-rajapinnassa pakottamalla standardoidun toimintosarjan ja käytännöt. Tämä tekee API:sta ennustettavamman ja helpommin käytettävän.

ViewSetien peruskäyttö

Aloitetaan yksinkertaisella esimerkillä ViewSetien käytöstä tuotteiden hallintaan tarkoitettavan API-rajapinnan luomiseksi. Määrittele ensin malli:

            # models.py
from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=255)
    description = models.TextField()
    price = models.DecimalField(max_digits=10, decimal_places=2)

    def __str__(self):
        return self.name

            

              
                Copy
              
            
          

Määrittele seuraavaksi serialisoija Product-mallille:

            # serializers.py
from rest_framework import serializers
from .models import Product

class ProductSerializer(serializers.ModelSerializer):
    class Meta:
        model = Product
        fields = '__all__'

            

              
                Copy
              
            
          

Luo nyt ViewSet Product-mallille:

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

            

              
                Copy
              
            
          

Lopuksi, määritä URL-reititys:

            # urls.py
from django.urls import path, include
from rest_framework import routers
from . import views

router = routers.DefaultRouter()
router.register(r'products', views.ProductViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

            

              
                Copy
              
            
          

Tämä konfiguraatio luo automaattisesti seuraavat API-päätepisteet:

• /products/ (GET: list, POST: create)
• /products/{id}/ (GET: retrieve, PUT: update, PATCH: partial_update, DELETE: destroy)

ModelViewSet tarjoaa oletustoteutukset kaikille standardi CRUD-toiminnoille. queryset-attribuutti määrittää objektijoukon, jota ViewSetin tulee käsitellä, ja serializer_class-attribuutti määrittää serialisoijan, jota käytetään datan serialisoimiseen ja deserialisoimiseen.

ViewSet-tyypit

DRF tarjoaa useita sisäänrakennettuja ViewSet-luokkia, jotka palvelevat erilaisia käyttötapauksia:

• ViewSet: Kaikkien ViewSetien perusluokka. Se tarjoaa perusinfrastruktuurin pyyntöjen ja vastausten käsittelyyn.
• ReadOnlyModelViewSet: ViewSet, joka tarjoaa vain luku -toimintoja (list ja retrieve). Tämä on hyödyllinen API-rajapinnoille, jotka sallivat vain datan haun.
• ModelViewSet: ViewSet, joka tarjoaa kaikki standardi CRUD-toiminnot (list, create, retrieve, update ja destroy). Tämä on yleisimmin käytetty ViewSet mallipohjaisissa API-rajapinnoissa.
• GenericViewSet: ViewSet, joka tarjoaa geneerisen toteutuksen yleisille API-toiminnoille. Tätä voidaan käyttää pohjaluokkana mukautettujen ViewSetien luomiseen.

Oikean ViewSetin valinta riippuu API:si erityisvaatimuksista. Jos tarvitset vain luku -toimintoja, käytä ReadOnlyModelViewSet-luokkaa. Jos tarvitset kaikki standardi CRUD-toiminnot, käytä ModelViewSet-luokkaa. Jos tarvitset enemmän kontrollia API:n toimintaan, voit luoda mukautetun ViewSetin perimällä GenericViewSet- tai ViewSet-luokasta.

ViewSetien mukauttaminen

Vaikka sisäänrakennetut ViewSetit tarjoavat kätevän tavan luoda API-rajapintoja, saatat joutua mukauttamaan niiden toimintaa vastaamaan erityisvaatimuksia. DRF tarjoaa useita tapoja mukauttaa ViewSettejä, mukaan lukien metodien ylikirjoittaminen, mukautettujen toimintojen lisääminen ja mukautettujen serialisoijien käyttö.

Metodien ylikirjoittaminen

Voit ylikirjoittaa standardien API-toimintojen oletustoteutukset määrittämällä samannimiset metodit ViewSet-luokassasi. Voit esimerkiksi ylikirjoittaa create-metodin lisätäksesi mukautettua logiikkaa ennen uuden objektin luomista tai sen jälkeen:

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer
from rest_framework.response import Response
from rest_framework import status

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

    def create(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        # Lisää mukautettu logiikka tähän ennen objektin luomista
        self.perform_create(serializer)
        headers = self.get_success_headers(serializer.data)
        return Response(serializer.data, status=status.HTTP_201_CREATED, headers=headers)

            

              
                Copy
              
            
          

Tässä esimerkissä create-metodi ylikirjoittaa oletustoteutuksen ja lisää mukautettua logiikkaa ennen objektin luomista. perform_create-metodia kutsutaan varsinaisen objektin luomiseen, ja vastaus palautetaan 201 Created -statuskoodilla.

Mukautettujen toimintojen lisääminen

Voit lisätä mukautettuja toimintoja ViewSettiisi käyttämällä @action-dekorointia. Mukautetut toiminnot mahdollistavat uusien API-päätepisteiden määrittelyn, jotka suorittavat tiettyjä operaatioita ViewSetin hallitsemilla resursseilla. Voit esimerkiksi lisätä toiminnon merkitäksesi tuotteen esillepanoksi (featured):

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework import status

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

    @action(detail=True, methods=['post'])
    def feature(self, request, pk=None):
        product = self.get_object()
        product.is_featured = True
        product.save()
        serializer = self.get_serializer(product)
        return Response(serializer.data)

            

              
                Copy
              
            
          

Tässä esimerkissä @action-dekorointi määrittelee uuden API-päätepisteen /products/{id}/feature/, joka merkitsee tuotteen esillepanoksi. detail=True-argumentti osoittaa, että toiminto kohdistuu tiettyyn mallin instanssiin. methods=['post']-argumentti määrittää, että toiminto hyväksyy vain POST-pyyntöjä.

Mukautettujen serialisoijien käyttö

Voit käyttää mukautettuja serialisoijia mukauttamaan tapaa, jolla ViewSet serialisoi ja deserialisoi dataa. Tämä on hyödyllistä, kun sinun on käsiteltävä monimutkaisia datarakenteita tai suoritettava mukautettua validointia. Voit esimerkiksi käyttää mukautettua serialisoijaa sisällyttääksesi liittyvän datan API-vastaukseen:

            # serializers.py
from rest_framework import serializers
from .models import Product, Category

class CategorySerializer(serializers.ModelSerializer):
    class Meta:
        model = Category
        fields = ['id', 'name']

class ProductSerializer(serializers.ModelSerializer):
    category = CategorySerializer(read_only=True)

    class Meta:
        model = Product
        fields = '__all__'

            

              
                Copy
              
            
          

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

            

              
                Copy
              
            
          

Tässä esimerkissä ProductSerializer sisältää CategorySerializerin serialisoimaan liittyvän kategoriadatan. Tämä mahdollistaa kategoriatietojen hakemisen yhdessä tuotetietojen kanssa yhdellä API-pyynnöllä.

Edistyneet ViewSet-tekniikat

ViewSetit tarjoavat peruskäytön ja mukautuksen lisäksi edistyneitä tekniikoita kehittyneiden API-rajapintojen rakentamiseen:

Suodatus

DRF tarjoaa tehokkaita suodatusominaisuuksia, jotka mahdollistavat kyselyjoukon suodattamisen pyyntöparametrien perusteella. Voit käyttää filter_backends-attribuuttia määrittääksesi käytettävät suodatusrajapinnat. Voit esimerkiksi käyttää SearchFilteriä antaaksesi käyttäjille mahdollisuuden etsiä tuotteita nimen tai kuvauksen perusteella:

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer
from rest_framework import filters

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    filter_backends = [filters.SearchFilter]
    search_fields = ['name', 'description']

            

              
                Copy
              
            
          

Tässä esimerkissä filter_backends-attribuutti määrittää, että SearchFilteriä tulee käyttää. search_fields-attribuutti määrittää kentät, joista haku suoritetaan.

Sivutus

DRF tarjoaa sivutusominaisuuksia, jotka mahdollistavat kyselyjoukon jakamisen pienempiin sivuihin. Tämä on hyödyllistä käsiteltäessä suuria datajoukkoja. Voit käyttää pagination_class-attribuuttia määrittääksesi käytettävän sivutusluokan. Voit esimerkiksi käyttää PageNumberPaginationia tulosten sivuttamiseen sivunumeroiden avulla:

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer
from rest_framework.pagination import PageNumberPagination

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    pagination_class = PageNumberPagination

            

              
                Copy
              
            
          

Tässä esimerkissä pagination_class-attribuutti määrittää, että PageNumberPaginationia tulee käyttää. Voit myös mukauttaa sivutuskäyttäytymistä luomalla oman sivutusluokkasi.

Autentikointi ja käyttöoikeudet

DRF tarjoaa joustavat autentikointi- ja käyttöoikeusmekanismit, joiden avulla voit hallita pääsyä API-päätepisteisiisi. Voit käyttää authentication_classes- ja permission_classes-attribuutteja määrittääksesi käytettävät autentikointi- ja käyttöoikeusluokat. Voit esimerkiksi käyttää TokenAuthenticationia käyttäjien autentikoimiseen tunnusten avulla ja IsAuthenticated-oikeutta sallia API:n käytön vain autentikoiduille käyttäjille:

            # views.py
from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer
from rest_framework.authentication import TokenAuthentication
from rest_framework.permissions import IsAuthenticated

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    authentication_classes = [TokenAuthentication]
    permission_classes = [IsAuthenticated]

            

              
                Copy
              
            
          

Tässä esimerkissä authentication_classes-attribuutti määrittää, että TokenAuthenticationia tulee käyttää, ja permission_classes-attribuutti määrittää, että IsAuthenticated-oikeutta tulee käyttää.

Parhaat käytännöt ViewSetien käytössä

Varmistaaksesi, että ViewSetisi ovat hyvin suunniteltuja ja ylläpidettäviä, noudata näitä parhaita käytäntöjä:

• Pidä ViewSetit kohdennettuina: Jokaisen ViewSetin tulisi olla vastuussa yhden resurssin tai läheisesti toisiinsa liittyvien resurssien joukon hallinnasta. Vältä luomasta liian monimutkaisia ViewSettejä, jotka käsittelevät useita toisiinsa liittymättömiä operaatioita.
• Käytä sopivia ViewSet-tyyppejä: Valitse API:si vaatimuksiin parhaiten sopiva ViewSet-tyyppi. Käytä ReadOnlyModelViewSetiä vain luku -API-rajapinnoille, ModelViewSetiä CRUD-API-rajapinnoille ja GenericViewSetiä tai ViewSetiä mukautetuille API-rajapinnoille.
• Noudata RESTful-periaatteita: Suunnittele API-päätepisteesi RESTful-periaatteiden mukaisesti. Käytä standardi HTTP-metodeja (GET, POST, PUT, PATCH, DELETE) suorittaaksesi operaatioita resursseilla.
• Käytä serialisoijia datan validointiin: Käytä serialisoijia validoidaksesi API:lle lähetettävän ja siitä vastaanotettavan datan. Tämä auttaa varmistamaan datan eheyden ja ehkäisee virheitä.
• Toteuta asianmukainen autentikointi ja käyttöoikeudet: Turvaa API-päätepisteesi toteuttamalla asianmukainen autentikointi ja käyttöoikeudet. Tämä auttaa suojaamaan tietojasi luvattomalta käytöltä.
• Kirjoita kattavat testit: Kirjoita kattavat testit varmistaaksesi, että ViewSetisi toimivat oikein. Tämä auttaa estämään regressioita ja helpottaa koodin ylläpitoa.

Kansainvälistymisen (i18n) ja lokalisoinnin (l10n) huomioiminen

Kun rakennat API-rajapintoja globaalille yleisölle, on olennaista ottaa huomioon kansainvälistyminen (i18n) ja lokalisointi (l10n). ViewSettejä voidaan mukauttaa tukemaan useita kieliä ja alueita:

• Serialisoijakentät: Käytä DRF:n serialisoijakenttiä asianmukaisten käännöstoimintojen kanssa (esim. gettext Djangon i18n-viitekehyksestä) näyttääksesi käännetyt kenttien otsikot ja ohjetekstit.
• Virheilmoitukset: Varmista, että API:n palauttamat virheilmoitukset on käännetty käyttäjän ensisijaiseen kieleen.
• Päivämäärä- ja aikamuotoilu: Käytä asianmukaista päivämäärä- ja aikamuotoilua käyttäjän aluekohtaisen asetuksen perusteella. DRF tarjoaa vaihtoehtoja päivämäärä- ja aikamuotojen mukauttamiseen.
• Valuuttamuotoilu: Muotoile valuutta-arvot käyttäjän aluekohtaisen asetuksen mukaisesti. Harkitse kirjastojen, kuten babel, käyttöä valuuttamuotoiluun. Esimerkiksi hinta 1234.56 USD voidaan muotoilla 1 234,56 dollariksi Yhdysvalloissa, mutta 1.234,56 € joissakin Euroopan maissa.
• Aikavyöhykkeet: Käsittele aikavyöhykkeet oikein. Tallenna päivämäärät ja ajat UTC-muodossa ja muunna ne käyttäjän paikalliseen aikavyöhykkeeseen näyttäessäsi niitä.

Esimerkiksi tuotteella voi olla kuvaus, joka tarvitsee kääntää. Käyttäisit Djangon käännösjärjestelmää serialisoijan sisällä:

            # serializers.py
from rest_framework import serializers
from django.utils.translation import gettext_lazy as _
from .models import Product

class ProductSerializer(serializers.ModelSerializer):
    description = serializers.CharField(help_text=_("Tuotekuvaus"))

    class Meta:
        model = Product
        fields = '__all__'

            

              
                Copy
              
            
          

Ja malleissasi tai koodissasi, joka käyttää tätä serialisoijaa, varmista, että oikea kieli on aktivoitu.

Esimerkki: Verkkokaupan API kansainvälisellä tuella

Kuvittele verkkokaupan API-rajapinta, joka myy tuotteita maailmanlaajuisesti. Product-malli voi sisältää kenttiä, kuten name, description, price ja image. API:n on tuettava useita kieliä ja valuuttoja.

ViewSet käsittelisi tuotteiden perus CRUD-toimintoja. Serialisoijat mukautettaisiin tukemaan tuotteen nimen ja kuvauksen kääntämistä. API sisältäisi myös päätepisteitä tuotteiden hakemiseen luokittain, tuotteiden suodattamiseen hintaluokan mukaan ja tuotteiden etsimiseen avainsanan perusteella. Näiden ominaisuuksien tulisi ottaa huomioon kansainvälistyminen, erityisesti hakutermien ja tuotekuvausten osalta, jotka voivat vaihdella kielestä toiseen.

Esimerkki-URL-osoitteet:

• /en/products/ - Tuoteluettelo englanniksi
• /fr/products/ - Tuoteluettelo ranskaksi
• /en/products/?currency=USD - Tuoteluettelo USD-valuutassa
• /fr/products/123/?currency=EUR - Tuotteen 123 tiedot ranskaksi, hinta näytettynä EUR-valuutassa

Yhteenveto

Django REST Framework ViewSetit tarjoavat tehokkaan ja elegantin tavan organisoida API-päätepisteesi. Kapseloimalla toisiinsa liittyvät näkymät yhdeksi luokaksi ViewSetit edistävät koodin uudelleenkäyttöä, yksinkertaistavat reititystä ja parantavat koodin luettavuutta. Kyky mukauttaa ViewSettejä ylikirjoittamalla metodeja, lisäämällä mukautettuja toimintoja ja käyttämällä mukautettuja serialisoijia mahdollistaa niiden räätälöinnin API:si erityisvaatimusten mukaisesti. Noudattamalla tässä oppaassa esitettyjä parhaita käytäntöjä voit varmistaa, että ViewSetisi ovat hyvin suunniteltuja, ylläpidettäviä ja skaalautuvia, mikä johtaa vankkoihin ja tehokkaisiin API-rajapintoihin.

Muista ottaa huomioon kansainvälistyminen ja lokalisointi rakentaessasi API-rajapintoja globaalille yleisölle. Mukauta ViewSettejäsi ja serialisoijiasi tukemaan useita kieliä, valuuttoja ja aikavyöhykkeitä tarjotaksesi saumattoman käyttökokemuksen käyttäjille ympäri maailmaa.

Hallitsemalla ViewSetit voit viedä Django REST Framework -taitosi seuraavalle tasolle ja rakentaa API-rajapintoja, jotka ovat sekä tehokkaita että ylläpidettäviä. Tämä edistää korkealaatuista ohjelmistoa ja positiivista käyttökokemusta globaalille yleisöllesi.

Tämän oppaan tulisi toimia vankana perustana ViewSetien ymmärtämiseen ja toteuttamiseen Django REST Framework -projekteissasi. Jatka harjoittelua, kokeilua ja DRF-dokumentaation tutkimista tullaksesi todelliseksi ViewSet-mestariksi!