← Cloudflare Durable Objects / durable-objects / tutorials

Vytvořte aplikaci pro rezervaci míst pomocí SQLite v Durable Objects

V tomto tutoriálu se naučíte, jak pomocí Durable Objects vytvořit aplikaci pro rezervaci sedadel. Tato aplikace umožní uživatelům zarezervovat si místo na let. Aplikace bude napsaná v TypeScriptu a použije nové Backend úložiště SQLite v Durable Object pro uložení dat.

Pomocí Durable Objects můžete psát znovupoužitelný kód, který za vás řeší koordinaci a správu stavu pro více klientů. Zápis dat do SQLite v Durable Objects je navíc synchronní a probíhá na lokálním disku, takže se všechny dotazy provádějí s vysokým výkonem. Více o úložišti SQLite v Durable Objects se dozvíte v blogový příspěvek o SQLite v Durable Objects ↗.

Aplikace bude fungovat takto:

Uživatel přejde do aplikace s číslem letu předaným jako parametr dotazu.
Aplikace vytvoří nový Durable Object pro dané číslo letu, pokud ještě neexistuje.
Pokud Durable Object již existuje, aplikace načte informace o sedadlech z databáze SQLite.
Pokud Durable Object neexistuje, aplikace vytvoří nový Durable Object a inicializuje databázi SQLite informacemi o sedadlech. Pro účely tohoto tutoriálu jsou informace o sedadlech v aplikaci napevno zakódované.
Když uživatel vybere sedadlo, aplikace se zeptá na jeho jméno. Poté sedadlo zarezervuje a jméno uloží do databáze SQLite.
Aplikace zároveň rozesílá všechny změny v obsazení míst všem klientům.

Pojďme na to!

Předpoklady

Zaregistrujte si účet Cloudflare ↗.
Nainstalujte Node.js ↗.

Správce verzí Node.js

Použijte správce verzí Node, jako je Volta ↗ nebo nvm ↗ abyste se vyhnuli problémům s oprávněními a měnili verze Node.js. Wrangler, o kterém se dále hovoří v tomto průvodci, vyžaduje verzi Node 16.17.0 nebo novější.

1. Vytvořte nový projekt

Vytvořte nový projekt Worker pro vytvoření a nasazení své aplikace.

Vytvořte Worker s názvem seat-booking spuštěním:
npm create cloudflare@latest -- seat-booking
Při nastavení vyberte následující možnosti:
- Pro S čím byste chtěli začít?, vyberte Hello World example.
- Pro Jakou šablonu chcete použít?, vyberte Worker + Durable Objects.
- Pro Jaký jazyk chcete použít?, vyberte TypeScript.
- Pro Chcete používat git pro správu verzí?, vyberte Yes.
- Pro Chcete nasadit svou aplikaci?, vyberte No (před nasazením provedeme ještě několik změn).
Přejděte do adresáře nového projektu a začněte vyvíjet:

cd seat-booking

2. Vytvořte frontend

Frontend aplikace je jednoduchá HTML stránka, na které si uživatelé mohou vybrat místo a zadat své jméno. Aplikace používá Workers Static Assets pro obsluhu frontendu.

Vytvořte nový adresář s názvem public v kořenovém adresáři projektu.
Vytvořte nový soubor s názvem index.html v public adresář.
Přidejte následující kód HTML do index.html soubor:

public/index.html

<!doctype html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>Flight Seat Booking</title>
		<style>
			body {
				font-family: Arial, sans-serif;
				display: flex;
				justify-content: center;
				align-items: center;
				height: 100vh;
				margin: 0;
				background-color: #f0f0f0;
			}
			.booking-container {
				background-color: white;
				padding: 20px;
				border-radius: 8px;
				box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
			}
			.seat-grid {
				display: grid;
				grid-template-columns: repeat(7, 1fr);
				gap: 10px;
				margin-top: 20px;
			}
			.aisle {
				grid-column: 4;
			}
			.seat {
				width: 40px;
				height: 40px;
				display: flex;
				justify-content: center;
				align-items: center;
				border: 1px solid #ccc;
				cursor: pointer;
			}
			.seat.available {
				background-color: #5dbf61ba;
				color: white;
			}
			.seat.unavailable {
				background-color: #f4433673;
				color: white;
				cursor: not-allowed;
			}
			.airplane {
				display: flex;
				flex-direction: column;
				align-items: center;
				background-color: #f0f0f0;
				padding: 20px;
				border-radius: 20px;
			}
		</style>
	</head>
	<body>
		<div class="booking-container">
			<h2 id="title"></h2>
			<div class="airplane">
				<div id="seatGrid" class="seat-grid"></div>
			</div>
		</div>

    	<script>
    		const seatGrid = document.getElementById("seatGrid");
    		const title = document.getElementById("title");

    		const flightId = window.location.search.split("=")[1];

        const hostname = window.location.hostname;

    		if (flightId === undefined) {
    			title.textContent = "No Flight ID provided";
    			seatGrid.innerHTML = "<p>Add `flightId` to the query string</p>";
    		} else {
    			handleBooking();
    		}

    		function handleBooking() {
    			let ws;
    			if (hostname === 'localhost') {
            const port = window.location.port;
    				ws = new WebSocket(`ws://${hostname}:${port}/ws?flightId=${flightId}`);
    			} else {
    				ws = new WebSocket(`wss://${hostname}/ws?flightId=${flightId}`);
    			}

    			title.textContent = `Book seat for flight ${flightId}`;

    			ws.onopen = () => {
    				console.log("Connected to WebSocket server");
    			};

    			function createSeatGrid(seats) {
    				seatGrid.innerHTML = "";
    				for (let row = 1; row <= 10; row++) {
    					for (let col = 0; col < 6; col++) {
    						if (col === 3) {
    							const aisle = document.createElement("div");
    							aisle.className = "aisle";
    							seatGrid.appendChild(aisle);
    						}

    						const seatNumber = `${row}${String.fromCharCode(65 + col)}`;
    						const seat = seats.find((s) => s.seatNumber === seatNumber);
    						const seatElement = document.createElement("div");
    						seatElement.className = `seat ${seat && seat.occupant ? "unavailable" : "available"}`;
    						seatElement.textContent = seatNumber;
    						seatElement.onclick = () => bookSeat(seatNumber);
    						seatGrid.appendChild(seatElement);
    					}
    				}
    			}

    			async function fetchSeats() {
    				const response = await fetch(`/seats?flightId=${flightId}`);
    				const seats = await response.json();
    				createSeatGrid(seats);
    			}

    			async function bookSeat(seatNumber) {
    				const name = prompt("Please enter your name:");
    				if (!name) {
    					return; // User canceled the prompt
    				}

    				const response = await fetch(`book-seat?flightId=${flightId}`, {
    					method: "POST",
    					headers: { "Content-Type": "application/json" },
    					body: JSON.stringify({ seatNumber, name }),
    				});
    				const result = await response.text();
    				fetchSeats();
    			}

    			ws.onmessage = (event) => {
    				try {
    					const seats = JSON.parse(event.data);
    					createSeatGrid(seats);
    				} catch (error) {
    					console.error("Error parsing WebSocket message:", error);
    				}
    			};

    			ws.onerror = (error) => {
    				console.error("WebSocket error:", error);
    			};

    			ws.onclose = (event) => {
    				console.log("WebSocket connection closed:", event);
    			};

    			fetchSeats();
    		}
    	</script>
    </body>

</html>

Frontend odešle HTTP GET požadavek na /seats endpoint pro získání dostupných sedadel pro let.
Zároveň využívá WebSocket připojení k příjmu aktualizací o dostupných sedadlech.
Když uživatel klikne na sedadlo, aplikace bookSeat() funkce se zavolá, čímž se uživatel vyzve k zadání jména, a poté provede POST požadavek na /book-seat koncový bod.

Aktualizujte vazby v Konfigurační soubor Wrangler pro konfiguraci assets pro obsluhu public adresář.

{
	"assets": {
		"directory": "public"
	}
}

[assets]
directory = "public"

Pokud vývojářský server spustíte následujícím příkazem, frontend poběží na adrese http://localhost:8787. Nebude to ale fungovat, protože backend zatím není implementovaný.

npm run dev

3. Vytvořte tabulku pro každý let

Aplikace už má binding pro třídu Durable Objects nakonfigurovaný v Konfigurační soubor Wrangler. Pokud aktualizujete název třídy Durable Objects v src/index.ts, nezapomeňte aktualizovat i vazbu v Konfigurační soubor Wrangler.

Aktualizujte vazbu tak, aby využívala úložiště SQLite v Durable Objects. V Konfigurační soubor Wrangler, nahraďte new_classes=["Flight"] hodnotou new_sqlite_classes=["Flight"], name = "FLIGHT" hodnotou name = "FLIGHT", a class_name = "MyDurableObject" hodnotou class_name = "Flight". váš Konfigurační soubor Wrangler by měl vypadat podobně jako toto:

{
	"durable_objects": {
		"bindings": [
			{
				"name": "FLIGHT",
				"class_name": "Flight"
			}
		]
	},
	// Durable Object migrations.
	// Docs: https://developers.cloudflare.com/workers/wrangler/configuration/#migrations
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": [
				"Flight"
			]
		}
	]
}

[[durable_objects.bindings]]
name = "FLIGHT"
class_name = "Flight"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "Flight" ]

Vaše aplikace nyní může využívat úložiště SQLite v Durable Objects.

Přidejte initializeSeats() funkci do Flight třída. Tato funkce se zavolá při inicializaci Durable Object. Zkontroluje, zda tabulka existuje, a pokud ne, vytvoří ji. Zároveň do tabulky vloží informace o sedadlech.

V tomto tutoriálu funkce vytváří pro všechny lety stejný plán sezení. V produkčním prostředí byste ale tuto funkci upravili tak, aby sedadla vkládala podle typu letu.

Nahraďte Flight třídu následujícím kódem:

src/index.ts

import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
	sql = this.ctx.storage.sql;

	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		this.initializeSeats();
	}

	private initializeSeats() {
		const cursor = this.sql.exec(`PRAGMA table_list`);

		// Check if a table exists.
		if ([...cursor].find((t) => t.name === "seats")) {
			console.log("Table already exists");
			return;
		}

		this.sql.exec(`
				  CREATE TABLE IF NOT EXISTS seats (
					seatId TEXT PRIMARY KEY,
					occupant TEXT
				  )
				`);

		// For this demo, we populate the table with 60 seats.
		// Since SQLite in DOs is fast, we can do a query per INSERT instead of batching them in a transaction.
		for (let row = 1; row <= 10; row++) {
			for (let col = 0; col < 6; col++) {
				const seatNumber = `${row}${String.fromCharCode(65 + col)}`;
				this.sql.exec(`INSERT INTO seats VALUES (?, null)`, seatNumber);
			}
		}
	}
}

Přidejte fetch handler do Flight třída. Tento handler vrátí textovou odpověď. V Krok 5 Aktualizujete fetch handler pro zpracování připojení WebSocket.

src/index.ts

import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
  ...
  async fetch(request: Request): Promise<Response> {
    return new Response("Hello from Durable Object!", { status: 200 });
  }
}

Dále upravte fetch handler Workeru tak, aby pro každý let vytvořil jedinečný Durable Object.

src/index.ts

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Get flight id from the query parameter
		const url = new URL(request.url);
		const flightId = url.searchParams.get("flightId");

		if (!flightId) {
			return new Response(
				"Flight ID not found. Provide flightId in the query parameter",
				{ status: 404 },
			);
		}

		const stub = env.FLIGHT.getByName(flightId);
		return stub.fetch(request);
	},
} satisfies ExportedHandler<Env>;

Na základě ID letu z parametru dotazu se vytvoří jedinečný Durable Object. Pokud ještě neexistuje tabulka, tento Durable Object se s ní inicializuje.

4. Přidejte metody do Durable Object

Přidejte getSeats() funkci do Flight třída. Tato funkce vrací všechna sedadla v tabulce.

src/index.ts

import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
    ...

	private initializeSeats() {
		...
	}

	// Get all seats.
	getSeats() {
		let results = [];

		// Query returns a cursor.
		let cursor = this.sql.exec(`SELECT seatId, occupant FROM seats`);

		// Cursors are iterable.
		for (let row of cursor) {
			// Each row is an object with a property for each column.
			results.push({ seatNumber: row.seatId, occupant: row.occupant });
		}

		return results;
	}
}

Přidejte assignSeat() funkci do Flight třída. Tato funkce přiřadí sedadlo cestujícímu. Jako parametry přijímá číslo sedadla a jméno cestujícího.

src/index.ts

import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
	...

	private initializeSeats() {
		...
	}

	// Get all seats.
	getSeats() {
		...
	}

	// Assign a seat to a passenger.
	assignSeat(seatId: string, occupant: string) {
		// Check that seat isn't occupied.
		let cursor = this.sql.exec(
			`SELECT occupant FROM seats WHERE seatId = ?`,
			seatId,
		);
		let result = cursor.toArray()[0]; // Get the first result from the cursor.

		if (!result) {
			return {message: 'Seat not available',  status: 400 };
		}
		if (result.occupant !== null) {
			return {message: 'Seat not available',  status: 400 };
		}

		// If the occupant is already in a different seat, remove them.
		this.sql.exec(
			`UPDATE seats SET occupant = null WHERE occupant = ?`,
			occupant,
		);

		// Assign the seat. Note: We don't have to worry that a concurrent request may
		// have grabbed the seat between the two queries, because the code is synchronous
		// (no `await`s) and the database is private to this Durable Object. Nothing else
		// could have changed since we checked that the seat was available earlier!
		this.sql.exec(
			`UPDATE seats SET occupant = ? WHERE seatId = ?`,
			occupant,
			seatId,
		);

		// Broadcast the updated seats.
		this.broadcastSeats();
		return {message: `Seat ${seatId} booked successfully`, status: 200 };
	}
}

Výše uvedená funkce používá broadcastSeats() funkci, která rozešle aktualizovaná místa všem připojeným klientům. V další části přidáme broadcastSeats() .

5. Zpracujte WebSocket připojení

Všichni klienti se k Durable Object připojí pomocí WebSocketů. Durable Object následně rozešle aktualizovaná místa všem připojeným klientům, což jim umožní aktualizovat UI v reálném čase.

Přidejte handleWebSocket() funkci do Flight třída. Tato funkce obsluhuje WebSocket připojení.

src/index.ts

import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
	...

	private initializeSeats() {
		...
	}

	// Get all seats.
	getSeats() {
		...
	}

	// Assign a seat to a passenger.
	assignSeat(seatId: string, occupant: string) {
		...
	}

  private handleWebSocket(request: Request) {
		console.log('WebSocket connection requested');
		const [client, server] = Object.values(new WebSocketPair());

		this.ctx.acceptWebSocket(server);
		console.log('WebSocket connection established');

		return new Response(null, { status: 101, webSocket: client });
	}
}

Přidejte broadcastSeats() funkci do Flight třída. Tato funkce rozešle aktualizovaná sedadla všem připojeným klientům.

src/index.ts

import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
	...

	private initializeSeats() {
		...
	}

	// Get all seats.
	getSeats() {
		...
	}

	// Assign a seat to a passenger.
	assignSeat(seatId: string, occupant: string) {
		...
	}

  private handleWebSocket(request: Request) {
		...
	}

  private broadcastSeats() {
		this.ctx.getWebSockets().forEach((ws) => ws.send(this.getSeats()));
	}
}

Dále aktualizujte fetch handler v Flight třída. Tento handler zpracovává všechny příchozí požadavky od Worker a WebSocket připojení obsluhuje pomocí handleWebSocket() metoda.

src/index.ts

import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
	...

	private initializeSeats() {
		...
	}

	// Get all seats.
	getSeats() {
		...
	}

	// Assign a seat to a passenger.
	assignSeat(seatId: string, occupant: string) {
		...
	}

  private handleWebSocket(request: Request) {
		...
	}

  private broadcastSeats() {
		...
	}

  async fetch(request: Request) {
		return this.handleWebSocket(request);
	}
}

Nakonec aktualizujte fetch handleru Workeru.

src/index.ts

export default {
	...

	async fetch(request, env, ctx): Promise<Response> {
		// Get flight id from the query parameter
		...

		if (request.method === "GET" && url.pathname === "/seats") {
			return new Response(JSON.stringify(await stub.getSeats()), {
				headers: { 'Content-Type': 'application/json' },
			});
		} else if (request.method === "POST" && url.pathname === "/book-seat") {
			const { seatNumber, name } = (await request.json()) as {
				seatNumber: string;
				name: string;
			};
			const result = await stub.assignSeat(seatNumber, name);
			return new Response(JSON.stringify(result));
		} else if (request.headers.get("Upgrade") === "websocket") {
			return stub.fetch(request);
		}

		return new Response("Not found", { status: 404 });
	},
} satisfies ExportedHandler<Env>;

fetch handler ve Workeru nyní volá příslušnou funkci Durable Object pro zpracování příchozího požadavku. Pokud je požadavek GET požadavek na /seats, Worker vrátí sedadla z Durable Objectu. Pokud je požadavek POST požadavek na /book-seat, Worker zavolá bookSeat metodu Durable Object a přiřadí tak sedadlo cestujícímu. Pokud je požadavek WebSocket připojení, Durable Object toto WebSocket připojení zpracuje.

6. Otestujte aplikaci

Aplikaci můžete otestovat lokálně spuštěním následujícího příkazu:

npm run dev

Tím se spustí lokální vývojový server, na kterém aplikace běží. Aplikace je dostupná na adrese http://localhost:8787.

Přejděte do aplikace na http://localhost:8787 v prohlížeči. Protože není zadáno ID letu, aplikace zobrazí chybovou zprávu.

Aktualizujte URL o ID letu jako http://localhost:8787?flightId=1234. Aplikace zobrazuje sedadla pro let s ID 1234.

7. Nasaďte aplikaci

Chcete-li aplikaci nasadit, spusťte následující příkaz:

npm run deploy

 ⛅️ wrangler 3.78.8
-------------------

🌀 Building list of assets...
🌀 Starting asset upload...
🌀 Found 1 new or modified file to upload. Proceeding with upload...
+ /index.html
Uploaded 1 of 1 assets
✨ Success! Uploaded 1 file (1.93 sec)

Total Upload: 3.45 KiB / gzip: 1.39 KiB
Your worker has access to the following bindings:
- Durable Objects:
  - FLIGHT: Flight
Uploaded seat-book (12.12 sec)
Deployed seat-book triggers (5.54 sec)
  [DEPLOYED_APP_LINK]
Current Version ID: [BINDING_ID]

Přejděte na [DEPLOYED_APP_LINK] a zobrazte aplikaci. Nezapomeňte znovu předat ID letu jako parametr řetězce dotazu.

Souhrn

V tomto tutoriálu jste:

použil úložný back-end SQLite v Durable Objects k uložení sedadel letu.
vytvořili třídu Durable Object pro správu rezervace míst.
nasadili aplikaci na Cloudflare Workers!

Kompletní kód k tomuto tutoriálu najdete na GitHub ↗.