- Vyberte si medzi rozložením založeným na type súboru alebo na funkciách na základe veľkosti projektu, architektúry a potrieb tímu, pričom konzistencia je najvyššou prioritou.
- Využite nápovedy typov FastAPI, modely Pydantic a vkladanie závislostí, aby ste udržali smerovanie tenké, logiku modulárnu a validáciu výkonnú a opakovane použiteľnú.
- Štruktúrujte bezpečnosť, testovanie, asynchrónny I/O a konfiguráciu ako prvotriedne záležitosti, aby škálovanie na produkčný systém a viacero tímov nevyžadovalo úplné prepísanie.
- Prijmite jasné konvencie pomenovávania, migrácie a nástrojov, aby ste udržali rastúcu flotilu monolitov alebo mikroslužieb FastAPI udržiavateľnú v priebehu času.
Navrhnutie čistej a škálovateľnej štruktúry pre projekt FastAPI je jedno z tých rozhodnutí, ktoré sa na začiatku zdajú byť malicherné, ale o šesť mesiacov neskôr vám úplne zmenia život., keď sa kódová základňa rozrástla, tím sa rozšíril a vy sa snažíte vysledovať chybu vo viacerých moduloch. Dobré rozloženie urýchľuje onboarding, znižuje regresie a robí refaktoringy oveľa menej bolestivými.
FastAPI vám poskytuje obrovskú flexibilitu, ale to tiež znamená, že si musíte aktívne vyberať a presadzovať konvencie.V tejto príručke zhromaždíme najužitočnejšie nápady z reálnych produkčných projektov FastAPI a známych repozitárov osvedčených postupov, porovnáme hlavné rozloženia projektov a pozrieme sa, ako interagujú so základnými konceptmi FastAPI, ako je vkladanie závislostí, validácia, asynchrónny I/O, testovanie a nasadenie.
Prečo je štruktúra projektu v FastAPI taká dôležitá
Pevná štruktúra je chrbticou, ktorá udržiava aplikáciu FastAPI zrozumiteľnou, aj keď rastie na veľkosti a zložitosti.Bez neho sa aj framework s vynikajúcou ergonómiou rýchlo zmení na kopu ad-hoc modulov, cyklického importu a duplicitnej logiky.
Z inžinierskeho hľadiska štruktúra priamo ovplyvňuje škálovateľnosťKeď sú moduly oddelené a zodpovednosti sú jasné, môžete rozdeliť služby, zaviesť fronty alebo škálovať rôzne časti systému nezávisle bez toho, aby ste museli všetko prepisovať.
Udržiavateľnosť je ďalším veľkým víťazstvomKeď má každá trasa, schéma a model databázy predvídateľný domov, vývojári strácajú menej času vyhľadávaním súborov a viac času riešením skutočných obchodných problémov. Taktiež sa stáva jednoduchším vykonávať kontroly kódu, pretože všetci zdieľajú rovnaký mentálny model.
V tímových projektoch konzistentné rozloženie výrazne zlepšuje spoluprácuNoví zamestnanci môžu odvodiť, kam umiestniť nové funkcie, QA môže objaviť správne vstupné body na testovanie a DevOps môžu pochopiť, ktoré časti sú kľúčové pre spustenie aplikácie (napríklad kde sa nachádza objekt aplikácie ASGI a ako je zapojená databáza).
Základné princípy štruktúrovania projektov FastAPI
Pred výberom rozloženia priečinkov je užitočné dohodnúť sa na niekoľkých zásadách, ktorými by sa malo riadiť každé rozhodnutie o architektúreTieto nápady sa opakovane objavujú v úspešných kódových bázach FastAPI.
Oddelenie záujmov je prvým pilierom: udržiavať smerovanie, perzistenciu, obchodné pravidlá a integračný kód na rôznych miestach. Koncové body by mali organizovať prípady použitia, nie vkladať SQL dotazy, manipuláciu s JSON a volania externých služieb do jednej dlhej funkcie.
Modularita je druhým pilieromNamiesto jedného obrovského monolitického balíka sa zamerajte na menšie, cielené moduly alebo podbalíky, ktoré zapuzdrujú súvisiace správanie. To výrazne uľahčuje opätovné použitie častí, ich testovanie izolovane a v prípade potreby ich rozdelenie do mikroslužieb.
Injektovanie závislostí je lepidlo, ktoré spája tieto moduly bez tesného prepojenia.Systém závislostí FastAPI vám umožňuje deklarovať, čo trasa alebo služba potrebuje (databázová relácia, konfigurácia, overený používateľ atď.) a nechať to poskytnúť frameworku, čo je ideálne pre testovateľnosť a opätovné použitie.
Samotná testovateľnosť sa musí považovať za prvotriednu požiadavkuAk štruktúra sťažuje spúšťanie aplikácie v pamäti, prepisovanie závislostí a dosahovanie koncových bodov testovacím klientom, buď preskočíte testy, alebo budete bojovať proti vlastnej architektúre. Dobrá štruktúra udržiava vedľajšie účinky lokálne a cesty importovateľné z testov.
Dve dominantné rozloženia projektov FastAPI: podľa typu súboru verzus podľa funkcie
V ekosystéme FastAPI zvyčajne nájdete dve jasné rodiny rozložení: projekty usporiadané podľa typu súboru (routery, modely, schémy, CRUD) a projekty usporiadané podľa domény alebo funkcie (autorizácia, používatelia, príspevky, platby atď.). Každý z nich sa prejavuje v inom kontexte.
Štruktúra založená na type súboru (smerovače, schémy, modely, CRUD)
Prístup k súborovým typom odráža, ako mnoho oficiálnych príkladov a tutoriálov predstavuje FastAPI.Kód zoskupujete podľa jeho technickej úlohy: smerovacia vrstva, pydantické schémy, databázové modely, operácie CRUD, utility atď.
Minimálne, ale realistické rozloženie by mohlo vyzerať takto (skrátené pre prehľadnosť):
Príklad rozloženia: .├── app
│ ├── __init__.py
│ ├── main.py # FastAPI app initialization
│ ├── dependencies.py # shared dependencies
│ ├── routers
│ │ ├── __init__.py
│ │ ├── items.py # endpoints for items
│ │ └── users.py # endpoints for users
│ ├── crud
│ │ ├── item.py # item CRUD
│ │ └── user.py # user CRUD
│ ├── schemas
│ │ ├── item.py # pydantic models for items
│ │ └── user.py # pydantic models for users
│ ├── models
│ │ ├── item.py # ORM models for items
│ │ └── user.py # ORM models for users
│ ├── external_services
│ │ ├── email.py # email provider client
│ │ └── notification.py # push / notification client
│ └── utils
│ ├── authentication.py
│ └── validation.py
├── tests
│ ├── test_main.py
│ ├── test_items.py
│ └── test_users.py
├── requirements.txt
└── README.md
V tomto štýle každý adresár najvyššej úrovne pod app/ má jednu zodpovednosť, Napríklad, routers/ popisuje vstupné body HTTP, schemas/ deklaruje vstupné/výstupné tvary a models/ predstavujú databázové tabuľky.
Toto rozloženie zvyčajne funguje mimoriadne dobre pre malé až stredné služby alebo mikroslužby.Doména je zvyčajne dostatočne úzka, takže rozdelenie podľa technických rolí nespôsobuje trenie. Väčšina koncových bodov používa rovnakú obmedzenú sadu modelov a kódu sa súčasne dotýka iba niekoľko tímov.
Medzi kľúčové výhody štruktúry súborového typu patrí veľmi nízka kognitívna záťaž pre začiatočníkov. a adresárový strom, ktorý dôsledne sleduje dokumentáciu FastAPI. Pre niekoho, kto sa učí framework, je vhodné vidieť vyhradený routers/ priečinok a a schemas/ Priečinok sa často zdá intuitívnejší ako priamy prechod na balíky riadené doménou.
Štruktúra orientovaná na funkcie alebo moduly pod src/
Ako sa projekty rozrastajú do monolitov s mnohými doménami, rozloženie typov súborov začína vŕzgať.Získate obrovské adresáre, ako napríklad routers/ s desiatkami súborov, zložitými importmi medzi modulmi a obchodnou logikou roztrúsenou po nesúvisiacich balíkoch.
Alternatívou, ktorá sa lepšie škáluje, je štruktúra založená na funkciách alebo riadená doménou.Tu umiestnite všetok kód pre konkrétnu doménu do jedného podbalíka: trasy, schémy, modely, služby, konfiguráciu a výnimky špecifické pre moduly.
Reprezentatívne rozloženie inšpirované populárnymi repozitármi osvedčených postupov vyzerá takto:
Reprezentatívny strom súborov: fastapi-project
├── alembic/
├── src
│ ├── auth
│ │ ├── router.py # auth endpoints
│ │ ├── schemas.py # pydantic models
│ │ ├── models.py # DB models
│ │ ├── dependencies.py # auth-specific dependencies
│ │ ├── config.py # local configs
│ │ ├── constants.py # auth error codes / constants
│ │ ├── exceptions.py # auth-specific exceptions
│ │ ├── service.py # business logic
│ │ └── utils.py # helpers
│ ├── aws
│ │ ├── client.py
│ │ ├── schemas.py
│ │ ├── config.py
│ │ ├── constants.py
│ │ ├── exceptions.py
│ │ └── utils.py
│ ├── posts
│ │ ├── router.py
│ │ ├── schemas.py
│ │ ├── models.py
│ │ ├── dependencies.py
│ │ ├── constants.py
│ │ ├── exceptions.py
│ │ ├── service.py
│ │ └── utils.py
│ ├── config.py # global configs
│ ├── models.py # shared DB models
│ ├── exceptions.py # shared exceptions
│ ├── pagination.py # reusable pagination logic
│ ├── database.py # DB connection & session management
│ └── main.py # FastAPI app factory / entry point
├── tests
│ ├── auth
│ ├── aws
│ └── posts
├── templates
│ └── index.html
├── requirements
│ ├── base.txt
│ ├── dev.txt
│ └── prod.txt
├── .env
├── logging.ini
└── alembic.ini
V tomto svete, src/ je vrcholom interného stromu aplikáciíKaždá doména, ako napríklad auth or posts, stáva sa takmer mini-službou: má svoj vlastný smerovač, schémy, modely, konštanty, typy chýb a vrstvu obchodných služieb.
Hlavnou výhodou je lokálnosť zmeny: keď pridáte novú funkciu do posts, len zriedka sa musíte dotknúť akéhokoľvek nesúvisiaceho balíka. Testy môžu byť tiež umiestnené spolu so svojimi funkciami (napríklad pod tests/posts/), čo podporuje vyššie pokrytie.
Táto štruktúra je obzvlášť vhodná pre monolitické aplikácie s mnohými doménami a tímami, kde chcete podporovať paralelnú prácu a redukovať konflikty zlúčenia. Taktiež sa dobre hodí k konceptom dizajnu riadeným doménou, ako sú ohraničené kontexty a agregáty.
Výber správneho rozloženia pre váš projekt FastAPI
Výber medzi typom súboru a štruktúrou založenou na funkciách nie je o správnom alebo nesprávnom, ale o zosúladení vašej architektúry s očakávaniami rastu.Malý interný nástroj s len hŕstkou koncových bodov nebude mať veľký úžitok z prepracovaného rozloženia domény.
Pre mikroslužby a úzko vymedzené API je rozloženie typov súborov zvyčajne jednoduchšie.Každá služba sa často zameriava na jednu zodpovednosť (fakturačné API, odosielateľ upozornení, mikroslužba pre tvorbu prehľadov) a vývojári už intuitívne vedia, kam umiestniť nové trasy alebo schémy.
Pri väčších monolitoch je rozdelenie podľa domény z dlhodobého hľadiska takmer vždy výhodné.Keď máte moduly pre profily, predplatné, obsah, platby, analytiku a ďalšie, umiestnenie každého smerovača do jedného adresára sa stáva chaotickým. Zoskupovanie podľa funkcie udržiava každú časť systému samostatnú.
Zvážte aj štruktúru vášho tímuAk jeden malý tím vlastní celú kódovú základňu, konzistencia sa môže ľahšie udržiavať s jednoduchým rozložením. Ak viacero tímov zdieľa monolit a každý z nich vlastní oblasť domény, štruktúra založená na funkciách im umožňuje pohybovať sa rýchlejšie bez toho, aby si navzájom šliapali po pätách.
Nech si vyberiete čokoľvek, konzistencia je dôležitejšia ako presný tvar stromu.Zmena rozloženia uprostred projektu je bolestivá, takže investovať trochu premýšľania v ranom štádiu a napísať krátky interný sprievodca štýlom sa neskôr vyplatí.
Pochopenie samotného FastAPI: čo štruktúrujete
Na navrhnutie rozumnej štruktúry potrebujete jasný mentálny model toho, čo pre vás FastAPI skutočne robí.FastAPI je vo svojej podstate webový framework ASGI zameraný na vytváranie HTTP API s Pythonom 3.7+ pomocou typových náznakov.
FastAPI sa pri overovaní údajov a serializácii silne opiera o PydanticPonúka oveľa viac než len jednoduché polia „povinné verzus voliteľné“; môžete priamo na svojich modeloch vyjadriť rozsiahle obmedzenia a transformácie.
Keďže schéma OpenAPI je odvodená priamo z vašich koncových bodov a modelov, FastAPI generuje aj interaktívnu dokumentáciu.Hneď po vybalení získate používateľské rozhranie Swagger na adrese /docs a ReDoc na /redoc, ktoré sú neoceniteľné pri spolupráci s frontendovými vývojármi alebo integrátormi tretích strán.
Pod kapotou beží FastAPI na serveroch ASGI, ako je Uvicorn.Vďaka tomu vaša aplikácia efektívne spracováva viacero súbežných pripojení a bez dodatočných ceremónií umožňuje funkcie, ako sú dlhotrvajúce pripojenia WebSocket.
FastAPI je tiež explicitný ohľadom požiadaviek a odpovedíKaždý koncový bod je len bežná funkcia Pythonu (sync alebo async) ozdobená @app.get, @app.post a priatelia, ktorí prijímajú údaje o ceste/dotaze/tele a vracajú odpoveď, zvyčajne dict alebo Pydantic model.
Async vs. synchronizácia: ako sa výkon pretína so štruktúrou
FastAPI je navrhnuté predovšetkým ako asynchrónny framework, ale podporuje asynchrónne aj synchronizačné koncové body.Pochopenie toho, ako sa správajú interne, vám pomôže pri navrhovaní služieb, výbere klientov a štruktúrovaní modulov spracovávajúcich I/O.
Keď vyhlásite async def trasu, FastAPI ju spúšťa priamo v slučke udalostíRámec predpokladá, že akékoľvek dlhotrvajúce operácie vo vnútri budú neblokujúce čakacie objekty, ako napríklad asynchrónny ovládač databázy alebo HTTP klient postavený na... asyncio.
Ak omylom uskutočníte blokujúce hovory (napríklad time.sleep(), slučky náročné na CPU alebo pomalé knižnice, ktoré synchrónne vykonávajú sieťový I/O) v rámci týchto asynchrónnych trás, efektívne zmrazíte slučku udalostíŽiadne ďalšie požiadavky nebudú spracované, kým sa táto operácia nedokončí, čo marí účel asynchrónnosti.
Synchronizačné trasy sa správajú odlišne: FastAPI ich vykonáva v poole vlákienBlokovanie práce v týchto trasách zadržiava iba pracovné vlákno, nie celú slučku udalostí, takže server môže stále prijímať nové požiadavky. Takto zostáva FastAPI flexibilné, keď sa musíte spoliehať na synchrónne knižnice.
Rovnaké zásady platia aj pre závislostiPodporované sú synchronizačné aj asynchrónne závislosti, ale synchronizačné závislosti sa tiež spúšťajú v fonde vlákien. Pre malé pomocné programy, ktoré nie sú I/O, je často lepšie označiť ich ako asynchrónne, aby sa predišlo réžii a obmedzeniam vlákien, keď to nie je potrebné.
Zaťaženie viazané na CPU je samostatný príbehČi už ich spúšťate synchronizovane alebo asynchrónne v rámci procesu, GIL (Global Interpreter Lock) znamená, že bajtkód Pythonu vykonáva naraz iba jedno vlákno. Pri úlohách, ako je spracovanie rozsiahlych dát, transkódovanie obrázkov alebo inferencia strojového učenia, zvážte presunutie práce na pracovníkov v samostatných procesoch alebo externých frontoch.
Overovanie a tvarovanie dát pomocou Pydantic
Pydantic je enginom stojacim za funkciami validácie a serializácie FastAPI.Ponúka oveľa viac než len jednoduché polia „povinné verzus voliteľné“; môžete priamo na svojich modeloch vyjadriť rozsiahle obmedzenia a transformácie.
Medzi typické prípady použitia patrí overovanie dĺžky reťazca, číselných rozsahov, formátov e-mailov alebo zložitých vnorených štruktúr.Modely sa tiež môžu spoliehať na výčty, regulárne výrazy, vlastné validátory a mnoho ďalších nástrojov na dezinfekciu vstupov predtým, ako sa dostanú do vašej obchodnej logiky.
Účinným vzorom je definovať vlastný základný model pre váš projekt.Zdedením všetkých schém z jednej základnej triedy môžete štandardizovať prierezové správanie, ako napríklad formát serializácie dátumu a času, pomocné metódy, ktoré vracajú iba hodnoty bezpečné pre JSON, alebo bežné konfiguračné príznaky.
Pydantic je skvelý na čistú validáciu dát, ale nevie nič o vašej databáze ani externých službách.Ak vaše pravidlá závisia od dotazu (napríklad kontrola existencie ID používateľa alebo jedinečnosti e-mailu), bežným osvedčeným postupom je presunúť tieto validácie do závislostí, a nie do validátorov modelov Pydantic.
Týmto spôsobom zachováte deklaratívny charakter schém a opätovne použijete validácie naprieč viacerými koncovými bodmi.Závislosť môže načítať entitu, vynútiť pravidlá prístupu a vložiť výsledok do trasy, zatiaľ čo FastAPI ukladá svoj výsledok do vyrovnávacej pamäte pre každú požiadavku, aby sa predišlo duplicitnej práci, keď sa tá istá závislosť použije viackrát.
Závislosti ako stavebný kameň čistej architektúry
Systém vkladania závislostí FastAPI nie je len syntaktický cukor pre parametre; je to základný architektonický nástroj.Správne používanie závislostí vám umožňuje zdieľať logiku, vynucovať invarianty a udržiavať trasy veľmi malé a expresívne.
Medzi bežné príklady patria poskytovatelia databázových relácií, konfiguračné zavádzače, pomocníci pri autentifikácii a parsery stránkovania.Namiesto manuálneho otvárania a zatvárania relácií alebo opakovania parametrov stránkovania všade ich deklarujete raz ako závislosti a znova ich použijete.
Nenápadným, ale dôležitým tipom pre dizajn je rozdeliť závislosti na malé, kompozičné jednotky.Namiesto jedného obra get_current_user_with_all_checks funkciu, môžete mať samostatné závislosti na parsovanie JWT, načítanie používateľa, overenie aktivity účtu a kontrolu, či používateľ vlastní daný zdroj.
Keďže FastAPI ukladá výsledky závislostí do vyrovnávacej pamäte v rámci jednej požiadavky, ich zostavenie je lacné.Ak tri rôzne závislosti opakovane používajú pomocníka nižšej úrovne (napríklad pri parsovaní JWT claims), tento pomocník sa spustí iba raz na požiadavku, aj keď sa naň odkazuje viackrát.
Pri navrhovaní trás môže pomenovanie ciest buď pomôcť, alebo brániť opätovnému použitiu závislostíNapríklad, ak niekoľko koncových bodov overí, že profile_id existuje, konzistentné používanie toho istého názvu v parametroch cesty uľahčuje vloženie jednej závislosti, ktorá sa spolieha na profile_id, namiesto vymýšľania mnohých variácií, ako napr. creator_id ktoré nesú rovnaký význam.
Bezpečnosť, autentifikácia a autorizácia vo vašej štruktúre
Bezpečnosť je jednou z oblastí, kde sa jasná štruktúra rýchlo vyplatíPriame zmiešanie logiky autentifikácie s náhodnými trasami sťažuje audit pravidiel prístupu a uľahčuje náhodné odhalenie údajov.
Bežným vzorom v rozloženiach založených na funkciách je mať auth balík s vlastným smerovačom, schémami, vrstvou služieb a výnimkamiTento modul bude spravovať registráciu používateľov, prihlasovacie procesy, vydávanie a overovanie tokenov a môže definovať závislosti ako napríklad get_current_user ktoré importujú ostatné moduly.
V rámci tohto balíka auth môžete podporovať viacero mechanizmov autentifikácie., ako napríklad OAuth2 s heslom a tokenmi nosiča, kľúče API pre volania medzi službami alebo tokeny založené na JWT pre bezstavové API. FastAPI fastapi.security Utility vám tiež pomôžu opísať tieto toky v OpenAPI.
Je dôležité oddeliť autentifikáciu (kto je používateľ) od autorizácie (čo môže robiť).Vaša štruktúra by mala jasne ukazovať, kde sa kontroly oprávnení nachádzajú: napríklad vo vyhradenej vrstve služieb alebo politík namiesto rozptýlených ad-hoc kontrol. if vyhlásenia na každej trase.
Pri práci s heslami dodržiavajte zavedené kryptografické postupyHašujte tajomstvá pomocou pomalého, soleného algoritmu, ako je bcrypt alebo argon2, prostredníctvom renomovaných knižníc, vyhýbajte sa manuálnemu kryptomenovaniu a považujte ukladanie tokenov, ochranu CSRF a bezpečnosť prenosu (HTTPS) za prvotriedne súčasti návrhu.
Efektívne testovanie aplikácií FastAPI
Štruktúra a testovanie sa navzájom posilňujú: prehľadné rozloženie prirodzene vedie k testovanejšiemu kóduS FastAPI môžete testovať na niekoľkých úrovniach, od čisto jednotkových testov služieb až po úplné integračné testy zasahujúce vrstvu HTTP.
Jednotkové testy by sa mali zameriavať na malé časti bez vedľajších účinkovČisté funkcie, validátory Pydantic, obchodné služby, ktoré fungujú s dátami v pamäti. Tieto bývajú veľmi rýchle a predstavujú vašu prvú líniu obrany proti regresiám.
Na precvičovanie skutočných HTTP koncových bodov môžete použiť vstavaného testovacieho klienta založeného na Starlette alebo moderných asynchrónnych klientov, ako napríklad httpxCieľom je importovať vašu aplikáciu, podľa potreby prepísať závislosti (napríklad vložením testovacej databázovej relácie) a odoslať požiadavky bez spustenia externého servera.
Ak pracujete s asynchrónnymi ovládačmi databáz alebo inými asynchrónnymi integráciami, oplatí sa od začiatku nastaviť asynchrónneho testovacieho klienta.Miešanie štýlov synchronizačného a asynchrónneho testovania neskôr často vedie k mätúcim problémom so slučkou udalostí, ktoré je ťažšie ladiť ako jednoducho štandardizovať jeden prístup.
Používanie databázy v testoch tiež interaguje s vašou štruktúrouVďaka centrálnemu database.py Modul, ktorý definuje továrne enginu a relácií, umožňuje jednoduchšie spúšťať testovacie databázy, zabaľovať testy do transakcií alebo používať prípravky, ktoré medzi spusteniami skracujú tabuľky.
Od lokálneho vývoja až po nasadenie v produkcii
Aplikácie FastAPI sa dajú spúšťať lokálne triviálne, ale v produkcii vyžadujú trochu viac plánovania.Štruktúra vášho projektu by mala jasne ukazovať, ako je aplikácia vytvorená, odkiaľ pochádza konfigurácia a ako je prepojené protokolovanie a kontroly stavu.
Pre vývoj väčšina tímov používa Uvicorn s automatickým načítavaním, zvyčajne prostredníctvom príkazu ako uvicorn app.main:app --reload alebo v novších nastaveniach, fastapi devToto poskytuje rýchle spätné väzby a je perfektné pri iterácii.
V produkcii zvyčajne chcete robustnejšie nastavenieWorkery Uvicorn alebo Hypercorn spravované supervízorom procesov alebo WSGI/ASGI wrapperom, ako napríklad Gunicorn, často za reverznou proxy (NGINX alebo spravovaný vyrovnávač záťaže). Cieľom je kontrolovať počet pracovníkov, časové limity a riadené reštarty na základe informácií moderné postupy DevOps.
Konfigurácia by mala byť riadená premennými prostredia, a nie pevne zakódovanými hodnotamiNástroje na správu nastavení Pydantic alebo podobné nástroje vám môžu pomôcť deklarovať triedy typových nastavení a načítať ich pri spustení, čím sa všetky ovládače špecifické pre dané prostredie centralizujú na jednom mieste.
Predtým, ako svoju aplikáciu označíte za pripravenú na produkciu, skontrolujte niekoľko základných informáciíŠtruktúrované protokolovanie, základné metriky, koncové body stavu pre testy živosti a pripravenosti, rozumné limity veľkosti tela a jasné pravidlá týkajúce sa zverejňovania dokumentácie iba v neverejných prostrediach, ak vaše API nie je určené na všeobecné použitie.
Pomenovanie, návrh databázy a migrácie
Súčasťou štruktúry vášho projektu je aj spôsob, akým pomenovávate veci vo svojich modeloch a súboroch schém.Nekonzistentné pomenovanie je jedným z najrýchlejších spôsobov, ako zmiasť vývojárov pracujúcich na kódovej základni, ktorú nevytvorili.
Jednoduchá a účinná konvencia je použiť lower_case_snake názvy tabuliek a stĺpcov, uprednostňujte názvy tabuliek v jednotnom čísle (napríklad post, post_like, user_playlist) a zoskupiť súvisiace tabuľky so spoločnou predponou, ako napríklad payment_ or post_.
Pre časové polia, prípony ako _at pre dátumy a časy a _date pri jednoduchých dátumoch majte veci jasnéPrísnosť v tomto prípade zabraňuje hádaniu typu „je to časová pečiatka alebo dátum?“ pri čítaní schém alebo surových dotazov.
Migrácie si zaslúžia osobitnú pozornosť; mali by byť deterministické, reverzibilné a popisné – zvážte nasledujúce postupy migrácie databázMnoho tímov používa vzorec pre názvy migračných súborov, ako napríklad YYYY-MM-DD_slug.py, čo uľahčuje sledovanie histórie a pochopenie zmien bez čítania celého rozdielu.
V prípade komplexných reportov alebo vnorených odpovedí využite svoju databázu namiesto nadmerného spracovania v Pythone.Moderné SQL enginy dokážu vykonávať spojenia, agregácie a vytváranie JSON oveľa rýchlejšie ako CPython a vrátenie vopred tvarovaných štruktúr do FastAPI často zjednodušuje vaše modely odpovedí.
Nástroje, formátovanie a tímové konvencie
Dobre štruktúrovaný projekt sa ľahšie udržiava v čistote, keď si na presadzovanie štýlových pravidiel zabezpečíte nástroje.Formátovače kódu, lintery a pre-commit hooky vám pomôžu sústrediť sa na obchodnú logiku namiesto hádok o medzier v kóde.
Nástroje ako Ruff sa v poslednej dobe stali populárnymi, pretože kombinujú viacero úloh v jednejNamiesto žonglovania so samostatnými nástrojmi na formátovanie, triedenie importu a linting môžete spustiť jeden rýchly nástroj, ktorý vynucuje stovky pravidiel v celej kódovej základni.
Spúšťanie týchto nástrojov pomocou jednoduchého skriptu alebo pre-commit hookov udržiava bariéru nízkuNie každý tím potrebuje prepracované nastavenie hookov, ale mať aspoň jeden príkaz, ktorý štandardizuje rozloženie kódu, je jednoduchá výhra.
Nakoniec zvážte zdokumentovanie vašich interných konvencií v krátkej „technickej príručke“. ktorý odkazuje agilné metódy vývoja softvéruPopíšte, ako by sa mali moduly pomenovávať, kedy vytvoriť nový doménový balík, ako štruktúrovať testy a ktoré bezpečnostné vzory sú povinné. Toto zabráni tomu, aby vedomosti zostali len v hlavách seniorných vývojárov.
Navrhovanie štruktúry projektu FastAPI je v skutočnosti o tom, aby bola budúca práca predvídateľná a nudná.Keď má každý nový koncový bod, model alebo služba jasné miesto, vývojári sa môžu rýchlo pohybovať bez prekvapení, bezpečnosť sa ľahšie audituje a aplikácia má oveľa väčšiu šancu prežiť rast v reálnom svete bez toho, aby sa zrútila pod vlastnou váhou.
