Kem Intensif Pembangunan Bahagian Belakang FastAPI · Pelajaran

Perversian URL, Pengepala dan Jenis Media

Bandingkan pendekatan perversian dan laksanakan pengumpulan laluan yang kemas supaya klien boleh dinaik taraf tanpa gangguan.

Pelajaran 1 daripada 413 langkah

Perversian URL, Pengepala dan Jenis Media ialah pelajaran Kem Intensif Pembangunan Bahagian Belakang FastAPI percuma di CoddyKit. Ini ialah pelajaran 1 daripada 4. Sebanyak 3 pelajaran dalam laluan pembelajaran ini boleh dibaca sepenuhnya secara percuma — selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan praktikal dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran Kem Intensif Pembangunan Bahagian Belakang FastAPI, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus Kem Intensif Pembangunan Bahagian Belakang FastAPI merangkumi sejumlah 4 pelajaran.

Mengapa API Perlu Mempunyai Versi?

Apabila klien sebenar bergantung pada API anda, anda tidak lagi boleh mengubah bentuk respons sesuka hati. Menamakan semula medan, membuang kunci atau mengubah kod status boleh merosakkan aplikasi produksi yang tidak anda kawal.

Pembuatan versi membolehkan anda melancarkan perubahan yang merosakkan di bawah label baharu, sementara tingkah laku lama terus berfungsi. Klien boleh menaik taraf mengikut jadual mereka sendiri.

Perubahan tidak merosakkan (menambah medan pilihan) biasanya tidak memerlukan versi baharu.
Perubahan merosakkan (membuang/menamakan semula medan, mengubah jenis atau semantik) memerlukan sempadan versi.

Pelajaran ini membandingkan tiga strategi klasik: versi laluan URL, Header dan Media-Type.

Strategi 1: Pembuatan Versi Laluan URL

Pendekatan yang paling biasa dan paling jelas: letakkan versi terus dalam laluan, contohnya /v1/users dan /v2/users.

Kelebihan: jelas dalam log dan pelayar, mudah untuk menghala, mudah dicache dan mudah didokumenkan.
Kekurangan: versi muncul dalam setiap URL; dari segi teknikal, URL sepatutnya mengenal pasti sumber, bukan perwakilan.

Dalam FastAPI, anda menyatakan perkara ini dengan prefix pada APIRouter. Setiap versi mendapat penghala dan awalan tersendiri.

from fastapi import APIRouter, FastAPI

app = FastAPI()

v1 = APIRouter(prefix="/v1", tags=["v1"])
v2 = APIRouter(prefix="/v2", tags=["v2"])

@v1.get("/users/{user_id}")
def get_user_v1(user_id: int):
    return {"id": user_id, "name": "Ada Lovelace"}

@v2.get("/users/{user_id}")
def get_user_v2(user_id: int):
    # v2 splits name into first/last
    return {"id": user_id, "first_name": "Ada", "last_name": "Lovelace"}

app.include_router(v1)
app.include_router(v2)

Pengumpulan Laluan yang Kemas dengan Penghala Kecil

Jangan letakkan setiap titik akhir pada satu penghala versi yang besar. Kumpulkan berdasarkan sumber, kemudian lekapkan penghala setiap sumber di bawah penghala versi supaya strukturnya kekal kemas apabila API berkembang.

Di sini, users_router dibina secara berasingan dan kemudian disertakan ke dalam v1. Laluan gabungan menjadi /v1/users/....

from fastapi import APIRouter, FastAPI

app = FastAPI()

users_router = APIRouter(prefix="/users", tags=["users"])

@users_router.get("/{user_id}")
def get_user(user_id: int):
    return {"id": user_id, "name": "Grace Hopper"}

v1 = APIRouter(prefix="/v1")
v1.include_router(users_router)   # -> /v1/users/{user_id}

app.include_router(v1)

Strategi 2: Pembuatan Versi melalui Pengepala

Di sini URL kekal kemas (/users/42) dan klien menyatakan versi melalui pengepala permintaan tersuai, biasanya X-API-Version: 2.

Kelebihan: URL bebas versi dan stabil; laluan sumber tidak pernah berubah.
Kekurangan: lebih sukar diuji dalam pelayar, pengepala mudah terlupa dan lapisan cache perlu diarahkan untuk mempelbagaikan cache berdasarkan pengepala itu.

Dalam FastAPI, anda membaca pengepala dengan parameter bertip dan memilih cabang (atau menghantar) berdasarkan nilainya.

from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/users/{user_id}")
def get_user(user_id: int, x_api_version: int = Header(default=1)):
    if x_api_version >= 2:
        return {"id": user_id, "first_name": "Ada", "last_name": "Lovelace"}
    return {"id": user_id, "name": "Ada Lovelace"}

Kebergantungan untuk Menentukan Versi

Membuat pilihan cabang dalam setiap titik akhir akan menjadi berserabut. Keluarkan logik versi ke dalam kebergantungan yang boleh digunakan semula, yang mengesahkan pengepala sekali dan menolak versi yang tidak disokong dengan 406 yang jelas.

Kini mana-mana titik akhir boleh bergantung pada api_version dan mempercayai bahawa nilainya ialah salah satu nilai yang disokong.

from fastapi import FastAPI, Header, HTTPException, Depends

app = FastAPI()
SUPPORTED = {1, 2}

def api_version(x_api_version: int = Header(default=1)) -> int:
    if x_api_version not in SUPPORTED:
        raise HTTPException(
            status_code=406,
            detail=f"Unsupported API version {x_api_version}",
        )
    return x_api_version

@app.get("/users/{user_id}")
def get_user(user_id: int, version: int = Depends(api_version)):
    return {"id": user_id, "version": version}

Strategi 3: Pembuatan Versi Jenis Media (Rundingan Kandungan)

Pendekatan yang paling mematuhi REST tetapi paling jarang digunakan. Klien meminta perwakilan tertentu melalui pengepala Accept menggunakan jenis media vendor:

Accept: application/vnd.myapp.v1+json
Accept: application/vnd.myapp.v2+json

URL mengenal pasti sumber; jenis media mengenal pasti perwakilan/versi. Inilah rundingan kandungan HTTP yang sebenar.

Kelebihan: URL kemas dan murni dari segi semantik; anda membuat versi perwakilan, bukan sumber.
Kekurangan: panjang, sukar untuk klien biasa, sokongan alat yang lemah dan mudah tersalah taip.

Menghuraikan Jenis Media Vendor

Inti pembuatan versi jenis media ialah menghuraikan rentetan vendor kepada nombor versi. Penghuraian itu ialah Python tulen dan mudah diuji unit secara berasingan, tanpa bergantung pada mana-mana rangka kerja.

Di bawah, kami mengekstrak token vN daripada nilai Accept, dengan lalai kepada v1 apabila nilai itu tiada atau tidak sah.

import re

PATTERN = re.compile(r"application/vnd\.myapp\.v(\d+)\+json")

def parse_version(accept: str, default: int = 1) -> int:
    match = PATTERN.search(accept or "")
    return int(match.group(1)) if match else default

# A few quick checks
print(parse_version("application/vnd.myapp.v2+json"))  # 2
print(parse_version("application/json"))                # 1 (default)
print(parse_version("application/vnd.myapp.v10+json")) # 10

Menghubungkan Pembuatan Versi Jenis Media dengan FastAPI

Dengan penghuraian yang telah tersedia, sambungkannya kepada kebergantungan yang membaca pengepala Accept. Titik akhir kekal kemas dan berfokus pada sumber, manakala versi diperoleh melalui rundingan kandungan.

import re
from fastapi import FastAPI, Header, Depends

app = FastAPI()
PATTERN = re.compile(r"application/vnd\.myapp\.v(\d+)\+json")

def accept_version(accept: str = Header(default="")) -> int:
    m = PATTERN.search(accept)
    return int(m.group(1)) if m else 1

@app.get("/users/{user_id}")
def get_user(user_id: int, version: int = Depends(accept_version)):
    if version >= 2:
        return {"id": user_id, "first_name": "Ada", "last_name": "Lovelace"}
    return {"id": user_id, "name": "Ada Lovelace"}

Mengekalkan DRY untuk Versi dengan Pengubah

Menyalin logik perniagaan bagi setiap versi akan cepat menjadi sukar diselenggara. Pola yang lebih kemas: kira data sekali dalam bentuk dalaman kanonik, kemudian jalankan pengubah kecil bagi setiap versi untuk menyesuaikannya dengan kontrak yang dijanjikan oleh versi tersebut.

Ini mengasingkan perbezaan kontrak dalam fungsi kecil yang boleh diuji, bukannya mencabangkan keseluruhan pengendali anda.

def canonical_user(user_id: int) -> dict:
    return {"id": user_id, "first": "Ada", "last": "Lovelace"}

def to_v1(u: dict) -> dict:
    return {"id": u["id"], "name": f"{u['first']} {u['last']}"}

def to_v2(u: dict) -> dict:
    return {"id": u["id"], "first_name": u["first"], "last_name": u["last"]}

VERSIONS = {1: to_v1, 2: to_v2}

def render(user_id: int, version: int) -> dict:
    return VERSIONS[version](canonical_user(user_id))

print(render(42, 1))  # {'id': 42, 'name': 'Ada Lovelace'}
print(render(42, 2))  # {'id': 42, 'first_name': 'Ada', 'last_name': 'Lovelace'}

Perangkap Cache, Vary dan Dokumentasi

Pembuatan versi melalui pengepala dan jenis media mempunyai sisi yang berbahaya: cache. Jika proksi mencache /users/42 tanpa mengetahui pengepala versi anda, klien v1 mungkin menerima isi v2 yang dicache.

Sentiasa hantar Vary: X-API-Version (atau Vary: Accept untuk pembuatan versi jenis media) supaya cache menggunakan pengepala itu sebagai kunci.
Pembuatan versi URL mengelakkan masalah ini sepenuhnya kerana setiap versi mempunyai URL yang berbeza.
Versi melalui pengepala/jenis media juga lebih sukar dilihat dalam skema /docs yang dijana secara automatik kerana laluannya kelihatan sama merentas versi.

Memilih Strategi dan Menamatkan Sokongan dengan Kemas

Panduan praktikal untuk kem latihan:

Pembuatan versi URL ialah lalai untuk API REST awam: jelas, mesra cache dan mudah digunakan oleh pengguna baharu.
Pembuatan versi melalui pengepala sesuai untuk perkhidmatan dalaman yang mahukan URL stabil serta mengawal klien dan pelayan.
Pembuatan versi jenis media sesuai untuk golongan yang mengutamakan hipermedia/REST; jarang digunakan dalam amalan.

Walau apa pun pilihan anda, sediakan pelan penamatan sokongan: umumkan tarikh penamatan, pulangkan pengepala Deprecation/Sunset pada versi lama dan kekalkan versi tersebut cukup lama untuk membolehkan klien berhijrah.

from fastapi import APIRouter
from fastapi.responses import JSONResponse

v1 = APIRouter(prefix="/v1")

@v1.get("/users/{user_id}")
def get_user_v1(user_id: int):
    body = {"id": user_id, "name": "Ada Lovelace"}
    headers = {
        "Deprecation": "true",
        "Sunset": "Wed, 31 Dec 2025 23:59:59 GMT",
        "Link": '</v2/users>; rel="successor-version"',
    }
    return JSONResponse(content=body, headers=headers)

Semakan Pantas: Memilih Pendekatan Pembuatan Versi yang Betul

Gunakan perkara yang telah anda pelajari tentang pertukaran antara ketiga-tiga strategi.

Jawab dalam pelajaran interaktif

Rumusan: Pembuatan Versi Tanpa Kerosakan

Anda telah membandingkan tiga cara untuk membuat versi API FastAPI:

Laluan URL (/v1/users): jelas kelihatan, mesra cache dan mudah dihalakan melalui awalan APIRouter bagi setiap versi. Pilihan lalai untuk API awam.
Pengepala (X-API-Version): URL yang kemas, diselesaikan dengan kebergantungan; jangan lupa Vary untuk cache.
Jenis media (Accept: application/vnd.myapp.vN+json): paling menepati REST, dihuraikan daripada pengepala Accept; jarang digunakan dan panjang.

Kumpulkan laluan mengikut sumber dan pasangkannya di bawah penghala versi, asingkan perbezaan kontrak dalam transformer kecil bagi setiap versi, dan sentiasa sertakan versi baharu dengan pelan penamatan sokongan/pemberhentian yang jelas supaya klien dapat dinaik taraf dengan lancar.

Percuma untuk bermula

Pelajari Kem Intensif Pembangunan Bahagian Belakang FastAPI dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus: 21
Pelajaran: 84

Mula belajar secara percuma Lihat kursus penuh

Soalan Lazim

Adakah pelajaran “Perversian URL, Pengepala dan Jenis Media” percuma?

Ya — sebanyak 3 pelajaran dalam laluan pembelajaran Kem Intensif Pembangunan Bahagian Belakang FastAPI, termasuk “Perversian URL, Pengepala dan Jenis Media”, boleh dibaca sepenuhnya secara percuma di web ini. Selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan interaktif dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Kursus Kem Intensif Pembangunan Bahagian Belakang FastAPI merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Perversian URL, Pengepala dan Jenis Media”?

Bandingkan pendekatan perversian dan laksanakan pengumpulan laluan yang kemas supaya klien boleh dinaik taraf tanpa gangguan. Anda berlatih Kem Intensif Pembangunan Bahagian Belakang FastAPI menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan Kem Intensif Pembangunan Bahagian Belakang FastAPI?

Tiada pengalaman terdahulu diperlukan. Pembelajaran Kem Intensif Pembangunan Bahagian Belakang FastAPI di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 1 daripada 4.

Berapa lamakah pelajaran “Perversian URL, Pengepala dan Jenis Media” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran Kem Intensif Pembangunan Bahagian Belakang FastAPI ini?

Ya. Setiap pelajaran Kem Intensif Pembangunan Bahagian Belakang FastAPI menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

Perversian URL, Pengepala dan Jenis Media
Penomboran Kursor berbanding Ofset pada Skala Besar
Parameter Penapisan dan Pengisihan Dinamik
Mereka Bentuk Sampul Tindak Balas yang Stabil

← Kembali ke Kem Intensif Pembangunan Bahagian Belakang FastAPI