Documentation уншиж сурах

Танилцуулга

Өмнөх хичээлд та FastAPI программ бичлээ. Тэр нь ажиллаж байна. /docs хуудас нээгдэж байна.

Гэвч та FastAPI-гийн БҮХ зүйлийг мэдэхгүй.

Түүнд хамаагүй илүү зүйл байна: dependency injection, middleware, authentication, background task, WebSocket, database integration, testing...

Мөн Python-ы ертөнцөд хэдэн зуун мянган сан бий.

Тэдгээрийг бүгдийг заах БОЛОМЖГҮЙ.

Гэвч ӨӨРӨӨ СУРАХ АРГЫГ заах боломжтой.

Тэр арга нь: DOCUMENTATION УНШИХ.

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

Энэ хичээлд шинэ Python байхгүй. Зөвхөн арга барил.

Шударга үнэн: хэн ч бүгдийг мэддэггүй

Эхлээд нэг зүйлийг тодруулъя, учир нь тэр нь эхлэгчдийг ихэвчлэн зовоодог.

Мэргэжлийн программистууд бүх зүйлийг цээжээр мэддэггүй.

Тэд:

• Documentation -ыг өдөр бүр уншдаг

• Функцийн параметрүүдийг хайдаг

• "Яаж хийх вэ" гэж google хийдэг

• Өөрсдийн хуучин кодоо хуулдаг

Ялгаа нь: тэд ХУРДАН олдог.

Тэд документыг хаанаас эхлэх, юуг алгасах, юуг анхаарахыг мэднэ.

Тэр бол ур чадвар. Мөн түүнийг сурч болно.

Хэрэв та "би цээжлэх ёстой" гэж бодож байвал — тэр нь буруу. Цээжлэх шаардлагагүй. ОЛОХ чадвартай байх л хангалттай.

Documentation -ийн ХОЁР төрөл

Бүх сайн documentation нь ХОЁР ХЭСГЭЭС бүрддэг. Тэдгээр нь ТЭС ӨӨР зорилготой.

1. TUTORIAL (заавар)

Зорилго: СУРГАХ.

• Дарааллаар уншина: 1 → 2 → 3

• Жишээгээр тайлбарлана

• "Эхлээд үүнийг хий, дараа нь тэрийг"

• Хэрэглэгчийг ГАРААС хөтлөнө

Хэзээ уншина: шинэ сан СУРАХ гэж байгаа үед.

Эхнээс нь эхэлж, дараалан уншина.

2. REFERENCE (лавлах)

Зорилго: ОЛОХ.

• Дарааллаар уншихгүй

• Функц бүрийн БҮХ параметр

• Хуурай, техникийн

• "Энэ функц нь эдгээр аргументыг авдаг"

Хэзээ уншина: тодорхой зүйлийг ХАЙХ үед.

Шууд хэрэгтэй газраа үсэрч очно.

АНХААР: Reference -ыг ЭХНЭЭС НЬ дарааллаар уншиж БОЛОХГҮЙ. Тэр нь толь бичгийг эхнээс нь уншихтай адил — уйтгартай, ашиггүй.

FastAPI-гийн documentation -ыг задалъя

Одоо БОДИТ жишээ. FastAPI-гийн documentation -ыг нээе:

fastapi.tiangolo.com

Зүүн талын цэсийг хараарай:

FastAPI
├── Features
├── Installation
│
├── Tutorial - User Guide          ← TUTORIAL
│   ├── First Steps
│   ├── Path Parameters
│   ├── Query Parameters
│   ├── Request Body
│   ├── Query Parameters and String Validations
│   ├── Path Parameters and Numeric Validations
│   ├── Body - Multiple Parameters
│   ├── ...
│   └── Testing
│
├── Advanced User Guide            ← ГҮНЗГИЙ TUTORIAL
│   ├── ...
│
└── Reference                      ← REFERENCE
    ├── FastAPI class
    ├── Request Parameters
    ├── ...

Танил бүтэц үү?

"Tutorial - User Guide" — эхнээс нь дарааллаар уншина.

"Reference" — зөвхөн хайхад.

Хаанаас ЭХЛЭХ вэ

Шинэ сан сурах ЗӨВ дараалал:

Алхам 1: "Installation" — суулгах

pip install fastapi uvicorn

Та түүнийг хийсэн.

Алхам 2: "First Steps" эсвэл "Quick Start"

Хамгийн энгийн ажиллагаатай жишээ.

FastAPI-гийн "First Steps" нь:

python

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

Танил үү? Та түүнийг Хичээл 15.2-т бичсэн.

ЭНЭ АЛХМЫГ АЛГАСАЖ БОЛОХГҮЙ. Ажиллагаатай жижиг зүйл нь итгэл өгдөг.

Алхам 3: Tutorial -ыг ДАРААЛЛААР

FastAPI-гийн tutorial нь ойролцоогоор 20 хуудас.

Эхний 5-6 хуудас нь 80% -ийг хамарна:

1. First Steps

2. Path Parameters

3. Query Parameters

4. Request Body

5. Query Parameters and String Validations

6. Response Model

Тэдгээрийг уншсны дараа та ажиллах API бичиж чадна.

Алхам 4: ЗОГС

Бүх tutorial -ыг УНШИХ ШААРДЛАГАГҮЙ.

Хэрэгтэй болоход буцаж ирнэ.

Хэрэв та authentication бичихгүй бол — тэр бүлгийг уншихгүй. Хэрэв WebSocket ашиглахгүй бол — тэр бүлгийг уншихгүй.

Эрт сурах нь цаг үрдэг. Та түүнийг мартна.

Reference -ыг ЯАЖ ашиглах вэ

Одоо reference руу орно.

Reference -ыг УНШИХГҮЙ. Түүнийг ХАЙНА.

Практик жишээ:

Та FastAPI() объект үүсгэж байна. title ба version -ыг мэднэ. Гэхдээ өөр юу байдаг вэ?

Гурван арга:

Арга 1: Editor -оос

VS Code дээр:

python

app = FastAPI(

Хаалт бичмэгц — VS Code нь БҮХ параметрийг харуулна:

FastAPI(
    *,
    debug: bool = False,
    routes: List[BaseRoute] | None = None,
    title: str = "FastAPI",
    summary: str | None = None,
    description: str = "",
    version: str = "0.1.0",
    openapi_url: str | None = "/openapi.json",
    docs_url: str | None = "/docs",
    redoc_url: str | None = "/redoc",
    ...
)

Type hint -үүд БҮГД харагдаж байна!

• title: str = "FastAPI" → string, default нь "FastAPI"

• docs_url: str | None = "/docs" → /docs хаягийг ӨӨРЧИЛЖ болно!

Бүлэг 4-ийн type hint нь ЭНД ажиллаж байна.

Editor нь ТАНЫ хамгийн хурдан documentation.

Арга 2: help()

Python дотроос:

python

from fastapi import FastAPI

help(FastAPI)

Docstring нь хэвлэгдэнэ.

Эсвэл тодорхой method:

python

help(FastAPI.get)

Арга 3: Онлайн reference

FastAPI → Reference → FastAPI class

Тэнд БҮХ параметр, тайлбартай.

Аль нь хамгийн хурдан вэ?

Editor. Тэр нь та бичиж байхад л харуулна.

Documentation -ийн ХУУДСЫГ ЯАЖ УНШИХ вэ

Одоо нэг хуудсыг задалъя.

FastAPI → Tutorial → Query Parameters

Ердийн бүтэц:

1. ГАРЧИГ                    Query Parameters

2. ТАЙЛБАР                   "When you declare other function 
                              parameters that are not part of 
                              the path parameters, they are 
                              automatically interpreted as 
                              query parameters."

3. КОД ЖИШЭЭ                 @app.get("/items/")
                             async def read_item(skip: int = 0, limit: int = 10):
                                 return fake_items_db[skip : skip + limit]

4. ТАЙЛБАР                   "The query is the set of key-value 
                              pairs that go after the ? in a URL..."

5. ХЭРЭГЛЭЭ                  http://127.0.0.1:8000/items/?skip=0&limit=10

6. НЭМЭЛТ ТОХИОЛДЛУУД        Optional parameters
                             Query parameter type conversion
                             Multiple path and query parameters
                             Required query parameters

УНШИХ ДАРААЛАЛ:

1. ЭХЛЭЭД КОД ЖИШЭЭГ хараарай.

Тэр нь хамгийн хурдан ойлголт өгнө. Хэрэв та кодыг ойлгож байвал — текстийн ихэнхийг алгасаж болно.

python

async def read_item(skip: int = 0, limit: int = 10):

Танил үү? skip: int = 0 — type hint + default утга. Та түүнийг мэднэ.

2. Дараа нь ТАЙЛБАРЫГ уншаарай — зөвхөн хэрэгтэй бол.

3. Нэмэлт тохиолдлуудыг АЛГАСААРАЙ — тэдгээр нь хэрэгтэй болоход л.

Заль: КОД → ТАЙЛБАР, ТАЙЛБАР → КОД БИШ

Эхлэгчид ихэвчлэн текстийг эхнээс нь дарааллаар уншдаг.

Тэр нь УДААН.

Туршлагатай программистууд ЭХЛЭЭД КОДЫГ хардаг.

Учир нь:

• Код нь ТОДОРХОЙ — тэр нь юу хийхийг ЯГ хэлдэг

• Текст нь БҮРХЭГ — тэр нь тайлбарладаг

• Код нь БОГИНО — 5 мөр vs 3 догол мөр

Хэрэв та кодыг харж, ойлгосон бол — текст хэрэггүй.

Хэрэв ойлгохгүй бол — тэр үед текстийг уншаарай.

Юуг АЛГАСАХ вэ

Documentation нь БҮГДИЙГ хамардаг. Гэвч танд бүгд хэрэггүй.

АЛГАСААРАЙ:

1. "Advanced" бүлгүүд — эхлээд үндсийг эзэмш.

2. Таны хэрэглээнд хамааралгүй хэсгүүд.

WebSocket ашиглахгүй бол — тэр бүлгийг алгас. GraphQL, background tasks, custom middleware — бүгд алгас.

3. Хэт нарийн тохиргоо.

Ихэнх параметр нь зөв default утгатай. Тэдгээрийг өөрчлөх шаардлагагүй.

4. "Migration" эсвэл "Changelog" — хуучин хувилбараас шилжих зааврууд.

АНХААР:

1. Quick Start / First Steps — ЗААВАЛ.

2. Үндсэн ойлголтууд (FastAPI-гийн хувьд: path, query, body, response model).

3. АЛДАА ЗОХИЦУУЛАЛТ — ихэнх хүн алгасдаг, дараа нь зовдог.

4. "Common Pitfalls" эсвэл "Gotchas" — хэрэв байвал ЗААВАЛ уншаарай. Тэдгээр нь бусад хүмүүсийн зовлонгоос сурсан зүйлс.

Хэзээ Google хийх вэ

Documentation бүх зүйлийг хамардаггүй.

Заримдаа танд ЯГ ТОДОРХОЙ асуулт байдаг:

• "FastAPI яаж файл upload хийх вэ?"

• "FastAPI CORS яаж тохируулах вэ?"

Тэр үед Google.

САЙН хайлт:

fastapi file upload
fastapi cors
python requests timeout
pandas read csv encoding

Формат: [сангийн нэр] [юу хийх гэж байгаа]

МУУ хайлт:

python яаж файл upload хийх вэ
how to do the thing with the api

Хэт ерөнхий, хэт урт.

Хайлтын үр дүнг ЯАЖ шүүх вэ

Google хийхэд олон үр дүн гарна. Аль нь сайн вэ?

ЭХЛЭЭД:

1. Албан ёсны documentation — хамгийн найдвартай, хамгийн шинэ.

Хэрэв тэр нь эхний үр дүнд байвал — түүнийг л дар.

2. GitHub -ийн албан ёсны repo — issue, discussion.

ДАРАА НЬ:

3. Stack Overflow — сайн, гэхдээ ОГНООГ ШАЛГА.

АНХААРУУЛГА: 2015 оны хариулт нь ХУУЧИРСАН байж болно.

Python, сангууд өөрчлөгддөг. Хуучин хариулт нь ажиллахгүй байж болно, эсвэл хуучин арга барил заасан байж болно.

Дүрэм: 2-3 жилээс хуучин хариултыг болгоомжтой ав.

БОЛГООМЖТОЙ:

4. Блог нийтлэл — чанар нь маш хэлбэлзэлтэй.

Заримдаа гайхалтай. Заримдаа буруу.

Огноог шалга. Кодыг өөрөө туршиж үз.

AI -тай documentation унших

Одоо орчин үеийн бодит зөвлөгөө.

AI (ChatGPT, Claude гэх мэт) нь documentation унших ХУРДАН арга байж болно.

САЙН хэрэглээ:

• "FastAPI -д query parameter яаж ажилладаг вэ, богино жишээгээр тайлбарлаач"

• "Энэ кодыг тайлбарлаач: [код наах]"

• "Энэ алдаа юу гэсэн үг вэ: [алдаа наах]"

МУУ хэрэглээ:

• "Надад бүтэн API бичиж өгөөч" → та юу ч сурахгүй

• Кодыг ойлголгүй хуулах → дараа нь засаж чадахгүй

ХАМГИЙН АЮУЛТАЙ:

AI нь ЗААРИМДАА БУРУУ ХЭЛДЭГ. Тэр нь байхгүй функц зохиож болно, хуучин арга заасан байж болно.

ДҮРЭМ:

AI -ийн хариултыг ҮРГЭЛЖ албан ёсны documentation -оор ШАЛГА.

Мөн кодыг ӨӨРӨӨ АЖИЛЛУУЛЖ үз.

AI бол ХУРДАН ТАЙЛБАРЛАГЧ, гэхдээ ЭЦСИЙН ЭХ СУРВАЛЖ БИШ.

Алдааны мессежийг ЯАЖ унших вэ

Documentation -ээс илүү чухал ур чадвар: АЛДАА УНШИХ.

Энэ курсийн турш бид олон алдаа харсан. Одоо тэдгээрийг ЯАЖ унших тухай.

Алдааны мессеж нь ГУРВАН хэсэгтэй:

Traceback (most recent call last):
  File "main.py", line 15, in nom_avakh          ← 1. ХААНА
    nom = nomnuud[nom_id]
KeyError: 999                                     ← 2. ЮУ + 3. АЛЬ УТГА

УНШИХ ДАРААЛАЛ:

1. ХАМГИЙН СҮҮЛЧИЙН МӨРИЙГ уншаарай.

KeyError: 999 — тэр нь ЖИНХЭНЭ асуудал.

Дээрх бүх зүйл нь зөвхөн "яаж энд хүрсэн" гэсэн зам.

2. АЛДААНЫ ТӨРЛИЙГ таньж ав.

• KeyError → dictionary -д key байхгүй

• AttributeError → объектод тэр талбар/method байхгүй

• TypeError → буруу төрөл

• ValueError → зөв төрөл, буруу утга

• ModuleNotFoundError → (venv) шалга!

3. ФАЙЛ, МӨРИЙГ ол.

File "main.py", line 15 — яг тэнд оч.

4. Хэрэв ойлгохгүй бол — АЛДААНЫ МЕССЕЖИЙГ GOOGLE хий.

Гэхдээ ЗӨВ хэсгийг:

KeyError: 999                          ← БУРУУ (тодорхой утга)
python KeyError dictionary             ← ЗӨВ

Тодорхой утгуудыг (999, файлын нэр, таны хувьсагчийн нэр) АВЧ хая.

Хамгийн чухал зөвлөгөө: АЖИЛЛУУЛЖ ХАР

Documentation унших нь ХАНГАЛТГҮЙ.

Кодыг АЖИЛЛУУЛЖ, өөрчилж, эвдэж үзээрэй.

Бүлэг 11.4-ийн сургамжийг санаж байна уу?

"ХАМГИЙН ЧУХАЛ ЗӨВЛӨГӨӨ: ЭХЛЭЭД ХАР, ДАРАА НЬ БИЧ."

Ижил зарчим:

1. Documentation -оос жишээ ХУУЛ

2. АЖИЛЛУУЛ — ажиллаж байгаа эсэхийг батал

3. ӨӨРЧИЛ — параметр солиж үз

4. ЭВД — зориудаар буруу утга өгч, алдааг хар

Тэр дөрвөн алхам нь ямар ч уншлагаас илүү ойлголт өгнө.

Бүлэг 15.2-т та яг үүнийг хийсэн: /docs дээр "Try it out" дарж, буруу өгөгдөл илгээж, 422 алдааг харсан.

Тэр бол сурах ЗӨВ арга.

Практик дасгал: FastAPI-гийн documentation

Одоо БОДИТ дасгал хийе.

Даалгавар: FastAPI -д Response Model гэж юу вэ?

Алхам 1: FastAPI documentation -г нээ.

Алхам 2: Tutorial → "Response Model" -ыг ол.

Алхам 3: ЭХЛЭЭД КОД ЖИШЭЭГ хар:

python

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI()


class UserIn(BaseModel):
    username: str
    password: str
    email: EmailStr
    full_name: str | None = None


class UserOut(BaseModel):
    username: str
    email: EmailStr
    full_name: str | None = None


@app.post("/user/", response_model=UserOut)
async def create_user(user: UserIn) -> Any:
    return user

Юу анзаарав?

• ХОЁР class: UserIn (оролт) ба UserOut (гаралт)

• UserOut -д password БАЙХГҮЙ!

• response_model=UserOut — keyword argument (Бүлэг 3.2)

Ойлголт: FastAPI нь хариултаас password -ыг АВЧ ХАЯНА.

Тэр бол АЮУЛГҮЙ БАЙДЛЫН зүйл. Хэрэглэгчийн нууц үгийг буцааж болохгүй.

Бүлэг 9.2-ын field(repr=False) -тэй ижил санаа — нууц мэдээллийг нуух.

Алхам 4: Одоо ӨӨРӨӨ туршаад үз.

Хичээл 15.2-ийн кодод нэмээрэй:

python

class NomOut(BaseModel):
    garchig: str
    zokhiolch: str
    on: int
    # khuudas БАЙХГҮЙ
    # tailbar БАЙХГҮЙ


@app.get("/nomnuud/{nom_id}/tovch", response_model=NomOut)
def nom_tovch(nom_id: int) -> Nom:
    nom = nomnuud.get(nom_id)
    if nom is None:
        raise HTTPException(status_code=404, detail="Олдсонгүй")
    return nom

Browser -ээр:

http://127.0.0.1:8000/nomnuud/1/tovch

json

{"garchig":"Монголын нууц товчоо","zokhiolch":"Тодорхойгүй","on":1240}

khuudas ба tailbar АЛГА!

FastAPI нь тэднийг ШҮҮЖ хаясан.

Та documentation -оос шинэ зүйл сурч, түүнийг ӨӨРИЙН кодод хэрэглэлээ.

Тэр бол ЖИНХЭНЭ сурах явц.

Хэрхэн САЙН асуулт асуух вэ

Эцэст нь: хэзээ нэгэн цагт та ГАЦНА. Тэр үед асуух хэрэгтэй болно.

Форум, Stack Overflow, эсвэл AI -аас.

САЙН асуулт нь ДӨРВӨН зүйл агуулна:

1. Юу хийх ГЭЖ БАЙНА ВЭ

"Би FastAPI -д зураг upload хийхийг хүсэж байна."

2. ЮУ ХИЙСЭН БЭ (код)

python

@app.post("/upload")
def zurag_upload(fail):
    ...

3. ЮУ БОЛСОН БЭ (яг алдаа)

TypeError: fail() missing 1 required positional argument

4. ЮУ ХҮЛЭЭЖ БАЙСАН БЭ

"Зураг хадгалагдана гэж бодсон."

МУУ асуулт:

"FastAPI ажиллахгүй байна. Тусалж өгөөч."

Хэн ч тусалж чадахгүй. Мэдээлэл байхгүй.

САЙН асуулт нь өөрөө ихэвчлэн ХАРИУЛТЫГ илрүүлдэг.

Асуултаа бичиж байхдаа та кодоо дахин уншиж, алдаагаа өөрөө олох нь маш түгээмэл. Программистууд түүнийг "rubber duck debugging" гэж нэрлэдэг — асуудлаа хэн нэгэнд (эсвэл резинэн нугаст) тайлбарлахад л шийдэгддэг.

Товч дүгнэлт

• Хэн ч бүх зүйлийг цээжээр мэддэггүй. Мэргэжлийн программистууд documentation -ыг өдөр бүр уншдаг. Ялгаа нь: тэд ХУРДАН олдог.

• Documentation ХОЁР төрөлтэй:

  • TUTORIAL — СУРГАХ. Эхнээс нь ДАРААЛЛААР уншина.

  • REFERENCE — ОЛОХ. Дарааллаар УНШИХГҮЙ, зөвхөн хайна.

• Шинэ сан сурах ДАРААЛАЛ:

  1. Installation

  2. First Steps / Quick Start — ЗААВАЛ, алгасаж болохгүй

  3. Tutorial -ын эхний 5-6 хуудас (80% -ийг хамарна)

  4. ЗОГС. Хэрэгтэй болоход буцаж ирнэ. Эрт сурах нь цаг үрдэг.

• Reference -ыг ХАЙХ гурван арга:

  1. EDITOR (VS Code) — хамгийн хурдан. Type hint -үүд шууд харагдана.

  2. help(функц)

  3. Онлайн reference

• ЗАЛЬ: КОД → ТАЙЛБАР, ТАЙЛБАР → КОД БИШ.

  • Эхлээд КОД ЖИШЭЭГ хар. Ойлгосон бол — текст хэрэггүй.

  • Код нь ТОДОРХОЙ, текст нь БҮРХЭГ.

• АЛГАСААРАЙ: "Advanced", хамааралгүй хэсгүүд, нарийн тохиргоо.

• АНХААР: Quick Start, үндсэн ойлголтууд, алдаа зохицуулалт, "Common Pitfalls".

• Google: [сангийн нэр] [юу хийх гэж байгаа]. Албан ёсны docs → GitHub → Stack Overflow (ОГНООГ ШАЛГА!) → блог (болгоомжтой).

• AI: хурдан тайлбарлагч, гэхдээ ЭЦСИЙН ЭХ СУРВАЛЖ БИШ. ҮРГЭЛЖ албан ёсны docs -оор шалга, кодыг ӨӨРӨӨ ажиллуул.

• АЛДАА УНШИХ:

  1. ХАМГИЙН СҮҮЛЧИЙН МӨРИЙГ унш — тэр нь жинхэнэ асуудал

  2. Алдааны ТӨРЛИЙГ таньж ав

  3. Файл, мөрийг ол

  4. Google -д зөв хэсгийг оруул (тодорхой утгуудыг хая)

• ХАМГИЙН ЧУХАЛ: АЖИЛЛУУЛЖ ХАР.

  1. ХУУЛ → 2. АЖИЛЛУУЛ → 3. ӨӨРЧИЛ → 4. ЭВД

  • Тэр дөрвөн алхам нь ямар ч уншлагаас илүү ойлголт өгнө.

• САЙН АСУУЛТ = юу хийх гэж байна + юу хийсэн (код) + юу болсон (алдаа) + юу хүлээж байсан.

  • Сайн асуулт нь өөрөө ихэвчлэн хариултыг илрүүлдэг ("rubber duck debugging").

Энэ бол таны цаашдын аяллын ХАМГИЙН ЧУХАЛ ур чадвар.

Курс дуусна. Сангууд өөрчлөгдөнө. Шинэ framework гарч ирнэ.

Гэвч documentation унших чадвар нь ҮҮРД хэвээр үлдэнэ.

Дараагийн хичээл нь СҮҮЛЧИЙНХ. Тэнд бид:

• Та ЮУГ эзэмшсэнийг бүрэн харна

• Одоо ЯГ ЮУ хийж чадахыг шударгаар хэлнэ

• Цаашдын замын ХУВИЛБАРУУДЫГ танилцуулна

• Мөн би багшийн хувьд танд эцсийн үгээ хэлнэ

Хамтдаа явсан замын төгсгөл ойртож байна.