Hoppa till innehållet
POLARISAI ACADEMY
R02-201 · Navigatör

API:er, SQL, spec före bygge och tester först

Efteråt kan du skriva ett kontrakt på sju rader för en vara, välja status 201, 200, 400 eller 404 ur de raderna, binda ett namn och ett antal med frågetecken, och se pytest rapportera 1 failed innan post_item följer kontraktet.

Nivå
Navigatör
Tid
28 h (uppskattning)
Förkunskap
R02-101
Kurs 2 av 4
Hoppa till

Efter kursen kan du

Eleven kan skriva en testsvit som fångar seedade kontraktsbrott och implementera ett SQL-backat REST-API som klarar 100 % av testerna för kontrakt, samtidighet och SQL-injection.

Sju rader innan funktionen finns

Skriv kontraktet på papper innan funktionen post_item finns. Kontraktet är en spec, en specifikation som testerna läser rad för rad. Rad 1 namnger tabellen items och dess tre kolumner, id, name och qty. Rad 2 säger att POST /items läser ett JSON-objekt med name och qty. Objektet {"name":"oats","qty":2} är 23 tecken: {"name": är 8, "oats" är 6, ,"qty": är 7, siffran 2 är 1 och den avslutande klammern är 1. 8 plus 6 plus 7 plus 1 plus 1 är 23. Rad 3 säger att en giltig första insättning svarar med status 201, kroppen {"id":1,"name":"oats","qty":2} och en Location-header vars värde är /items/1, 8 tecken. Den kroppen är 30 tecken: {"id": är 6, siffran 1 är 1, ,"name": är 8, "oats" är 6, ,"qty": är 7, siffran 2 är 1 och den avslutande klammern är 1. 6 plus 1 plus 8 plus 6 plus 7 plus 1 plus 1 är 30. Rad 4 säger att ett namn som är tomt efter strip svarar med status 400 och kroppen {"error":"empty name"}, 22 tecken, utan Location-header. strip tar bort blanksteg i båda ändar.

Rad 5 säger att ett qty som missar heltalsregeln svarar med status 400 och {"error":"qty"}, 15 tecken, utan Location-header. Rad 6 säger att GET /items/1 efter den första insättningen svarar med status 200 och samma kropp på 30 tecken. Rad 7 säger att GET /items/99, när den raden saknas, svarar med status 404 och {"error":"missing"}, 19 tecken. Heltalsregeln står på samma blad. name är en str. Längden efter strip går från 1 till och med 40. qty gör att type(qty) is int blir sant, och qty ligger från 1 till och med 99. True faller på regeln. type(True) is bool blir sant, type(True) is int blir falskt, och isinstance(True, int) blir sant. Ett namn av 41 a har längden 41 efter strip, så status blir 400 och kroppen blir {"error":"name"}, 16 tecken. En saknad name-nyckel använder samma kropp på 16 tecken. En saknad qty-nyckel använder qty-kroppen på 15 tecken. REST betyder en metod, en sökväg och den kropp de här raderna redan har låst. POST /items, GET /items/1 och GET /items är tre vägar. Efter första insättningen svarar GET /items med status 200 och {"items":[{"id":1,"name":"oats","qty":2}]}. Omslaget {"items":[ plus ]} är 12 tecken runt objektet på 30 tecken, och 30 plus 12 är 42. Du lägger redan till ett ord i en lista på en sida. De sju raderna börjar där ordet lämnar sidan.

Status på en POST och en GET

Gå igenom POST /items med ett namn på 10 tecken, tre blanksteg, sedan oats, sedan tre blanksteg, och med qty 2. strip lämnar oats, längd 4. type(2) is int blir sant, och 2 ligger inom 1 till och med 99. Rad 3 gäller. Status är 201. Kroppen är objektet på 30 tecken med id 1, eftersom tabellen var tom och det första värdet för INTEGER PRIMARY KEY i en tom SQLite-tabell är 1. Location-värdet är /items/1. Gå igenom POST med ett namn av tre blanksteg och qty 2. strip lämnar längd 0. Rad 4 gäller. Status är 400, kroppen är objektet för tomt namn på 22 tecken, location saknas, och tabellen får ingen rad. Gå igenom POST med namnet oats och qty True. type(True) is int blir falskt, så rad 5 gäller. Status är 400, kroppen är qty-objektet på 15 tecken, och tabellen får ingen rad. Gå igenom POST med namnet oats och qty 100. type(100) is int blir sant, och 100 ligger över 99, så rad 5 gäller igen: status 400, samma kropp på 15 tecken, och ingen ny rad. Gå igenom POST med namnet oats och qty 0. 0 ligger under 1, så resultatet blir samma trippel med 400.

Gå igenom GET /items/1 när oats-raden ligger lagrad. Rad 6 gäller. Status är 200 och kroppen är objektet på 30 tecken. Gå igenom GET /items/99 när de lagrade id:na stannar vid 1, eller vid 2 efter en senare insättning av milk. Rad 7 gäller. Status är 404 och kroppen är missing-objektet på 19 tecken. En hanterare som lagrar raden och svarar med status 200 missar ändå rad 3, eftersom testet läser heltalet 201. Den vanliga frasen bredvid 201 är Created, bredvid 400 är Bad Request, bredvid 404 är Not Found och bredvid 200 är OK. Fraserna står på statusraden. Kontrollerna läser heltalen 201, 200, 400 och 404. Räkna ett svar genom att skriva heltalet först, sedan kroppen, sedan Location-värdet eller ordet saknas.

Tabellen och frågetecknet

SQL-texten som skapar tabellen är CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT NOT NULL, qty INTEGER NOT NULL). Den strängen är 85 tecken. Insättningstexten är INSERT INTO items (name, qty) VALUES (?, ?). Den strängen är 43 tecken. De två frågetecknen stannar i texten. En parameteriserad fråga håller texten stilla och skickar värdena bredvid den. I Pythons sqlite3 åker värdena i andra argumentet till execute, tupeln ("oats", 2). I en tom tabell lagrar första execute id 1, namnet oats och qty 2. Ett andra execute med ("milk", 1) lagrar id 2. Båda raderna läses som (1, "oats", 2) och (2, "milk", 1), och COUNT() är 2. Öppna en andra anslutning till samma databasfil efter BEGIN och efter insättningen, och före commit. Den anslutningens COUNT() är 0. Efter commit är COUNT(*) 1 och raden är (1, "oats", 2). Den andra anslutningen ser raden när commit landar. commit låser in ändringen så att den syns utanför transaktionen.

Select-texten är SELECT id, name, qty FROM items WHERE name = ?. Den strängen är 46 tecken. Bind strängen på 11 tecken, ' OR '1'='1, som det enda värdet. Jämförelsen söker ett namn som är lika med de 11 tecknen. oats har längd 4 och milk har längd 4, så select ger en tom lista, och COUNT(*) stannar på 2. Om du stänger citattecken runt samma sträng byggs en enda sats, SELECT id, name, qty FROM items WHERE name = '' OR '1'='1'. OR gör villkoret sant på varje rad i den enda SELECT-satsen, så anropet lämnar båda raderna. Formen med frågetecken behåller de 11 tecknen som data. Tabellen håller fortfarande 2 rader i båda fallen, eftersom den här SELECT-satsen bara läser. D1 kör den här SQLite-SQL:en för de här satserna. Samma CREATE TABLE på 85 tecken och samma INSERT på 43 tecken gäller där. I D1 går värdena till bind i samma ordning från vänster till höger som frågetecknen. Det lagrade namnet är strängen du band, och en select på id 1 ger oats och 2.

Testet som faller först

Att skriva testet före funktionen är testdriven utveckling, på engelska test-driven development. Verktyget för den här omgången är pytest. Skriv test_post_oats_returns_201 i test_items.py medan post_item ännu saknas. Testet anropar post_item med objektet vars name är oats och vars qty är 2, och hävdar tre saker: status är 201, kroppen är objektet på 30 tecken, och location är /items/1. Kommandot python -m pytest test_items.py -q kör det enda testet. Anropet kastar NameError, och pytest rapporterar 1 failed. Lägg in en stump som struntar i sitt argument och alltid returnerar 201, oats-kroppen och /items/1. Lägg till test_blank_name_returns_400. Det testet anropar post_item med ett namn av tre blanksteg och qty 2, och hävdar status 400, kroppen på 22 tecken och location None. Oats-testet klarar sina tre hävdanden. Tomnamnstestet stannar på första hävdandet, eftersom status är 201. pytest rapporterar 1 failed, 1 passed.

Byt ut stumpen mot kontrollerna från kontraktet. Kör strip på name. När längden är 0, returnera 400, kroppen för tomt namn och None. När type(qty) is int blir falskt, eller qty ligger under 1, eller qty ligger över 99, returnera 400, qty-kroppen och None. Annars returnerar du 201, en kropp med id 1, det strippade namnet och qty, plus location /items/1. För oats och 2 lämnar strip oats och qty-kontrollen går igenom, så trippeln med 201 kommer tillbaka. För tre blanksteg är längden 0, så trippeln med 400 kommer tillbaka. pytest rapporterar 2 passed. Ett tredje test skickar namnet oats och qty True. Det går igenom när funktionen använder type(qty) is int. En funktion som använde isinstance(qty, int) skulle släppa igenom True och returnera en 201 vars qty är True, och det tredje testet skulle falla. Klistra in de sju raderna i chattjänsten om du vill ha ett utkast till post_item, och kör sedan samma pytest från mappen som innehåller filen. Utkastet förtjänar sin plats när rapporten säger 2 passed. En senare körning i webbläsaren kan öppna sidan med Playwright och läsa samma status i svaret. Körningen du gör i dag är pytest.

Ett exempel

En vara, från sju rader till två test som går igenom

Skriv de sju raderna. Tabellen är tom. Skicka POST med kroppen på 23 tecken, {"name":"oats","qty":2}. post_item returnerar 201, kroppen på 30 tecken och /items/1. Insättningen använder SQL på 43 tecken och tupeln ("oats", 2). En andra anslutning till samma fil ser COUNT(*) 0 före commit och 1 efter commit, och raden är (1, "oats", 2). GET /items/1 svarar 200 och samma kropp. GET /items/99 svarar 404 och kroppen på 19 tecken. GET /items svarar 200 och listkroppen på 42 tecken.

Skicka POST med ett namn av tre blanksteg och qty 2. Status är 400, kroppen är objektet för tomt namn på 22 tecken, location är None, och COUNT() stannar på 1. Skicka POST med namnet oats och qty True. Status är 400, kroppen är qty-objektet på 15 tecken, och COUNT() stannar på 1. Skicka POST med namnet oats och qty 100. Resultatet blir samma trippel med 400, och COUNT() stannar på 1. Sätt in ("milk", 1) med frågetecknen, så är id 1 och 2. Bind strängen på 11 tecken i select på 46 tecken. Select ger en tom lista. SELECT-satsen med ihopkopplade citattecken lämnar båda raderna. COUNT() stannar på 2.

När post_item saknas och bara oats-testet ligger i filen rapporterar pytest 1 failed. Med stumpen som alltid returnerar oats-svaret 201, och med båda testen i filen, rapporterar pytest 1 failed, 1 passed. Med kontraktets kontroller i post_item rapporterar pytest 2 passed. Tomnamnstestet är det som går från failed till passed när längden efter strip kontrolleras.

Övning

Kolla på papper

Räkna tecknen i {"error":"qty"} och i {"items":[{"id":1,"name":"oats","qty":2}]}. Visa 42 som 30 plus 12. Första POST använder ett namn på 10 tecken, tre blanksteg, sedan oats, sedan tre blanksteg, och qty 2, på en tom tabell. Skriv status, kroppen, Location-värdet och längden efter strip. Nästa POST använder namnet oats och qty 100, med oats-raden redan lagrad. Skriv status, kroppen och COUNT(). Två rader ligger lagrade, oats och milk. Select på 46 tecken binder strängen på 11 tecken, ' OR '1'='1. Skriv hur många rader som kommer tillbaka, och skriv COUNT(). Stumpen returnerar oats-svaret 201 för varje anrop, och filen har oats-testet och tomnamnstestet. Skriv hur många som går igenom och hur många som faller. För qty True och namnet oats, skriv vad type(True) is int ger, vad isinstance(True, int) ger, och vad kontraktets funktion returnerar.

Kroppen för qty-felet är 15 tecken. Listkroppen är 42 tecken, 30 plus 12. Första POST returnerar status 201, kroppen {"id":1,"name":"oats","qty":2} och Location /items/1. Längden efter strip är 4. POST med qty 100 returnerar status 400 och {"error":"qty"}, och COUNT() stannar på 1. Den bundna selecten returnerar 0 rader, och COUNT() stannar på 2. Körningen med stumpen har 1 passed och 1 failed. type(True) is int ger falskt, isinstance(True, int) ger sant, och kontraktets funktion returnerar 400, {"error":"qty"} och None.

Kontrollfrågor

Svara själv först. Öppna sedan frågan för att se svaret.

Hur många tecken har {"name":"oats","qty":2}, och vilken status och vilket Location-värde kräver rad 3 när den kroppen är första insättningen?

23 tecken. Status 201, och Location-värdet är /items/1. Kroppen som kommer tillbaka är objektet på 30 tecken med id 1.

Vilken status, vilken kropp och vilken location kräver kontraktet för ett namn av tre blanksteg och qty 2, och får tabellen en rad?

Status 400, kroppen {"error":"empty name"}, och ingen Location-header. Tabellen får ingen rad, eftersom strip lämnar längd 0 och rad 4 stannar före insättningen.

Två rader ligger lagrade, oats och milk. Select binder strängen på 11 tecken, ' OR '1'='1, till frågetecknet. Hur många rader lämnar select, och vad rapporterar COUNT(*)?

Select lämnar 0 rader, eftersom inget namn är lika med de 11 tecknen. COUNT(*) rapporterar 2. Formen med ihopkopplade citattecken lämnar båda raderna, och tabellen håller fortfarande 2.

Stumpen returnerar 201 och oats-kroppen för varje anrop. pytest kör oats-testet och tomnamnstestet. Hur många går igenom, och varför faller det andra?

1 passed och 1 failed. Oats-testet går igenom. Tomnamnstestet faller på sitt första hävdande, eftersom status är 201 och rad 4 kräver 400.

Ta med dig

Skriv de sju raderna, skicka tillbaka det statusheltal raderna namnger, håll varje värde bredvid SQL-texten, och låt pytest rapportera 1 failed innan post_item följer kontraktet.

Slutuppgift

Lämna in ett REST-API + SQLite/D1-schema och en pytest-svit; runnern verifierar att elevens tester fångar 8 seedade felaktiga implementationer och att elevens API klarar alla 40 fasta kontrakts- och säkerhetstester.

Slutuppgiften rättas av fasta facit och automatiska tester när proven öppnar.

Begrepp i kursen

Kursen har inga egna begrepp i ordlistan ännu. Begrepp från tidigare kurser används här också.

Fler lektioner kommer

Första lektionen är öppen att läsa. Resten av kursens lektioner skrivs, och prov och diplom kommer senare. Till väntelistan