Aplikacja Spring Boot z Cloud Spanner

1. Przegląd

Cloud Spanner to wysoce dostępny, skalowalny w poziomie i wieloregionowy system RDBMS. W tym laboratorium użyjemy najmniejszej instancji Cloud Spanner, ale nie zapomnij jej wyłączyć po zakończeniu pracy.

Czego się nauczysz

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

Czego potrzebujesz

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

Jak zamierzasz korzystać z tego samouczka?

Tylko przeczytaj Przeczytaj i wykonaj ćwiczenia

Jak oceniasz korzystanie z usług Google Cloud Platform?

Początkujący Średnio zaawansowany Zaawansowany

2. Konfiguracja i wymagania

Samodzielne konfigurowanie środowiska

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

Uwaga: żeby łatwo otwierać konsolę Cloud, wystarczy zapamiętać jej adres URL: console.cloud.google.com.

Zapamiętaj identyfikator projektu, czyli unikalną nazwę we wszystkich projektach Google Cloud (podana powyżej nazwa jest już zajęta i nie będzie działać w Twoim przypadku). W dalszej części tego laboratorium będzie on nazywany PROJECT_ID.

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

2. Następnie musisz włączyć rozliczenia w konsoli Cloud, aby korzystać z zasobów Google Cloud.

Ukończenie tego laboratorium nie powinno wiązać się z dużymi kosztami, a nawet z żadnymi. Wykonaj instrukcje z sekcji „Czyszczenie”, w której znajdziesz informacje o tym, jak wyłączyć zasoby, aby uniknąć naliczenia opłat po zakończeniu tego samouczka. Nowi użytkownicy Google Cloud mogą skorzystać z programu bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.

Aktywowanie Cloud Shell

1. W konsoli Cloud kliknij Aktywuj Cloud Shell .

Jeśli uruchamiasz Cloud Shell po raz pierwszy, zobaczysz ekran pośredni (część strony widoczna po przewinięciu) z opisem tego środowiska. W takim przypadku kliknij Dalej, a ten ekran nie będzie się już wyświetlać. Ten wyświetlany jednorazowo ekran wygląda tak:

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

Ta maszyna wirtualna zawiera wszystkie potrzebne narzędzia dla programistów. Zawiera również stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie zwiększa wydajność sieci i usprawnia proces uwierzytelniania. Większość zadań w tym module, a być może wszystkie, możesz wykonać w przeglądarce lub na Chromebooku.

Po połączeniu z Cloud Shell zobaczysz, że uwierzytelnianie zostało już przeprowadzone, a projekt jest już ustawiony na Twój identyfikator projektu.

2. Aby potwierdzić, że uwierzytelnianie zostało przeprowadzone, uruchom w Cloud Shell to polecenie:

gcloud auth list

Wynik 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 i ujednolicone narzędzie wiersza poleceń w Google Cloud. Jest już zainstalowane w Cloud Shell. Zauważysz, że obsługuje on uzupełnianie za pomocą klawisza Tab. Więcej informacji znajdziesz w omówieniu narzędzia wiersza poleceń gcloud.

gcloud config list project

Wynik polecenia

[core]
project = <PROJECT_ID>

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

gcloud config set project <PROJECT_ID>

Wynik polecenia

Updated property [core/project].

3. Inicjowanie Cloud Spanner

Włącz interfejs 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, aby opisać 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 powłoki 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, a także pom.xml Maven, otoki Maven i punktu wejścia aplikacji.

W pliku pom.xml dodaj starter 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 JAVA_HOME jest ustawiony na odpowiednią wersję:

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

Ponownie skompiluj aplikację, aby sprawdzić, czy konfiguracja Maven jest prawidłowa:

./mvnw package

5. Tworzenie encji

Dzięki obsłudze Spring Data Spanner w Spring Cloud GCP możesz łatwo utworzyć obiekt Java i idiomatyczne mapowanie ORM do tabeli Spanner za pomocą Spring Data.

Najpierw utwórz klasę Order Item.

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żywać złożonego klucza podstawowego. W tym przykładzie klucz złożony to order_id i order_item_id.

Następnie utwórz klasę Order:

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 klasę OrderRepository z tą treś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> {
}

Interfejs rozszerza SpannerRepository<Order, String>, gdzie Order to klasa domeny, a String to typ klucza podstawowego. Spring Data automatycznie zapewni dostęp CRUD za pomocą tego interfejsu i nie musisz tworzyć żadnego dodatkowego kodu.

7. Tworzenie kontrolera REST do wykonywania podstawowych operacji

Otwórz główną klasę aplikacji DemoApplication 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

Utwórz i uruchom aplikację.

./mvnw spring-boot:run

Powinien się uruchomić prawidłowo i nasłuchiwać na porcie 8080.

Możesz opublikować rekord zamówienia 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

Powinien odpowiedzieć, podając UUID zamówienia.

Następnie możesz pobrać zamówienie za pomocą funkcji UUID:

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

Aby zobaczyć, jak dane są przechowywane w Cloud Spanner, otwórz Cloud Console i kliknij Spanner → Instancja Spanner → baza danych zamówień → tabela zamówień → Dane.

9. Czyszczenie danych

Aby wyczyścić dane, usuń instancję Spannera, aby nie generowała już opłat.

gcloud spanner instances delete spanner-instance -q

10. Gratulacje!

W tym laboratorium utworzyliśmy interaktywną aplikację CLI, która może przechowywać i pobierać dane z Cloud Spanner.

Więcej informacji

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

Licencja

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