Spring Boot 使用 PostgreSQL 完整入门指南-三亩地-编程学习日记

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

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

一、准备 PostgreSQL 数据库

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

CREATEDATABASEspringboot_demo;

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

dockerrun-d\--namepostgres-demo\-ePOSTGRES_USER=postgres\-ePOSTGRES_PASSWORD=123456\-ePOSTGRES_DB=springboot_demo\-p5432: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_demousername:postgrespassword:123456driver-class-name:org.postgresql.Driverjpa:hibernate:ddl-auto:updateshow-sql:trueproperties:hibernate:format_sql:true

常见的ddl-auto配置说明：

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

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

四、创建实体类

下面以用户表为例。

packagecom.example.demo.entity;importjakarta.persistence.*;importlombok.Data;importjava.time.LocalDateTime;@Data@Entity@Table(name="sys_user")publicclassUser{@Id@GeneratedValue(strategy=GenerationType.IDENTITY)privateLongid;@Column(nullable=false)privateStringusername;@Column(nullable=false)privateStringemail;privateIntegerage;@Column(name="created_at")privateLocalDateTimecreatedAt;}

说明：

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

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

五、创建 Repository

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

packagecom.example.demo.repository;importcom.example.demo.entity.User;importorg.springframework.data.jpa.repository.JpaRepository;importjava.util.Optional;publicinterfaceUserRepositoryextendsJpaRepository<User,Long>{Optional<User>findByUsername(Stringusername);}

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

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

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

Optional<User>findByUsername(Stringusername);

六、创建 Service

packagecom.example.demo.service;importcom.example.demo.entity.User;importcom.example.demo.repository.UserRepository;importlombok.RequiredArgsConstructor;importorg.springframework.stereotype.Service;importjava.time.LocalDateTime;importjava.util.List;@Service@RequiredArgsConstructorpublicclassUserService{privatefinalUserRepositoryuserRepository;publicUsercreate(Useruser){user.setCreatedAt(LocalDateTime.now());returnuserRepository.save(user);}publicList<User>list(){returnuserRepository.findAll();}publicUsergetById(Longid){returnuserRepository.findById(id).orElseThrow(()->newRuntimeException("用户不存在"));}publicUserupdate(Longid,Userrequest){Useruser=getById(id);user.setUsername(request.getUsername());user.setEmail(request.getEmail());user.setAge(request.getAge());returnuserRepository.save(user);}publicvoiddelete(Longid){userRepository.deleteById(id);}}

七、创建 Controller

packagecom.example.demo.controller;importcom.example.demo.entity.User;importcom.example.demo.service.UserService;importlombok.RequiredArgsConstructor;importorg.springframework.web.bind.annotation.*;importjava.util.List;@RestController@RequestMapping("/users")@RequiredArgsConstructorpublicclassUserController{privatefinalUserServiceuserService;@PostMappingpublicUsercreate(@RequestBodyUseruser){returnuserService.create(user);}@GetMappingpublicList<User>list(){returnuserService.list();}@GetMapping("/{id}")publicUsergetById(@PathVariableLongid){returnuserService.getById(id);}@PutMapping("/{id}")publicUserupdate(@PathVariableLongid,@RequestBodyUseruser){returnuserService.update(id,user);}@DeleteMapping("/{id}")publicvoiddelete(@PathVariableLongid){userService.delete(id);}}

八、测试接口

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

新增用户

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

查询用户列表

curlhttp://localhost:8080/users

查询单个用户

curlhttp://localhost:8080/users/1

修改用户

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

删除用户

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

九、使用 PostgreSQL JSON 字段

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

例如创建一个配置字段：

@Column(columnDefinition="jsonb")privateStringextra;

请求示例：

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

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

十、分页查询

Spring Data JPA 内置分页支持。

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

@GetMapping("/page")publicPage<User>page(@RequestParam(defaultValue="0")intpage,@RequestParam(defaultValue="10")intsize){returnuserRepository.findAll(PageRequest.of(page,size));}

需要引入：

importorg.springframework.data.domain.Page;importorg.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 是一个非常稳定、成熟的组合。

日记详情

Spring Boot 使用 PostgreSQL 完整入门指南