在 Spring Boot 中使用 Supabase

先决条件 #

🌐 Prerequisites

在开始之前，确保你有：

🌐 Before you begin, make sure you have:

• Java 17 或更高版本，你可以用 java -version 检查
• curl 和 unzip，用于下载并解压生成的项目

1. 创建一个 Supabase 项目 #

🌐 1. Create a Supabase project

首先，你需要一个 Supabase 项目。

🌐 To start, you need a Supabase project.

从你所属的任何组织的仪表板创建一个新的 Supabase 项目。

🌐 Create a new Supabase project from the Dashboard of any organization you belong to.

安全地保存你的数据库密码。你连接数据库时需要它。

🌐 Save your database password securely. You need it for the connection string.

2. 创建一个 Spring Boot 项目 #

🌐 2. Create a Spring Boot project

使用 Spring Initializr 创建一个新的项目，添加 Web、Spring Data JPA 和 Postgres 驱动依赖。从你存放项目的目录运行以下命令。

🌐 Use Spring Initializr to scaffold a new project with the Web, Spring Data JPA, and Postgres Driver dependencies. Run the following from the directory where you keep your projects.

1
curl https://start.spring.io/starter.zip \
2
  -d dependencies=web,data-jpa,postgresql \
3
  -d type=maven-project \
4
  -d language=java \
5
  -d groupId=com.example \
6
  -d artifactId=instruments \
7
  -d name=instruments \
8
  -o instruments.zip
9
unzip instruments.zip -d instruments && cd instruments

3. 设置 AI 工具（可选） #

🌐 3. Set up AI tooling (optional)

Supabase 提供了两种方式让 AI 工具了解你的项目：Agent Skills，它为你的 AI 编程助手提供操作知识；以及 MCP 服务器，它可以让 AI 助手直接连接到你的 Supabase 项目。

🌐 Supabase provides two ways to give AI tools context about your project: Agent Skills, which give your AI coding agent procedural knowledge, and the MCP server, which connects AI assistants to your Supabase project directly.

代理技能 #

🌐 Agent Skills

代理技能 是一套精心整理的指令，提供你的 AI 代理有关使用 Supabase 的操作知识。

安装它们，这样你的 AI 编码代理就能使用当前的 Supabase 模式（比如认证、服务端渲染和数据库迁移）生成更准确、更可靠的代码，而不只是依赖培训数据。

🌐 Install them so your AI coding agent can produce more accurate, reliable code using current Supabase patterns, such as authentication, server-side rendering, and database migrations, rather than relying solely on training data.

安装代理技能 #

🌐 Installing Agent Skills

要安装，在你项目的根目录运行以下命令：

🌐 To install, run the following command in the root of your project:

1
npx skills add supabase/agent-skills

Supabase MCP 服务器 #

🌐 Supabase MCP server

Supabase MCP 服务器将 AI 助手连接到 Supabase，这样它们就可以检查你的架构并代表你操作项目。在 MCP 文档 中了解如何将它添加到你的客户端。

🌐 The Supabase MCP server connects AI assistants to Supabase, so they can inspect your schema and act on your projects on your behalf. Find out how to add it to your client in the MCP docs.

4. 设置 Postgres 连接详情 #

🌐 4. Set up the Postgres connection details

1. 导航到你的项目仪表板，然后点击连接。

   不要把事务池（端口 6543）当作你应用的主要数据源。大多数 ORM 依赖服务器端的预处理语句，而事务池不支持。可以使用会话池（端口 5432），或者如果你在 IPv6 环境 下，或者有 IPv4 插件，就直接用连接字符串。

2. 找到会话池连接字符串并复制它。将密码占位符替换为你保存的数据库密码，并对其中的任何保留字符进行百分号编码，比如 &、#、? 或空格。如果你没有数据库密码，可以在你的数据库设置中重置它。

3. 如果你的框架单独设置它，可以在连接字符串上或作为显式配置选项设置 sslmode=require。大多数驱动默认使用 prefer，如果加密尝试失败，就会回退到以明文发送数据。你也可以在数据库端强制使用 SSL。

下面的连接字符串只是显示格式。请从你复制的字符串中获取主机、端口和用户名，而不是直接输入括号里的占位符。

🌐 The connection strings below show the format only. Take the host, port, and username from the string you copied rather than typing the bracketed placeholders literally.

选择 JDBC 标签，以便复制适用于 Spring Boot 的正确格式的连接字符串。

🌐 Select the JDBC tab to copy the connection string in the right format for Spring Boot.

连接字符串包含你的数据库密码，而 application.properties 已经和你的项目一起提交了。最好将这个字符串设置为环境变量，并在你部署的任何平台上用相同的方式设置它。

🌐 The connection string contains your database password, and application.properties is committed with your project. Set the string as an environment variable instead, and set it the same way on whatever platform you deploy to.

1
export SUPABASE_DB_URL='jdbc:postgresql://[POOLER-HOST]:5432/postgres?user=postgres.[PROJECT-REF]&password=[YOUR-PASSWORD]&sslmode=require'

然后在 src/main/resources/application.properties 中引用该变量和驱动程序。

🌐 Then reference the variable, along with the driver, in src/main/resources/application.properties.

1
spring.datasource.url=${SUPABASE_DB_URL}
2
spring.datasource.driver-class-name=org.postgresql.Driver
3
spring.jpa.hibernate.ddl-auto=update

如果应用在使用 Unable to determine Dialect without JDBC metadata 时启动失败，Hibernate 根本无法建立连接。查看日志中那行上面的内容来找到真正的原因，最常见的是 password authentication failed。

🌐 If the app fails to start with Unable to determine Dialect without JDBC metadata, Hibernate couldn't open a connection at all. Look above that line in the logs for the real cause, most commonly password authentication failed.

5. 更改默认模式 #

🌐 5. Change the default schema

默认情况下，Hibernate 会在 public 架构中创建表。我们建议更改这一设置，因为 Supabase 会将 public 架构作为 数据 API 暴露出来。

🌐 By default Hibernate creates tables in the public schema. We recommend changing this as Supabase exposes the public schema as a data API.

在启动应用之前先创建 app 架构。Hibernate 会在启动时在该架构中创建表，但它不会自己创建架构。在 SQL 编辑器 中运行以下命令：

🌐 Create the app schema before you start the app. Hibernate creates tables in that schema on startup, but it does not create the schema itself. Run the following in the SQL Editor:

1
create schema if not exists app;

然后让 Hibernate 指向 application.properties 里的 schema。

🌐 Then point Hibernate at the schema in application.properties.

1
spring.jpa.properties.hibernate.default_schema=app

6. 创建一个实体和仓库 #

🌐 6. Create an entity and repository

Spring Data JPA 将 Java 类映射到数据库表。在 src/main/java/com/example/instruments/Instrument.java 中创建一个 Instrument 实体。当设置了 spring.jpa.hibernate.ddl-auto=update 后，Hibernate 会在应用启动时为你创建 instruments 表。

🌐 Spring Data JPA maps Java classes to database tables. Create an Instrument entity in src/main/java/com/example/instruments/Instrument.java. With spring.jpa.hibernate.ddl-auto=update set, Hibernate creates the instruments table for you when the app starts.

1
package com.example.instruments;
2
3
import jakarta.persistence.Entity;
4
import jakarta.persistence.GeneratedValue;
5
import jakarta.persistence.GenerationType;
6
import jakarta.persistence.Id;
7
import jakarta.persistence.Table;
8
9
@Entity
10
@Table(name = "instruments")
11
public class Instrument {
12
13
    @Id
14
    @GeneratedValue(strategy = GenerationType.IDENTITY)
15
    private Long id;
16
17
    private String name;
18
19
    public Instrument() {}
20
21
    public Instrument(String name) {
22
        this.name = name;
23
    }
24
25
    public Long getId() {
26
        return id;
27
    }
28
29
    public String getName() {
30
        return name;
31
    }
32
33
    public void setName(String name) {
34
        this.name = name;
35
    }
36
}

在同一个包里创建一个 InstrumentRepository 接口。继承 JpaRepository 就能得到 findAll、save 和其他查询方法，而无需编写任何实现。

🌐 Create an InstrumentRepository interface in the same package. Extending JpaRepository gives you findAll, save, and other query methods without writing any implementation.

1
package com.example.instruments;
2
3
import org.springframework.data.jpa.repository.JpaRepository;
4
5
public interface InstrumentRepository extends JpaRepository<Instrument, Long> {}

7. 初始化示例数据 #

🌐 7. Seed sample data

在 InstrumentsApplication.java 中添加一个 CommandLineRunner bean，用于在应用第一次启动时保存一些示例乐器。

🌐 Add a CommandLineRunner bean to InstrumentsApplication.java that saves some sample instruments the first time the app starts.

1
package com.example.instruments;
2
3
import org.springframework.boot.CommandLineRunner;
4
import org.springframework.boot.SpringApplication;
5
import org.springframework.boot.autoconfigure.SpringBootApplication;
6
import org.springframework.context.annotation.Bean;
7
8
@SpringBootApplication
9
public class InstrumentsApplication {
10
11
    public static void main(String[] args) {
12
        SpringApplication.run(InstrumentsApplication.class, args);
13
    }
14
15
    @Bean
16
    CommandLineRunner seedInstruments(InstrumentRepository instrumentRepository) {
17
        return args -> {
18
            if (instrumentRepository.count() == 0) {
19
                instrumentRepository.save(new Instrument("violin"));
20
                instrumentRepository.save(new Instrument("viola"));
21
                instrumentRepository.save(new Instrument("cello"));
22
            }
23
        };
24
    }
25
}

8. 从应用中查询数据 #

🌐 8. Query data from the app

创建一个 InstrumentController，通过仓库获取 instruments 表的每一行，并以 JSON 返回。

🌐 Create an InstrumentController that fetches every row from the instruments table through the repository and returns it as JSON.

1
package com.example.instruments;
2
3
import java.util.List;
4
5
import org.springframework.web.bind.annotation.GetMapping;
6
import org.springframework.web.bind.annotation.RestController;
7
8
@RestController
9
public class InstrumentController {
10
11
    private final InstrumentRepository instrumentRepository;
12
13
    public InstrumentController(InstrumentRepository instrumentRepository) {
14
        this.instrumentRepository = instrumentRepository;
15
    }
16
17
    @GetMapping("/instruments")
18
    public List<Instrument> getInstruments() {
19
        return instrumentRepository.findAll();
20
    }
21
}

9. 启动应用 #

🌐 9. Start the app

运行 Spring Boot 应用，然后在浏览器中打开 http://localhost:8080/instruments。你应该能看到乐器列表。

🌐 Run the Spring Boot app, and go to http://localhost:8080/instruments in your browser. You should see the list of instruments.

1
./mvnw spring-boot:run

生产要求 #

🌐 Production requirements

本指南中的快速入门步骤是为了让你尽快运行起一个可用的应用，而不是为了生产环境优化。

🌐 The quickstart procedure in this guide optimizes for getting you to a working app, not for production.

在你部署之前：

🌐 Before you deploy:

• 如果你的应用通过数据 API 读取或写入数据，请查看你的 行级安全 策略。你在这里添加的任何策略都是针对这个快速入门的示例数据，而不是针对真实用户数据。
• 在你部署的平台上把 Supabase 凭据设置为环境变量，而不是把它们提交到源码管理里。
• 一旦你准备上线，就为你的 Supabase 项目配置一个自定义域名。

下一步 #

🌐 Next steps

• 为你的应用设置 Auth
• 把更多数据插入到你的数据库里
• 使用 Storage 上传和提供静态文件
• 在投入生产前，将 ddl-auto 替换为 数据库迁移