在適用於 PostgreSQL 的 Azure 資料庫中使用 Spring Data R2DBC

本文說明如何將 Spring Data R2DBC 與適用於 PostgreSQL 的 Azure 資料庫結合，建立一個可擴展、完全反應式的 Spring Boot 應用程式，以儲存與檢索資訊。範例使用 GitHub 上 r2dbc-postgreSQL 倉庫中 PostgreSQL 的 R2DBC 實作。

R2DBC 會將反應式 API 帶入傳統關係資料庫。您可以將它與 Spring WebFlux 搭配使用，以建立使用非封鎖 API 的完整回應式 Spring Boot 應用程式。其可提供比傳統「每個連線一個線程」方法更好的延展性。

必要條件

Azure 訂用帳戶 - 建立免費帳戶。
Java Development Kit （JDK）版本 8 或更高版本。
Apache Maven。
Azure CLI。

PostgreSQL 命令行用戶端。
cURL 或類似的 HTTP 公用程式來測試功能。

請參閱範例應用程式

在本文中，你將編寫一個範例應用程式。如果您想加快速度，這個應用程式的程式碼已經寫好，並可於 https://github.com/Azure-Samples/quickstart-spring-data-r2dbc-postgresql 取得。

準備工作環境

首先，執行下列命令來設定一些環境變數：

export AZ_RESOURCE_GROUP=database-workshop
export AZ_DATABASE_SERVER_NAME=<YOUR_DATABASE_SERVER_NAME>
export AZ_DATABASE_NAME=<YOUR_DATABASE_NAME>
export AZ_LOCATION=<YOUR_AZURE_REGION>
export AZ_POSTGRESQL_ADMIN_USERNAME=spring
export AZ_POSTGRESQL_ADMIN_PASSWORD=<YOUR_POSTGRESQL_ADMIN_PASSWORD>
export AZ_POSTGRESQL_NON_ADMIN_USERNAME=nonspring
export AZ_POSTGRESQL_NON_ADMIN_PASSWORD=<YOUR_POSTGRESQL_NON_ADMIN_PASSWORD>
export AZ_LOCAL_IP_ADDRESS=<YOUR_LOCAL_IP_ADDRESS>

將預留位置取代為下列值，本文通篇都將使用這些值：

<YOUR_DATABASE_SERVER_NAME>：您的 PostgreSQL 伺服器名稱，這在整個 Azure 中應該是唯一的。
<YOUR_DATABASE_NAME>:P ostgreSQL 伺服器的資料庫名稱，在 Azure 中應該是唯一的。
<YOUR_AZURE_REGION>：您要使用的 Azure 區域。你可以預設使用 eastus ，但設定一個離你住處更近的區域。請使用 az account list-locations 查看可用區域的完整清單。
<YOUR_POSTGRESQL_ADMIN_PASSWORD> 和 <YOUR_POSTGRESQL_NON_ADMIN_PASSWORD>:P ostgreSQL 資料庫伺服器的密碼，其至少應有八個字元。這些字元應屬於下列三種類別：英文大寫字母、英文小寫字母、數字 (0-9) 及非英數字元 (!、$、#、% 等等)。
<YOUR_LOCAL_IP_ADDRESS>：本機電腦的 IP 位址，您將在此電腦執行 Spring Boot 應用程式。您可以開啟 whatismyip.akamai.com，以便找出此資訊。

附註

Microsoft 建議您使用最安全的可用驗證流程。此程式中所述的驗證流程，例如資料庫、快取、傳訊或 AI 服務，在應用程式中需要高度的信任，而且不會在其他流程中帶來風險。僅在更安全的選項（例如可用於無密碼或無金鑰連線的受控識別）不可行時，才使用此流程。針對本機計算機作業，偏好使用無密碼或無密鑰連線的使用者身分識別。

接下來，使用下列命令建立資源群組：

az group create \
    --name $AZ_RESOURCE_GROUP \
    --location $AZ_LOCATION \
    --output tsv

建立適用於 PostgreSQL 的 Azure 資料庫實例並設定系統管理員使用者

你首先建立的是一台由管理員管理的 PostgreSQL 伺服器。

附註

欲了解更多關於建立 PostgreSQL 伺服器的資訊，請參閱「使用 Azure 入口網站建立適用於 PostgreSQL 的 Azure 資料庫伺服器」。

az postgres flexible-server create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME \
    --location $AZ_LOCATION \
    --admin-user $AZ_POSTGRESQL_ADMIN_USERNAME \
    --admin-password $AZ_POSTGRESQL_ADMIN_PASSWORD \
    --yes \
    --output tsv

設定 PostgreSQL 資料庫

您先前建立的 PostgreSQL 伺服器是空的。使用下列命令來建立新的資料庫。

az postgres flexible-server db create \
    --resource-group $AZ_RESOURCE_GROUP \
    --database-name $AZ_DATABASE_NAME \
    --server-name $AZ_DATABASE_SERVER_NAME \
    --output tsv

設定 PostgreSQL 伺服器的防火牆規則

適用於 PostgreSQL 的 Azure 資料庫執行個體依預設會受到保護。其防火牆不允許任何連入連線。要使用你的資料庫，你需要加入一個防火牆規則，允許你的本地 IP 位址存取資料庫伺服器。

由於您已在本文開頭設定本機 IP 位址，您可以執行下列命令來開啟伺服器的防火牆：

az postgres flexible-server firewall-rule create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME \
    --rule-name $AZ_DATABASE_SERVER_NAME-database-allow-local-ip \
    --start-ip-address $AZ_LOCAL_IP_ADDRESS \
    --end-ip-address $AZ_LOCAL_IP_ADDRESS \
    --output tsv

如果您要從 Windows 電腦上的 Windows 子系統 Linux 版（WSL）連線到 PostgreSQL 伺服器，您必須將 WSL 主機標識元新增至防火牆。

透過 WSL 執行以下指令，取得你主機的 IP 位址：

cat /etc/resolv.conf

在術語 nameserver後複製 IP 位址，然後使用以下指令設定 WSL IP 位址的環境變數：

export AZ_WSL_IP_ADDRESS=<the-copied-IP-address>

然後，使用下列命令，讓伺服器的防火牆對以 WSL 為基礎的應用程式開放：

az postgres flexible-server firewall-rule create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME \
    --rule-name $AZ_DATABASE_SERVER_NAME-database-allow-local-ip \
    --start-ip-address $AZ_WSL_IP_ADDRESS \
    --end-ip-address $AZ_WSL_IP_ADDRESS \
    --output tsv

建立 PostgreSQL 非系統管理員使用者並授與權限

接下來，建立非系統管理員使用者，並授與資料庫的所有權限。

附註

欲了解更多關於建立 PostgreSQL 使用者的資訊，請參閱「在適用於 PostgreSQL 的 Azure 資料庫建立使用者」。

建立一個名為 create_user.sql 的 SQL 腳本，用來建立非管理員使用者。新增下列內容，並將其儲存在本地：

附註

cat << EOF > create_user.sql
CREATE ROLE "$AZ_POSTGRESQL_NON_ADMIN_USERNAME" WITH LOGIN PASSWORD '$AZ_POSTGRESQL_NON_ADMIN_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE $AZ_DATABASE_NAME TO "$AZ_POSTGRESQL_NON_ADMIN_USERNAME";
EOF

接著，使用以下指令執行 SQL 腳本並建立 Microsoft Entra 非管理員使用者：

psql "host=$AZ_DATABASE_SERVER_NAME.postgres.database.azure.com user=$AZ_POSTGRESQL_ADMIN_USERNAME dbname=$AZ_DATABASE_NAME port=5432 password=$AZ_POSTGRESQL_ADMIN_PASSWORD sslmode=require" < create_user.sql

現在，請使用以下指令移除暫存的 SQL 腳本檔案：

rm create_user.sql

建立回應式 Spring Boot 應用程式

若要建立回應式 Spring Boot 應用程式，我們將使用 Spring Initializr。我們將建立的應用程式會使用：

Spring Boot 2.7.11。
下列相依性：Spring Reactive Web（也稱為 Spring WebFlux）和 Spring Data R2DBC。

使用 Spring Initializr 產生應用程式

使用下列命令在命令列上產生應用程式：

curl https://start.spring.io/starter.tgz -d dependencies=webflux,data-r2dbc -d baseDir=azure-database-workshop -d bootVersion=2.7.11 -d javaVersion=17 | tar -xzvf -

新增回應式 PostgreSQL 驅動程序實作

開啟產生的專案 pom.xml 檔案，然後從 GitHub 上的 r2dbc-postgresql 存放庫新增回應式 PostgreSQL 驅動程式。在 spring-boot-starter-webflux 相依性之後，加入下列文字：

<dependency>
    <groupId>io.r2dbc</groupId>
    <artifactId>r2dbc-postgresql</artifactId>
    <version>0.8.12.RELEASE</version>
    <scope>runtime</scope>
</dependency>

將 Spring Boot 設定為使用適用於 PostgreSQL 的 Azure 資料庫

開啟 src/main/resources/application.properties 檔案，然後新增下列文字：

logging.level.org.springframework.data.r2dbc=DEBUG

spring.r2dbc.url=r2dbc:pool:postgres://$AZ_DATABASE_SERVER_NAME.postgres.database.azure.com:5432/$AZ_DATABASE_NAME
spring.r2dbc.username=nonspring
spring.r2dbc.password=$AZ_POSTGRESQL_NON_ADMIN_PASSWORD
spring.r2dbc.properties.sslMode=REQUIRE

將 $AZ_DATABASE_SERVER_NAME、 $AZ_DATABASE_NAME和 $AZ_POSTGRESQL_NON_ADMIN_PASSWORD 變數取代為您在本文中開頭所設定的值。

警告

出於安全考量，適用於 PostgreSQL 的 Azure 資料庫需要 SSL 連線。新增 spring.r2dbc.properties.sslMode=REQUIRE 組態屬性。否則，R2DBC PostgreSQL 驅動程式會嘗試使用不安全的連線連線，但連線失敗。

附註

為了提升效能，spring.r2dbc.url 屬性會設定為使用 r2dbc-pool 的連線集區。

您現在可以使用提供的 Maven 包裝開始申請，如下：

./mvnw spring-boot:run

以下是第一次執行的應用程式螢幕快照：

建立資料庫結構描述

在 main DemoApplication 類別內，使用下列程式代碼，設定將建立資料庫架構的新 Spring bean：

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.core.io.ClassPathResource;
import org.springframework.data.r2dbc.connectionfactory.init.ConnectionFactoryInitializer;
import org.springframework.data.r2dbc.connectionfactory.init.ResourceDatabasePopulator;

import io.r2dbc.spi.ConnectionFactory;

@SpringBootApplication
public class DemoApplication {

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

    @Bean
    public ConnectionFactoryInitializer initializer(ConnectionFactory connectionFactory) {
        ConnectionFactoryInitializer initializer = new ConnectionFactoryInitializer();
        initializer.setConnectionFactory(connectionFactory);
        ResourceDatabasePopulator populator = new ResourceDatabasePopulator(new ClassPathResource("schema.sql"));
        initializer.setDatabasePopulator(populator);
        return initializer;
    }
}

這個 Spring bean 使用稱為 schema.sql 的 檔案，因此請在 src/main/resources 資料夾中建立該檔案，然後新增下列文字：

DROP TABLE IF EXISTS todo;
CREATE TABLE todo (id SERIAL PRIMARY KEY, description VARCHAR(255), details VARCHAR(4096), done BOOLEAN);

停止執行中的應用程式，然後使用下列命令再次啟動它。應用程式現在會使用 demo 你之前建立的資料庫，並在裡面建立一個 todo 資料表。

./mvnw spring-boot:run

以下是建立資料庫資料表的螢幕快照：

編碼應用程式

接著，加入使用 R2DBC 來儲存和檢索 PostgreSQL 伺服器資料的 Java 程式碼。

使用下列程式碼，在 DemoApplication 類別旁邊建立新的 Todo Java 類別：

package com.example.demo;

import org.springframework.data.annotation.Id;

public class Todo {

    public Todo() {
    }

    public Todo(String description, String details, boolean done) {
        this.description = description;
        this.details = details;
        this.done = done;
    }

    @Id
    private Long id;

    private String description;

    private String details;

    private boolean done;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public String getDetails() {
        return details;
    }

    public void setDetails(String details) {
        this.details = details;
    }

    public boolean isDone() {
        return done;
    }

    public void setDone(boolean done) {
        this.done = done;
    }
}

這個類別是在您先前建立的 todo 資料表上對應的領域模型。

需要有存放庫才能管理該類別。使用下列程式代碼，在相同的套件中定義新的 TodoRepository 介面：

package com.example.demo;

import org.springframework.data.repository.reactive.ReactiveCrudRepository;

public interface TodoRepository extends ReactiveCrudRepository<Todo, Long> {
}

此存放庫是 Spring Data R2DBC 管理的回應式存放庫。

建立可儲存和擷取資料的控制器以完成應用程式。在相同的套件中實作 TodoController 類別，並新增下列程式碼：

package com.example.demo;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

@RestController
@RequestMapping("/")
public class TodoController {

    private final TodoRepository todoRepository;

    public TodoController(TodoRepository todoRepository) {
        this.todoRepository = todoRepository;
    }

    @PostMapping("/")
    @ResponseStatus(HttpStatus.CREATED)
    public Mono<Todo> createTodo(@RequestBody Todo todo) {
        return todoRepository.save(todo);
    }

    @GetMapping("/")
    public Flux<Todo> getTodos() {
        return todoRepository.findAll();
    }
}

最後，停止應用程式，然後使用下列命令再次啟動它：

./mvnw spring-boot:run

測試應用程式

若要測試應用程式，您可以使用 cURL。

首先，使用下列命令在資料庫中建立新的「todo」專案：

curl --header "Content-Type: application/json" \
    --request POST \
    --data '{"description":"configuration","details":"congratulations, you have set up R2DBC correctly!","done": "true"}' \
    http://127.0.0.1:8080

此命令應該會傳回已建立的專案，如下所示：

{"id":1,"description":"configuration","details":"congratulations, you have set up R2DBC correctly!","done":true}

接下來，使用新的 cURL 要求搭配下列命令來擷取數據：

curl http://127.0.0.1:8080

此命令會傳回「todo」項目清單，包括您所建立的專案，如下所示：

[{"id":1,"description":"configuration","details":"congratulations, you have set up R2DBC correctly!","done":true}]

以下是這些 cURL 要求的螢幕快照：

恭喜！你建立了一個完全被動式的 Spring Boot 應用程式，使用 R2DBC 來儲存和檢索適用於 PostgreSQL 的 Azure 資料庫的資料。

清除資源

若要清除本快速入門期間使用的所有資源，請使用下列命令刪除資源群組：

az group delete \
    --name $AZ_RESOURCE_GROUP \
    --yes

下一步

若要深入瞭解如何將 Spring Data 應用程式部署至 Azure Spring 應用程式和使用受控識別，請參閱教學課程：使用無密碼連線將 Spring 應用程式部署至 Azure Spring Apps。

若要深入了解 Spring 和 Azure，請繼續閱讀「Azure 上的 Spring」文件中心中的資訊。

Azure 上的 Spring

另請參閱

如需 Spring Data R2DBC 的詳細資訊，請參閱 Spring 的參考檔。

如需如何搭配使用 Azure 和 Java 的詳細資訊，請參閱適用於 Java 開發人員的 Azure 和使用 Azure DevOps 和 Java。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-31