GET ба route-ийн бүтэц

Танилцуулга

Бүлэг 1-д та ажиллаж байгаа сервертэй боллоо. Гэхдээ таны API одоохондоо ганц хаягтай, ганц хариутай. Жинхэнэ API олон арван, заримдаа олон зуун хаягтай байдаг: нэг нь ном жагсаана, нөгөө нь нэг номын дэлгэрэнгүйг өгнө, гурав дахь нь хайлт хийнэ. Тэдгээр хаяг бүрийг path operation гэж нэрлэдэг.

Энэ хичээлд бид дөрвөн мөр кодыг маш нарийн задлан үзнэ. Тэр дөрвөн мөр бол таны бичих бүх endpoint-ийн загвар юм. Тэднийг бүрэн ойлгосон хүн энэ сургалтын үлдсэн хэсгийг илүү хөнгөн даван туулна, учир нь цаашид гарах бүх зүйл нь эдгээрийн дээр нэмэгдэх хувилбарууд болно.

Нэр томьёо: path operation гэж юу вэ

Path гэдэг бол хаягны зам — http://127.0.0.1:8000/books гэсэн хаягны /books хэсэг. Домэйн болон port-ыг оруулдаггүй, зөвхөн зураасаас хойших хэсгийг хэлдэг.

Operation гэдэг бол тэр зам дээр хийх үйлдэл — HTTP method гэсэн үг. Курс 2-оос та GET-ийг мэднэ: "унш, авчир". Дараа нь POST, PUT, DELETE-тэй танилцана.

Хоёрыг нийлүүлээд path operation болно: "энэ зам дээр энэ үйлдлийг хийвэл юу болох вэ". FastAPI-ийн баримт бичигт энэ нэр байнга гарах тул тогтоож авах нь зүйтэй. Өдөр тутмын ярианд хүмүүс үүнийг endpoint гэж ч нэрлэдэг, мөн route гэж ч нэрлэдэг. Гурвуулаа ойролцоогоор ижил зүйлийг хэлж байна. Бид гурвыг нь бүгдийг ашиглана, учир нь та бодит ертөнцөд гурвыг нь бүгдийг харна.

Зоогийн газрын зүйрлэлээр: endpoint бол цэсэн дэх нэг хоол. Цэс (API) бүхэлдээ олон хоолтой; endpoint бол тэдгээрийн нэг нь.

Дөрвөн мөрийн задаргаа

Бүлэг 1-д бичсэн кодоо дахин харъя:

python

# main.py
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def root():
    return {"мэссэж": "Миний анхны API"}

app объект

python

app = FastAPI()

app бол таны бүхэл аппликейшн. Түүнийг бүртгэлийн дэвтэр гэж төсөөлж болно. Хоосон дэвтэр анх үүсэхэд ямар ч endpoint бүртгэгдээгүй байдаг. Та endpoint бичих бүрд тэр дэвтэрт нэг мөр нэмэгддэг: "энэ зам, энэ method, энэ функц".

Хүсэлт ирэхэд FastAPI тэр дэвтрээ дээрээс нь доош уншиж, тохирох мөрийг хайдаг. Олдвол тэр мөрөнд бичигдсэн функцийг дуудна. Олдохгүй бол 404 буцаана. Энэ бол бүхэл framework-ийн зүрх юм, бодит байдал дээр үүнээс илүү төвөгтэй ч ойлголтын хувьд яг ийм.

app гэдэг нэр заавал биш. application = FastAPI() гэж бичиж болно. Гэхдээ дэлхийн бүх FastAPI төсөл app гэж нэрлэдэг тул та ч бас тэгэх нь зүйтэй — бусад хүн таны кодыг уншихад амар болно.

Decorator

python

@app.get("/")

Энэ мөр бол хамгийн чухал нь. Курс 2-ын Бүлэг 10-д та decorator-ыг сурсан: бэлгийг боох цаас — бэлгээ өөрчлөхгүйгээр гаднаас нь нэмэлт өгдөг.

Энд болж байгаа зүйл нь яг тэр. Доорх функц өөрөө зүгээр л Python функц; түүнийг та терминалаас дуудаж болно, ямар ч онцгой зүйл байхгүй. Гэхдээ энэ decorator түүнийг app дэвтэрт бүртгэж байна. Decorator FastAPI-д ингэж хэлж байна: "Хэн нэгэн / гэсэн зам руу GET хүсэлт илгээвэл, доорх функцийг дууд."

Мөрийг хэсэгчлэн задалъя. @ бол decorator эхэлж байгааг заана. app бол таны аппликейшн объект. .get бол HTTP method — тэр объектын method бөгөөд яг GET-д зориулсан. ("/") бол зам.

Тиймээс @app.post("/books") гэж бичвэл: "app дэвтэрт бүртгэ: /books зам, POST method". Логик яг адилхан, зөвхөн үг солигдоно.

Функц

python

def root():

Энэ бол ердийн Python функц. FastAPI түүний нэрийг тоохгүй — та root, home, hello_world гэж юу ч гэж нэрлэж болно, ажиллагаа өөрчлөгдөхгүй. Нэр нь зөвхөн /docs хуудсан дээрх товч тайлбарт харагдана (Бүлэг 1, Хичээл 3-т үүнийг харсан).

Гэхдээ нэрийг утга учиртай сонгох нь чухал. Хэдэн сарын дараа өөрийнхөө кодыг уншихад def f1(): гэдэг нь юу хийдгийг мартсан байх болно, харин def get_all_books(): гэдэг нь өөрийгөө тайлбарлаж байх болно.

Буцаах утга

python

return {"мэссэж": "Миний анхны API"}

Функц энгийн Python dictionary буцааж байна. Гэхдээ хэрэглэгч JSON хүлээж авдаг. Хооронд нь FastAPI зогсож, автоматаар хувиргалт хийж байна.

Курс 2-ын Бүлэг 6-д та json.dumps() гэдгийг гараар дуудаж, Python объектыг JSON текст болгож байсан. Одоо тэр ажлыг framework хийж байна. Та зөвхөн Python-оор бодоод, Python объект буцаахад л хангалттай.

Анхны жишээ: гурван endpoint

Одоо main.py файлаа бүхэлд нь дараах кодоор солино:

python

# main.py
from fastapi import FastAPI

app = FastAPI(title="Номын API")


@app.get("/")
def root():
    return {"message": "Номын API-д тавтай морил"}


@app.get("/books")
def get_books():
    return ["Монголын нууц товчоо", "Цог хийморь", "Цагаан хэрэм"]


@app.get("/books/count")
def get_book_count():
    return {"total": 3}

Хадгална. Терминал дээр reload болсныг шалгана.

Хүсэлт 1

Browser дээр:

http://127.0.0.1:8000/

Хариу:

json

{"message":"Номын API-д тавтай морил"}

Хүсэлт 2

http://127.0.0.1:8000/books

Хариу:

json

["Монголын нууц товчоо","Цог хийморь","Цагаан хэрэм"]

Хүсэлт 3

http://127.0.0.1:8000/books/count

Хариу:

json

{"total":3}

Задаргаа

Гурван endpoint, гурван өөр зам, гурван өөр функц, гурван өөр хариу. FastAPI хүсэлт бүрийг зам дээр нь тулгуурлан зөв функц рүү чиглүүлж байна.

Хоёр дахь endpoint нэг зүйлийг харуулж байна: dictionary заавал биш. Функц Python list буцаасан, FastAPI түүнийг JSON array болгосон. Та str, int, bool, None, list, dictionary — Python-ы бараг ямар ч энгийн төрөл буцааж болно. Тэдгээрийг хэрхэн хувиргах талаар Бүлэг 3-т илүү дэлгэрэнгүй ярина.

Гурав дахь endpoint-ийн зам нь /books/count — хоёр түвшинтэй. Энэ нь ямар ч онцгой зүйл биш; зам бол зүгээр л текст. /api/v1/books/statistics/monthly гэсэн зам ч мөн адил хүчинтэй. Түвшний тоо ямар ч утга агуулдаггүй, зөвхөн хүн уншихад цэгцтэй байлгах зорилготой.

Нэмэлт жишээ: /docs дээр харах

Одоо /docs хуудсаа нээж шинэчилнэ:

http://127.0.0.1:8000/docs

Гурван мөр харагдана:

GET   /              Root
GET   /books         Get Books
GET   /books/count   Get Book Count

Дээд талд Номын API гэсэн гарчиг харагдана — та FastAPI(title="Номын API") гэж бичсэний үр дүн.

Анзаараарай: FastAPI функцийн нэрийг автоматаар цэвэрлэсэн. get_books гэсэн нэр Get Books болж хувирсан — доогуур зураасыг зайгаар сольж, эхний үсгүүдийг том болгосон. Энэ бол жижиг тав тух боловч таны кодыг баримт бичиг рүү шууд холбож байгаагийн бас нэг жишээ.

Аль ч мөр дээр товшоод Try it out -> Execute дарж хариуг нь харна уу. Одоо танд туршиж болох гурван зүйл байна.

Гурав дахь жишээ: олон төрөл буцаах

Дараах endpoint-ийг нэмнэ:

python

# main.py (нэмэлт хэсэг)

@app.get("/status")
def get_status():
    return {
        "api": "Номын API",
        "version": 1,
        "is_online": True,
        "book_count": 3,
        "maintenance_message": None,
    }

Хүсэлт:

http://127.0.0.1:8000/status

Хариу:

json

{"api":"Номын API","version":1,"is_online":true,"book_count":3,"maintenance_message":null}

Хувиргалтыг сайтар ажиглана уу, учир нь энэ нь Курс 2-ын JSON мэдлэгийг батлаж байна. Python-ы True нь JSON-д true болсон — жижиг үсгээр. Python-ы None нь JSON-д null болсон. Тоонууд ямар ч хашилтгүй үлдсэн, текст хашилттай. Эдгээр бол Python болон JSON хоёрын хэлний ялгаа бөгөөд FastAPI орчуулгыг тань хийж өгч байна.

Курс 2-т та json.dumps() ашиглан яг ижил хувиргалтыг гараар хийж байсныг санаж байвал — энэ нь тэр ажил юм, зөвхөн одоо автоматаар болж байна.

Туршаад үзээрэй

Хүсвэл өөрийн гэсэн шинэ endpoint нэмж үзээрэй. Жишээ нь /authors гэсэн зам үүсгээд зохиолчдын жагсаалт буцаана уу. Хадгалаад /docs хуудсаа шинэчилээд шинэ мөр гарч ирснийг ажиглаарай.

Сонирхвол функц дотор print() дуудаж үзээрэй:

python

@app.get("/books")
def get_books():
    print("Хэн нэгэн номын жагсаалт хүслээ")
    return ["Монголын нууц товчоо", "Цог хийморь", "Цагаан хэрэм"]

Дараа нь browser дээрээ /books руу орж, терминалаа хараарай. Тэнд таны мессеж гарч ирнэ. Энэ нь чухал зүйлийг харуулж байна: таны функц сервер дээр ажиллаж байна, хэрэглэгчийн browser дээр биш. print() нь хэрэглэгчид харагдахгүй, зөвхөн танд, терминал дээр харагдана. Энэ ялгааг сайн ойлгох нь чухал.

Түгээмэл алдаанууд

Зам зураасаар эхлээгүй

python

@app.get("books")
def get_books():
    return ["Монголын нууц товчоо"]

Терминал дээр:

fastapi.exceptions.FastAPIError: Prefix and path cannot be empty and must start with '/'

Зам заавал / тэмдэгтээр эхлэх ёстой. "books" биш, "/books". Алдааны мэдэгдэл үүнийг шууд хэлж байна: must start with '/' — зураасаар эхлэх ёстой.

Хоёр функц ижил нэртэй

python

@app.get("/books")
def get_books():
    return ["ном 1"]


@app.get("/authors")
def get_books():
    return ["зохиолч 1"]

Энэ код ямар ч алдаа өгөхгүй ажиллана. Гэхдээ /docs хуудас дээр хоёулаа Get Books гэж харагдана, учир нь FastAPI функцийн нэрийг товч тайлбар болгон авдаг. Энэ бол алдаа биш, гэхдээ будлиан. Python-ы хувьд ч хоёр дахь get_books нь эхнийхийг дарж бичдэг — тиймээс функцээ өөр нэртэй болгох нь зүйтэй.

Зам ижил, method ижил

python

@app.get("/books")
def get_books():
    return ["ном 1"]


@app.get("/books")
def get_all_books():
    return ["ном 2"]

Алдаа гарахгүй, гэхдээ зөвхөн эхнийх нь ажиллана. FastAPI дэвтрээ дээрээс доош уншиж, эхний тохирлыг олоод зогсдог. Хоёр дахь нь хэзээ ч дуудагдахгүй — "үхсэн код" болно.

Энэ бол ирээдүйд чухал болох зан төлөв юм. Бүлэг 2-ын сүүлийн хичээлд бид үүнээс үүсэх бодит асуудлыг (route ordering gotcha) харах болно.

Товч дүгнэлт

• Path operation = зам (/books) + method (GET) + функц. Endpoint, route гэж ч нэрлэдэг.

• app = FastAPI() бол бүртгэлийн дэвтэр; decorator бүр түүнд нэг мөр нэмнэ.

• @app.get("/зам") — decorator доорх функцийг тэр зам, тэр method-д бүртгэнэ.

• Функцийн нэр ажиллагаанд нөлөөлөхгүй, зөвхөн /docs дээр харагдана.

• Буцаасан Python объект (dict, list, str, int, bool, None) автоматаар JSON болно.

• Хүсэлт ирэхэд FastAPI дэвтрээ дээрээс доош уншиж, эхний тохирлыг ашиглана.

• Функц сервер дээр ажиллана — print() терминал дээр гарна, хэрэглэгчид харагдахгүй.

Одоохондоо таны бүх хариу тогтмол байна: /books руу хэн ханддаг ч ижил гурван ном ирнэ. Гэхдээ жинхэнэ API ийм биш. Хэрэглэгч "гурав дахь номыг өгөөч" эсвэл "Python тухай номуудыг хайж өгөөч" гэж хэлж чаддаг байх ёстой. Дараагийн хичээлд бид path parameter сурна — хаяг дотроос утга барьж авах арга. Тэнд мөн энэ сургалтын нэгэн онцлох мөч бидэнтэй уулзана: буруу өгөгдөл илгээхэд FastAPI автоматаар татгалзаж, дэлгэрэнгүй алдааны хариу буцаахыг бид хамтдаа мөр мөрөөр нь уншина.