首页 > 软件编程 > java > SpringBoot集成PostgreSQL

SpringBoot集成PostgreSQL实现增删改查的完整入门指南

2026-08-18 08:40:20 作者：ly7689

本文详细讲解如何在SpringBoot项目中集成PostgreSQL数据库,包括环境准备、依赖配置、实体类与Repository的编写,以及完整的增删改查操作,同时深入探讨了JSON字段的使用、分页查询和常见问题解决方法,需要的朋友可以参考下

PostgreSQL 是一个功能强大的开源关系型数据库，支持事务、索引、JSON、全文检索、窗口函数等能力。在 Spring Boot 项目中，PostgreSQL 经常用于业务系统、后台管理系统、数据分析平台等场景。

本文介绍如何在 Spring Boot 中集成 PostgreSQL，并完成常见的增删改查操作。

一、准备 PostgreSQL 数据库

如果你本地已经安装 PostgreSQL，可以直接创建数据库：

CREATE DATABASE springboot_demo;

如果使用 Docker，可以通过下面命令快速启动：

docker run -d \
  --name postgres-demo \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=123456 \
  -e POSTGRES_DB=springboot_demo \
  -p 5432:5432 \
  postgres:16

连接信息如下：

host: localhost
port: 5432
database: springboot_demo
username: postgres
password: 123456

二、创建 Spring Boot 项目

项目依赖可以选择：

Spring Web
Spring Data JPA
PostgreSQL Driver
Lombok

如果使用 Maven，pom.xml 中加入以下依赖：

<dependencies>
    <!-- Web 接口支持 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Spring Data JPA -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <!-- PostgreSQL 驱动 -->
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
    </dependency>
    <!-- Lombok，可选 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

三、配置数据库连接

在 application.yml 中配置 PostgreSQL：

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/springboot_demo
    username: postgres
    password: 123456
    driver-class-name: org.postgresql.Driver
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
    properties:
      hibernate:
        format_sql: true

常见的 ddl-auto 配置说明：

none：不自动处理表结构
validate：启动时校验表结构
update：自动更新表结构，开发环境常用
create：每次启动重新建表
create-drop：启动建表，关闭时删表

开发环境可以使用 update，生产环境建议使用 Flyway 或 Liquibase 管理数据库脚本。

四、创建实体类

下面以用户表为例。

package com.example.demo.entity;

import jakarta.persistence.*;
import lombok.Data;

import java.time.LocalDateTime;

@Data
@Entity
@Table(name = "sys_user")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String username;

    @Column(nullable = false)
    private String email;

    private Integer age;

    @Column(name = "created_at")
    private LocalDateTime createdAt;
}

说明：

@Entity：声明这是一个 JPA 实体类
@Table：指定数据库表名
@Id：指定主键
@GeneratedValue：指定主键生成策略
@Column：指定字段映射规则

PostgreSQL 支持自增主键，使用 GenerationType.IDENTITY 即可。

五、创建 Repository

Spring Data JPA 可以自动生成常见的数据库操作方法。

package com.example.demo.repository;

import com.example.demo.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;

import java.util.Optional;

public interface UserRepository extends JpaRepository<User, Long> {

    Optional<User> findByUsername(String username);
}

继承 JpaRepository<User, Long> 后，可以直接使用：

save()
findById()
findAll()
deleteById()
count()

也可以按照方法名自动生成查询，例如：

Optional<User> findByUsername(String username);

六、创建 Service

package com.example.demo.service;

import com.example.demo.entity.User;
import com.example.demo.repository.UserRepository;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

import java.time.LocalDateTime;
import java.util.List;

@Service
@RequiredArgsConstructor
public class UserService {

    private final UserRepository userRepository;

    public User create(User user) {
        user.setCreatedAt(LocalDateTime.now());
        return userRepository.save(user);
    }

    public List<User> list() {
        return userRepository.findAll();
    }

    public User getById(Long id) {
        return userRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("用户不存在"));
    }

    public User update(Long id, User request) {
        User user = getById(id);
        user.setUsername(request.getUsername());
        user.setEmail(request.getEmail());
        user.setAge(request.getAge());
        return userRepository.save(user);
    }

    public void delete(Long id) {
        userRepository.deleteById(id);
    }
}

七、创建 Controller

package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    @PostMapping
    public User create(@RequestBody User user) {
        return userService.create(user);
    }

    @GetMapping
    public List<User> list() {
        return userService.list();
    }

    @GetMapping("/{id}")
    public User getById(@PathVariable Long id) {
        return userService.getById(id);
    }

    @PutMapping("/{id}")
    public User update(@PathVariable Long id, @RequestBody User user) {
        return userService.update(id, user);
    }

    @DeleteMapping("/{id}")
    public void delete(@PathVariable Long id) {
        userService.delete(id);
    }
}

八、测试接口

启动 Spring Boot 项目后，可以使用 curl 测试。

新增用户

curl -X POST http://localhost:8080/users \
  -H "Content-Type: application/json" \
  -d '{"username":"zhangsan","email":"zhangsan@example.com","age":20}'

查询用户列表

curl http://localhost:8080/users

查询单个用户

curl http://localhost:8080/users/1

修改用户

curl -X PUT http://localhost:8080/users/1 \
  -H "Content-Type: application/json" \
  -d '{"username":"lisi","email":"lisi@example.com","age":25}'

删除用户

curl -X DELETE http://localhost:8080/users/1

九、使用 PostgreSQL JSON 字段

PostgreSQL 支持 json 和 jsonb 类型，实际开发中推荐使用 jsonb，查询和索引能力更强。

例如创建一个配置字段：

@Column(columnDefinition = "jsonb")
private String extra;

请求示例：

{
  "username": "wangwu",
  "email": "wangwu@example.com",
  "age": 30,
  "extra": "{\"level\":\"vip\",\"source\":\"app\"}"
}

如果项目中需要更复杂的 JSON 映射，可以使用 Hibernate Types 或自定义转换器。

十、分页查询

Spring Data JPA 内置分页支持。

Repository 不需要额外修改，Controller 可以这样写：

@GetMapping("/page")
public Page<User> page(@RequestParam(defaultValue = "0") int page,
                       @RequestParam(defaultValue = "10") int size) {
    return userRepository.findAll(PageRequest.of(page, size));
}

需要引入：

import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;

注意：Spring Data JPA 的页码从 0 开始。

十一、常见问题

1. 连接失败

常见错误：

Connection refused

需要检查：

PostgreSQL 是否启动
端口是否为 5432
用户名和密码是否正确
数据库是否已创建

2. 表名大小写问题

PostgreSQL 默认会把未加双引号的表名、字段名转换为小写。

建议统一使用小写加下划线命名：

sys_user
created_at
order_detail

3. 生产环境不要随便使用 ddl-auto=update

ddl-auto=update 适合开发环境快速调试，但生产环境不建议依赖它自动改表。

生产环境更推荐使用：

Flyway
Liquibase
手写 SQL 脚本

这样可以保证数据库变更可追踪、可回滚、可审计。

十二、总结

Spring Boot 集成 PostgreSQL 的核心步骤并不复杂：

引入 PostgreSQL Driver 和 Spring Data JPA
配置 spring.datasource
创建实体类
创建 Repository
编写 Service 和 Controller
通过接口完成增删改查

PostgreSQL 本身功能非常丰富，除了普通关系型数据存储外，还支持 JSON、全文检索、数组类型、窗口函数、事务和复杂索引。在中后台系统、业务平台、数据服务中，Spring Boot + PostgreSQL 是一个非常稳定、成熟的组合。

以上就是SpringBoot集成PostgreSQL的完整入门指南的详细内容，更多关于SpringBoot集成PostgreSQL的资料请关注脚本之家其它相关文章！