Spring Data JPA 接入金仓数据库：少写代码，多干活

Spring Data JPA 接入金仓数据库：少写代码，多干活

从一个需求说起

上个月接了个小任务：两周内搭一个用户中心的原型，要支持增删改查和分页。时间紧、活不多，我想着能少写代码就少写。

以前用 MyBatis 的时候，每个表都要手写 mapper 接口、xml 文件、service 层——一套下来代码不少。这次想换个思路，试试 Spring Data JPA。之前听说这玩意儿能在接口里直接写 SQL，连实现类都不用，今天正好验证一下它对金仓数据库的支持怎么样。

从配依赖到跑通整个 CRUD，大概花了一个多小时。中间还试了自定义 SQL 和分页，跑得都挺顺。今天就把这个过程整理出来。

一、先准备好连接信息

动手之前，先找 DBA 要数据库的连接信息。一般会给你一个类似这样的命令：

./ksql -U system -d test -h 192.168.1.100 -p 54321

这里面包含四个关键信息：

• 用户名：system（默认管理员）
• 数据库名：test
• IP 地址：192.168.1.100
• 端口号：54321（金仓默认端口）

先用命令行连一下，确认账号密码没问题，再继续下一步。

二、项目搭建

2.1 目录结构

java-kingbase-springdatajpa/
├── pom.xml
├── src/main/
│   ├── java/com/kingbase/testspringdatajpa/
│   │   ├── TestSpringDataJpaApplication.java   # 启动类
│   │   ├── dao/
│   │   │   └── UserRepository.java             # 数据访问接口
│   │   ├── entity/
│   │   │   └── User.java                       # 实体类
│   │   └── service/
│   │       ├── UserService.java                # 服务接口
│   │       └── impl/UserServiceImpl.java       # 服务实现
│   └── resources/
│       └── application.yml                     # 配置文件
└── src/test/
    └── java/.../TestSpringDataJpaApplicationTests.java

和 MyBatis 比，少了一个 IUserMapper.xml，多了一个 service/impl 目录。JPA 的 Repository 接口自带基础 CRUD 方法，不用自己写实现类。

2.2 pom.xml：引入依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.0</version>
        <relativePath/>
    </parent>
    
    <groupId>com.kingbase</groupId>
    <artifactId>java-kingbase-springdatajpa</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    
    <properties>
        <java.version>1.8</java.version>
    </properties>
    
    <dependencies>
        <!-- JPA 核心依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        
        <!-- Web 支持 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- 金仓 JDBC 驱动 -->
        <dependency>
            <groupId>cn.com.kingbase</groupId>
            <artifactId>kingbase8</artifactId>
            <version>9.0.0</version>
        </dependency>
        
        <!-- Druid 连接池（可选，Spring Boot 默认自带 HikariCP） -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid</artifactId>
            <version>1.2.8</version>
        </dependency>
        
        <!-- 测试 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

JPA 的 spring-boot-starter-data-jpa 会自动引入 Hibernate，不用单独配置。

2.3 application.yml：配置文件

server:
  servlet:
    context-path: /testspringdatajpa
  port: 8890

spring:
  datasource:
    driver-class-name: com.kingbase8.Driver
    url: jdbc:kingbase8://192.168.1.100:54321/test
    username: system
    password: 你的密码
    type: com.alibaba.druid.pool.DruidDataSource   # 用 Druid 连接池
  jpa:
    database-platform: org.hibernate.dialect.Kingbase8Dialect
    hibernate:
      ddl-auto: update        # 自动更新表结构
    show-sql: true            # 打印 SQL
    format-sql: true          # 格式化 SQL
    open-in-view: false

关键点：database-platform 必须配成 org.hibernate.dialect.Kingbase8Dialect，Hibernate 才能生成适合金仓的 SQL。

ddl-auto: update 方便开发测试，生产环境建议用 none 或 validate。

三、代码实现

3.1 实体类 User.java

package com.kingbase.testspringdatajpa.entity;

import javax.persistence.*;

@Entity
@Table(name = "test_springdatajpa_2")
public class User {
    
    @Id
    @GeneratedValue(strategy = GenerationType.TABLE)
    @Column(name = "id", nullable = false)
    private Integer id;
    
    @Column(name = "username")
    private String username;
    
    public User() {}
    
    public User(Integer id, String username) {
        this.id = id;
        this.username = username;
    }
    
    // getter / setter 省略...
    
    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", username='" + username + '\'' +
                '}';
    }
}

@GeneratedValue(strategy = GenerationType.TABLE) 适合老版本金仓。新版可以改用 GenerationType.IDENTITY。

3.2 Repository 接口 UserRepository.java

package com.kingbase.testspringdatajpa.dao;

import com.kingbase.testspringdatajpa.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;

@Repository("userRepository")
public interface UserRepository extends JpaRepository<User, Integer> {
    
    // 原生 SQL + 位置参数
    @Query(value = "update test_springdatajpa_2 set username = ?1 where id = ?2", 
           nativeQuery = true)
    @Modifying
    int updateById(String name, String id);
    
    // JPQL 写法，参数命名
    @Query("SELECT u FROM User u WHERE u.username = :username")
    User findUser(@Param("username") String username);
}

继承 JpaRepository 后，基础的 save()、findById()、deleteById() 都不用写，框架自动实现。

3.3 Service 层

接口 UserService.java：

package com.kingbase.testspringdatajpa.service;

import com.kingbase.testspringdatajpa.entity.User;
import java.util.Iterator;

public interface UserService {
    void insertUser(User user);
    void deleteUser(Integer id);
    int updateUser(User user);
    int updateUserById(String name, String id);
    User selectUserById(Integer id);
    User selectUserByName(String username);
    Iterator<User> selectUserAll(Integer pageNum, Integer pageSize);
}

实现类 UserServiceImpl.java：

package com.kingbase.testspringdatajpa.service.impl;

import com.kingbase.testspringdatajpa.dao.UserRepository;
import com.kingbase.testspringdatajpa.entity.User;
import com.kingbase.testspringdatajpa.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.util.Iterator;
import java.util.Optional;

@Service
@Transactional
public class UserServiceImpl implements UserService {
    
    private final UserRepository userRepository;
    
    @Autowired
    public UserServiceImpl(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
    
    @Override
    public void insertUser(User user) {
        userRepository.save(user);
    }
    
    @Override
    public void deleteUser(Integer id) {
        if (!userRepository.existsById(id)) {
            return;
        }
        userRepository.deleteById(id);
    }
    
    @Override
    public int updateUser(User user) {
        userRepository.save(user);
        return 1;
    }
    
    @Override
    public int updateUserById(String name, String id) {
        return userRepository.updateById(name, id);
    }
    
    @Override
    public User selectUserById(Integer id) {
        Optional<User> optional = userRepository.findById(id);
        return optional.orElse(null);
    }
    
    @Override
    public User selectUserByName(String username) {
        return userRepository.findUser(username);
    }
    
    @Override
    public Iterator<User> selectUserAll(Integer pageNum, Integer pageSize) {
        Sort sort = Sort.by(Sort.Direction.ASC, "id");
        Pageable pageable = PageRequest.of(pageNum, pageSize, sort);
        Page<User> users = userRepository.findAll(pageable);
        return users.iterator();
    }
}

@Transactional 确保数据库操作在同一事务中执行。

3.4 启动类

package com.kingbase.testspringdatajpa;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class TestSpringDataJpaApplication {
    public static void main(String[] args) {
        SpringApplication.run(TestSpringDataJpaApplication.class, args);
    }
}

四、测试验证

package com.kingbase.testspringdatajpa;

import com.kingbase.testspringdatajpa.entity.User;
import com.kingbase.testspringdatajpa.service.UserService;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import java.util.Iterator;

@SpringBootTest
public class TestSpringDataJpaApplicationTests {
    
    @Autowired
    private UserService userService;
    
    @Test
    public void contextLoads() {
        // 1. 插入 10 条数据
        for (int i = 1; i <= 10; i++) {
            userService.insertUser(new User(i, "insert" + i));
        }
        
        // 2. 删除 id=1
        userService.deleteUser(1);
        
        // 3. 更新 id=2，改名为 update
        userService.updateUser(new User(2, "update"));
        
        // 4. 按 ID 查询
        User user = userService.selectUserById(2);
        System.out.println("user = " + user);
        
        // 5. 按用户名查询
        User userByName = userService.selectUserByName("insert");
        System.out.println("userByName = " + userByName);
        
        // 6. 分页查询（第 1 页，每页 5 条）
        Iterator<User> userIterator = userService.selectUserAll(0, 5);
        userIterator.forEachRemaining(System.out::println);
    }
}

运行结果：

user = User{id=2, username='update'}
userByName = null
User{id=1, username='insert1'}
User{id=2, username='update'}
User{id=3, username='insert3'}
User{id=4, username='insert4'}
User{id=5, username='insert5'}

数据删掉了 id=1，更新了 id=2，分页正常返回了前 5 条。selectUserByName("insert") 返回 null 因为 id=1 被删了，剩下的用户名带数字后缀，精确匹配查不到，符合预期。

控制台还打印了 Hibernate 生成的 SQL，可以清楚地看到框架在背后的工作。

五、JPA 和 MyBatis 怎么选

两种方式都接入了金仓，顺便做个对比：

维度	Spring Data JPA	MyBatis
代码量	少（基础 CRUD 不用写）	多（接口 + XML + Service）
灵活性	一般	高（SQL 完全手写控制）
复杂查询	JPQL 有点绕	XML 里写原生 SQL
分页	内置支持，一行代码	需要插件或手写
学习成本	高（JPA 概念多）	低（会 SQL 就行）
性能调优	Hibernate 生成 SQL 不好控	SQL 完全掌控

建议：单表 CRUD 为主的项目，JPA 能省很多代码；查询复杂、需要精细控制 SQL 的，MyBatis 更合适。

顺便说一句，金仓对 JPA 的方言支持比较到位，Kingbase8Dialect 能正确处理分页、序列等特性，用起来基本不用操心方言适配的问题。

六、常见问题

Hibernate 不认识金仓方言：检查 database-platform 配置是否正确。老版本 Hibernate 可能没有内置金仓方言，需要升级版本或手动引入方言包。

表名或字段名大小写问题：实体类中 @Table(name = "test_springdatajpa_2") 保持小写。如果建表时用了双引号大小写敏感，查询会报“表不存在”。建议统一用小写，避免麻烦。

ddl-auto: update 不生效：检查用户有没有建表权限。普通用户可能只有 DML 权限，需要 DBA 授权。

分页查询性能问题：JPA 分页会先执行 count 再执行 limit，大表场景有性能开销。可以改用 @Query 手写分页 SQL 优化。

七、写在最后

从 MySQL 切换到金仓，Spring Data JPA 项目需要改的地方很少：pom.xml 换金仓驱动，application.yml 改数据库 URL，dialect 配成金仓专用的。如果代码里没用数据库特有的方言，基本无缝迁移。

这次体验下来，我对金仓的生态兼容性有了更多信心。如果你的项目以单表 CRUD 为主，不妨试试 JPA，同样能跑得很顺。