PostgreSQL 是一个功能强大的开源关系型数据库支持事务、索引、JSON、全文检索、窗口函数等能力。在 Spring Boot 项目中PostgreSQL 经常用于业务系统、后台管理系统、数据分析平台等场景。本文介绍如何在 Spring Boot 中集成 PostgreSQL并完成常见的增删改查操作。一、准备 PostgreSQL 数据库如果你本地已经安装 PostgreSQL可以直接创建数据库CREATEDATABASEspringboot_demo;如果使用 Docker可以通过下面命令快速启动dockerrun-d\--namepostgres-demo\-ePOSTGRES_USERpostgres\-ePOSTGRES_PASSWORD123456\-ePOSTGRES_DBspringboot_demo\-p5432:5432\postgres:16连接信息如下host: localhost port: 5432 database: springboot_demo username: postgres password: 123456二、创建 Spring Boot 项目项目依赖可以选择Spring WebSpring Data JPAPostgreSQL DriverLombok如果使用 Mavenpom.xml中加入以下依赖dependencies!-- Web 接口支持 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Spring Data JPA --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-data-jpa/artifactId/dependency!-- PostgreSQL 驱动 --dependencygroupIdorg.postgresql/groupIdartifactIdpostgresql/artifactIdscoperuntime/scope/dependency!-- Lombok可选 --dependencygroupIdorg.projectlombok/groupIdartifactIdlombok/artifactIdoptionaltrue/optional/dependency/dependencies三、配置数据库连接在application.yml中配置 PostgreSQLspring: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;DataEntityTable(namesys_user)publicclassUser{IdGeneratedValue(strategyGenerationType.IDENTITY)privateLongid;Column(nullablefalse)privateStringusername;Column(nullablefalse)privateStringemail;privateIntegerage;Column(namecreated_at)privateLocalDateTimecreatedAt;}说明Entity声明这是一个 JPA 实体类 Table指定数据库表名 Id指定主键 GeneratedValue指定主键生成策略 Column指定字段映射规则PostgreSQL 支持自增主键使用GenerationType.IDENTITY即可。五、创建 RepositorySpring Data JPA 可以自动生成常见的数据库操作方法。packagecom.example.demo.repository;importcom.example.demo.entity.User;importorg.springframework.data.jpa.repository.JpaRepository;importjava.util.Optional;publicinterfaceUserRepositoryextendsJpaRepositoryUser,Long{OptionalUserfindByUsername(Stringusername);}继承JpaRepositoryUser, Long后可以直接使用save() findById() findAll() deleteById() count()也可以按照方法名自动生成查询例如OptionalUserfindByUsername(Stringusername);六、创建 Servicepackagecom.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;ServiceRequiredArgsConstructorpublicclassUserService{privatefinalUserRepositoryuserRepository;publicUsercreate(Useruser){user.setCreatedAt(LocalDateTime.now());returnuserRepository.save(user);}publicListUserlist(){returnuserRepository.findAll();}publicUsergetById(Longid){returnuserRepository.findById(id).orElseThrow(()-newRuntimeException(用户不存在));}publicUserupdate(Longid,Userrequest){UserusergetById(id);user.setUsername(request.getUsername());user.setEmail(request.getEmail());user.setAge(request.getAge());returnuserRepository.save(user);}publicvoiddelete(Longid){userRepository.deleteById(id);}}七、创建 Controllerpackagecom.example.demo.controller;importcom.example.demo.entity.User;importcom.example.demo.service.UserService;importlombok.RequiredArgsConstructor;importorg.springframework.web.bind.annotation.*;importjava.util.List;RestControllerRequestMapping(/users)RequiredArgsConstructorpublicclassUserController{privatefinalUserServiceuserService;PostMappingpublicUsercreate(RequestBodyUseruser){returnuserService.create(user);}GetMappingpublicListUserlist(){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\-HContent-Type: application/json\-d{username:zhangsan,email:zhangsanexample.com,age:20}查询用户列表curlhttp://localhost:8080/users查询单个用户curlhttp://localhost:8080/users/1修改用户curl-XPUT http://localhost:8080/users/1\-HContent-Type: application/json\-d{username:lisi,email:lisiexample.com,age:25}删除用户curl-XDELETE http://localhost:8080/users/1九、使用 PostgreSQL JSON 字段PostgreSQL 支持json和jsonb类型实际开发中推荐使用jsonb查询和索引能力更强。例如创建一个配置字段Column(columnDefinitionjsonb)privateStringextra;请求示例{username:wangwu,email:wangwuexample.com,age:30,extra:{\level\:\vip\,\source\:\app\}}如果项目中需要更复杂的 JSON 映射可以使用 Hibernate Types 或自定义转换器。十、分页查询Spring Data JPA 内置分页支持。Repository 不需要额外修改Controller 可以这样写GetMapping(/page)publicPageUserpage(RequestParam(defaultValue0)intpage,RequestParam(defaultValue10)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_detail3. 生产环境不要随便使用 ddl-autoupdateddl-autoupdate适合开发环境快速调试但生产环境不建议依赖它自动改表。生产环境更推荐使用Flyway Liquibase 手写 SQL 脚本这样可以保证数据库变更可追踪、可回滚、可审计。十二、总结Spring Boot 集成 PostgreSQL 的核心步骤并不复杂引入 PostgreSQL Driver 和 Spring Data JPA配置spring.datasource创建实体类创建 Repository编写 Service 和 Controller通过接口完成增删改查PostgreSQL 本身功能非常丰富除了普通关系型数据存储外还支持 JSON、全文检索、数组类型、窗口函数、事务和复杂索引。在中后台系统、业务平台、数据服务中Spring Boot PostgreSQL 是一个非常稳定、成熟的组合。