搭配 Azure SQL 資料庫使用 Spring Data R2DBC

本文說明如何建立一個範例應用程式，使用 Spring Data R2DBC 透過來自 r2dbc-mssql GitHub repository 的 Microsoft SQL Server R2DBC 實作，在 Azure SQL Database 中儲存及擷取資訊。

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

必要條件

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

sqlcmd 公用程式。
cURL 或類似的 HTTP 公用程式來測試功能。

請參閱範例應用程式

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

準備工作環境

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

export AZ_RESOURCE_GROUP=database-workshop
export AZ_DATABASE_NAME=<YOUR_DATABASE_NAME>
export AZ_LOCATION=<YOUR_AZURE_REGION>
export AZ_SQL_SERVER_ADMIN_USERNAME=spring
export AZ_SQL_SERVER_ADMIN_PASSWORD=<YOUR_AZURE_SQL_ADMIN_PASSWORD>
export AZ_SQL_SERVER_NON_ADMIN_USERNAME=nonspring
export AZ_SQL_SERVER_NON_ADMIN_PASSWORD=<YOUR_AZURE_SQL_NON_ADMIN_PASSWORD>
export AZ_LOCAL_IP_ADDRESS=<YOUR_LOCAL_IP_ADDRESS>

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

<YOUR_DATABASE_NAME>：Azure SQL 資料庫伺服器的名稱，在 Azure 中應該是唯一的。
<YOUR_AZURE_REGION>：您要使用的 Azure 區域。你可以預設使用 eastus ，但設定一個離你住處更近的區域。請使用 az account list-locations 查看可用區域的完整清單。
<AZ_SQL_SERVER_ADMIN_PASSWORD>和 <AZ_SQL_SERVER_NON_ADMIN_PASSWORD>：Azure SQL 資料庫伺服器的密碼，至少應有八個字元。這些字元應屬於下列三種類別：英文大寫字母、英文小寫字母、數字 (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

建立 Azure SQL 資料庫執行個體

接下來，執行下列命令來建立受控 Azure SQL 資料庫伺服器實例。

附註

MS SQL 密碼必須符合特定條件，若密碼不合規，設定即失敗。如需詳細資訊，請參閱＜ Password Policy＞。

az sql server create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_NAME \
    --location $AZ_LOCATION \
    --admin-user $AZ_SQL_SERVER_ADMIN_USERNAME \
    --admin-password $AZ_SQL_SERVER_ADMIN_PASSWORD \
    --output tsv

設定 Azure SQL 資料庫伺服器的防火牆規則

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

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

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

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

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

cat /etc/resolv.conf

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

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

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


az sql server firewall-rule create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_NAME-database-allow-local-ip-wsl \
    --server $AZ_DATABASE_NAME \
    --start-ip-address $AZ_WSL_IP_ADDRESS \
    --end-ip-address $AZ_WSL_IP_ADDRESS \
    --output tsv

設定 Azure SQL 資料庫

您稍早建立的 Azure SQL 資料庫伺服器是空的。它沒有任何資料庫可以搭配 Spring Boot 應用程式使用。執行下列命令來建立名為 demo 的新資料庫：

az sql db create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name demo \
    --server $AZ_DATABASE_NAME \
    --output tsv

建立 SQL 資料庫非系統管理員帳戶並授予權限

在這個步驟中，你會建立一個非管理員使用者，並將資料庫上的所有權限 demo 授予該使用者。

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

附註

cat << EOF > create_user.sql
USE demo;
GO
CREATE USER $AZ_SQL_SERVER_NON_ADMIN_USERNAME WITH PASSWORD='$AZ_SQL_SERVER_NON_ADMIN_PASSWORD'
GO
GRANT CONTROL ON DATABASE::demo TO $AZ_SQL_SERVER_NON_ADMIN_USERNAME;
GO
EOF

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

sqlcmd -S $AZ_DATABASE_NAME.database.windows.net,1433  -d demo -U $AZ_SQL_SERVER_ADMIN_USERNAME -P $AZ_SQL_SERVER_ADMIN_PASSWORD  -i create_user.sql

附註

如需建立 SQL 資料庫使用者的詳細資訊，請參閱 CREATE USER （Transact-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 -

新增回應式 Azure SQL 資料庫驅動程序實作

開啟產生的專案pom.xml檔案，從 r2dbc-mssql GitHub 存放庫新增回應式 Azure SQL 資料庫驅動程式。

在 spring-boot-starter-webflux 相依性之後，加入下列文字：

<dependency>
    <groupId>io.r2dbc</groupId>
    <artifactId>r2dbc-mssql</artifactId>
    <scope>runtime</scope>
</dependency>

設定 Spring Boot 以使用 Azure SQL 資料庫

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

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

spring.r2dbc.url=r2dbc:pool:mssql://$AZ_DATABASE_NAME.database.windows.net:1433/demo
spring.r2dbc.username=nonspring@$AZ_DATABASE_NAME
spring.r2dbc.password=$AZ_SQL_SERVER_NON_ADMIN_PASSWORD

將兩個 $AZ_DATABASE_NAME 變數和 $AZ_SQL_SERVER_NON_ADMIN_PASSWORD 變數替換為您在本文開頭所設定的值。

附註

為了提升效能，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 INT IDENTITY PRIMARY KEY, description VARCHAR(255), details VARCHAR(4096), done BIT);

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

./mvnw spring-boot:run

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

編碼應用程式

接著，加入使用 R2DBC 來儲存和取回 Azure SQL Database 伺服器資料的 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 來儲存和檢索 Azure SQL Database 的資料。

清除資源

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

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-09-02