Aplikacja Spring Boot z Cloud Spanner

1. Omówienie

Cloud Spanner to bardzo dostępna, skalowalna w poziomie i wiele regionów RDBMS. W tym module do programowania zostanie wykorzystana najmniejsza instancja Cloud Spanner, ale pamiętaj, aby ją wyłączyć, gdy skończysz.

Czego się nauczysz

• Jak używać Cloud Spanner do zapisywania i pobierania danych za pomocą Spring Boot

Czego potrzebujesz

• Projekt Google Cloud Platform
• przeglądarkę, np. Chrome lub Firefox;

Jak wykorzystasz ten samouczek?

Tylko do przeczytania Przeczytaj go i wykonaj ćwiczenia

Jak oceniasz swoje wrażenia z korzystania z usług Google Cloud Platform?

Początkujący Poziom średnio zaawansowany Biegły

2. Konfiguracja i wymagania

Samodzielne konfigurowanie środowiska

1. Zaloguj się w konsoli Google Cloud i utwórz nowy projekt lub wykorzystaj już istniejący. Jeśli nie masz jeszcze konta Gmail lub G Suite, musisz je utworzyć.

Uwaga: możesz łatwo uzyskać dostęp do konsoli Cloud, zapamiętując jej adres URL, czyli Console.cloud.google.com.

Zapamiętaj identyfikator projektu, unikalną nazwę we wszystkich projektach Google Cloud (powyższa nazwa jest już zajęta i nie będzie Ci odpowiadać). W dalszej części tego ćwiczenia w programie będzie ona określana jako PROJECT_ID.

Uwaga: jeśli używasz konta Gmail, jako domyślną lokalizację możesz pozostawić ustawienie Brak organizacji. Jeśli używasz konta G Suite, wybierz lokalizację odpowiednią dla Twojej organizacji.

2. Następnie musisz włączyć płatności w Cloud Console, aby korzystać z zasobów Google Cloud.

Ukończenie tego ćwiczenia z programowania nie powinno kosztować zbyt wiele. Postępuj zgodnie z instrukcjami podanymi w sekcji „Czyszczenie” W tym samouczku znajdziesz wskazówki, jak wyłączyć zasoby, aby uniknąć naliczania opłat. Nowi użytkownicy Google Cloud mogą skorzystać z programu bezpłatnego okresu próbnego o wartości 300 USD.

Aktywowanie Cloud Shell

1. W konsoli Cloud kliknij Aktywuj Cloud Shell .

Jeśli dopiero zaczynasz korzystać z Cloud Shell, wyświetli się ekran pośredni (w części strony widocznej po przewinięciu) z opisem tej funkcji. W takim przypadku kliknij Dalej (nie zobaczysz go więcej). Tak wygląda ten jednorazowy ekran:

Uzyskanie dostępu do Cloud Shell i połączenie się z nim powinno zająć tylko kilka chwil.

Ta maszyna wirtualna ma wszystkie potrzebne narzędzia dla programistów. Zawiera stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie zwiększa wydajność sieci i uwierzytelnianie. Większość zadań w ramach tego ćwiczenia z programowania można wykonać w przeglądarce lub na Chromebooku.

Po nawiązaniu połączenia z Cloud Shell powinno pojawić się informacja, że użytkownik jest już uwierzytelniony i że projekt jest już ustawiony na identyfikator Twojego projektu.

2. Uruchom to polecenie w Cloud Shell, aby potwierdzić, że jesteś uwierzytelniony:

gcloud auth list

Dane wyjściowe polecenia

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Uwaga: narzędzie wiersza poleceń gcloud to zaawansowane, ujednolicone narzędzie wiersza poleceń w Google Cloud. Jest ona wstępnie zainstalowana w Cloud Shell. Zauważysz, że obsługuje ona funkcję autouzupełniania. Więcej informacji znajdziesz w artykule Omówienie narzędzia wiersza poleceń gcloud.

gcloud config list project

Dane wyjściowe polecenia

[core]
project = <PROJECT_ID>

Jeśli tak nie jest, możesz go ustawić za pomocą tego polecenia:

gcloud config set project <PROJECT_ID>

Dane wyjściowe polecenia

Updated property [core/project].

3. Inicjowanie Cloud Spanner

Włącz Cloud Spanner API za pomocą gcloud CLI:

gcloud services enable spanner.googleapis.com

Utwórz instancję Cloud Spanner:

gcloud spanner instances create spanner-instance \
 --config=regional-us-central1 \
 --nodes=1 --description="A Spanner Instance"

Utwórz bazę danych w instancji:

gcloud spanner databases create orders \
  --instance=spanner-instance

Utwórz plik schema.ddl opisujący schemat danych:

cat << EOF > schema.ddl
CREATE TABLE orders (
  order_id STRING(36) NOT NULL,
  description STRING(255),
  creation_timestamp TIMESTAMP,
) PRIMARY KEY (order_id);

CREATE TABLE order_items (
  order_id STRING(36) NOT NULL,
  order_item_id STRING(36) NOT NULL,
  description STRING(255),
  quantity INT64,
) PRIMARY KEY (order_id, order_item_id),
  INTERLEAVE IN PARENT orders ON DELETE CASCADE;
EOF

Zastosuj schemat do bazy danych Cloud Spanner:

gcloud spanner databases ddl update orders \
  --instance=spanner-instance \
  --ddl="$(<schema.ddl)"

4. Wczytywanie nowej aplikacji Spring Boot w Javie

W środowisku Cloud Shell użyj tego polecenia, aby zainicjować i uruchomić nową aplikację Spring Boot:

$ curl https://start.spring.io/starter.tgz \
  -d packaging=jar \
  -d dependencies=cloud-gcp,web,lombok \
  -d baseDir=spanner-example \
  -d type=maven-project \
  -d bootVersion=3.2.6 | tar -xzvf -

$ cd spanner-example

Spowoduje to utworzenie nowego katalogu spanner-example/ z nowym projektem Maven, wraz z klasą pom.xml Maven, kodem Maven oraz punktem wejścia aplikacji.

W pliku pom.xml dodaj polecenie inicjujące Spring Data Cloud Spanner.

spanner-example/pom.xml

<project>
  ...
  <dependencies>
        ...
        <!-- Add Spring Cloud GCP Spanner Starter -->
        <dependency>
                <groupId>com.google.cloud</groupId>
                <artifactId>spring-cloud-gcp-starter-data-spanner</artifactId>
        </dependency>

        ...

  </dependencies>

  ...
</project>

W pliku application.properties skonfiguruj informacje o połączeniu z bazą danych Spanner:

spanner-example/src/main/resources/application.properties

spring.cloud.gcp.spanner.instance-id=spanner-instance
spring.cloud.gcp.spanner.database=orders

Sprawdź, czy zasada JAVA_HOME jest ustawiona na odpowiednią wersję:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64/

Ponownie skompiluj aplikację, aby upewnić się, że konfiguracja Maven jest prawidłowa:

./mvnw package

5. Tworzenie encji

Dzięki obsłudze Spring Data Spanner z usługi Spring Cloud GCP możesz łatwo utworzyć obiekt Java i idiomatyczne mapowanie ORM na tabelę Spannera za pomocą danych Spring.

Najpierw utwórz klasę Element zamówienia.

spanner-example/src/main/java/com/example/demo/OrderItem.java

package com.example.demo;

import com.google.cloud.spring.data.spanner.core.mapping.Column;
import com.google.cloud.spring.data.spanner.core.mapping.PrimaryKey;
import com.google.cloud.spring.data.spanner.core.mapping.Table;

@Table(name="order_items")
@Data
class OrderItem {
  @PrimaryKey(keyOrder = 1)
  @Column(name="order_id")
  private String orderId;

  @PrimaryKey(keyOrder = 2)
  @Column(name="order_item_id")
  private String orderItemId;

  private String description;
  private Long quantity;
}

W przypadku relacji nadrzędny/podrzędny w usłudze Spanner należy użyć złożonego klucza podstawowego. W tym przykładzie kluczem złożonym są order_id i order_item_id.

Następnie utwórz klasę zamówienia:

spanner-example/src/main/java/com/example/demo/Order.java

package com.example.demo;

import java.time.LocalDateTime;
import java.util.List;
import lombok.Data;
import com.google.cloud.spring.data.spanner.core.mapping.Column;
import com.google.cloud.spring.data.spanner.core.mapping.Interleaved;
import com.google.cloud.spring.data.spanner.core.mapping.PrimaryKey;
import com.google.cloud.spring.data.spanner.core.mapping.Table;

@Table(name="orders")
@Data
public class Order {
  @PrimaryKey
  @Column(name="order_id")
  private String id;

  private String description;

  @Column(name="creation_timestamp")
  private LocalDateTime timestamp;

  @Interleaved
  private List<OrderItem> items;
}

Ta klasa używa adnotacji @Interleaved do utworzenia relacji „jeden do wielu” z elementami zamówienia.

6. Tworzenie interfejsu OrderRepository

Utwórz zajęcia OrderRepository z tą zawartością:

spanner-example/src/main/java/com/example/demo/OrderRepository.java

package com.example.demo;

import com.google.cloud.spring.data.spanner.repository.SpannerRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface OrderRepository extends SpannerRepository<Order, String> {
}

Rozszerza interfejs SpannerRepository<Order, String>, gdzie Order jest klasą domeny, a String to typ klucza podstawowego. Spring Data automatycznie zapewni dostęp CRUD za pomocą tego interfejsu. Nie musisz tworzyć żadnego dodatkowego kodu.

7. Tworzenie kontrolera REST do podstawowych operacji

Otwórz klasę DemoApplication aplikacji głównej i zmodyfikuj ją tak, aby wyglądała tak:

spanner-example/src/main/java/com/example/demo/DemoApplication.java

package com.example.demo;

import java.time.LocalDateTime;
import java.util.UUID;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.server.ResponseStatusException;

@SpringBootApplication
public class DemoApplication {
        public static void main(String[] args) {
                SpringApplication.run(DemoApplication.class, args);
        }
}

@RestController
class OrderController {
  private final OrderRepository orderRepository;

        OrderController(OrderRepository orderRepository) {
                this.orderRepository = orderRepository;
        }

        @GetMapping("/api/orders/{id}")
        public Order getOrder(@PathVariable String id) {
          return orderRepository.findById(id)
                                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, id + " not found"));
        }

        @PostMapping("/api/orders")
        public String createOrder(@RequestBody Order order) {
                // Spanner currently does not auto generate IDs
                // Generate UUID on new orders
                order.setId(UUID.randomUUID().toString());
                order.setTimestamp(LocalDateTime.now());

                order.getItems().forEach(item -> {
                        // Assign parent ID, and also generate child ID
                        item.setOrderId(order.getId());
                        item.setOrderItemId(UUID.randomUUID().toString());
                });

          Order saved = orderRepository.save(order);
          return saved.getId();
        }
}

8. Uruchamianie aplikacji

Ponownie skompiluj i uruchom aplikację.

./mvnw spring-boot:run

Proces powinien rozpocząć się poprawnie i nasłuchiwać na porcie 8080.

Rekord zamówienia możesz opublikować w punkcie końcowym:

curl -H"Content-Type: application/json" -d'{"description": "My orders", "items": [{"description": "Android Phone", "quantity": "1"}]}' \
  http://localhost:8080/api/orders

W odpowiedzi powinien wyświetlić się identyfikator UUID zamówienia.

Zamówienie możesz wtedy pobrać za pomocą identyfikatora UUID:

curl http://localhost:8080/api/orders/REPLACE_WITH_ORDER_UUID

Aby sprawdzić, jak dane są przechowywane w Cloud Spanner, otwórz konsolę Cloud i przejdź do Spanner → Instancja Spannera → baza danych zamówień → tabela zamówień → Dane.

9. Czyszczenie danych

Aby wyczyścić dane, usuń instancję Spannera, aby nie była już obciążana opłatami.

gcloud spanner instances delete spanner-instance -q

10. Gratulacje!

Dzięki tym ćwiczeniom w Codelabs stworzysz interaktywną aplikację interfejsu wiersza poleceń, która może przechowywać i pobierać dane z Cloud Spanner.

Więcej informacji

• Cloud Spanner: https://cloud.google.com/spanner/
• Projekt Spring on GCP: https://googlecloudplatform.github.io/spring-cloud-gcp/reference/html/
• Repozytorium Spring on GCP na GitHubie: https://github.com/spring-cloud/spring-cloud-gcp
• Java w Google Cloud Platform: https://cloud.google.com/java/

Licencja

To zadanie jest licencjonowane na podstawie ogólnej licencji Creative Commons Attribution 2.0.