Spring Boot 接入金仓数据库：配置分层、启动自检与常见错误

JDBC 单文件程序适合验证链路，但真实业务系统大多是 Spring Boot 应用。Spring Boot 接入数据库看起来只是写几行 application.yml，但其实上线后出问题最多的也恰恰是这些配置：URL 写错、账号混用、连接池默认值不合适、环境配置串了、启动时没有做数据库自检。

本文基于 Windows 11 本地开发环境和 CentOS 7.6 数据库服务器，演示一个 Spring Boot 项目如何接入金仓数据库，并把配置拆分成可维护的方式。文中的 kb_app、shop、app_user 和 shop.t_connection_check 沿用第一篇创建好的对象。

文章目录

[Spring Boot 接入金仓数据库：配置分层、启动自检与常见错误](#Spring Boot 接入金仓数据库：配置分层、启动自检与常见错误)
- 一、实验目标
- 二、准备项目依赖
- 三、基础连接配置
- 四、写一个最小查询接口
- 五、增加启动自检
- 六、按环境拆分配置
- [七、不要忽略默认 Schema 问题](#七、不要忽略默认 Schema 问题)
- 八、常见错误排查
- - [1. Failed to configure a DataSource](#1. Failed to configure a DataSource)
  - [2. No suitable driver](#2. No suitable driver)
  - [3. Connection refused](#3. Connection refused)
  - [4. FATAL 或认证失败](#4. FATAL 或认证失败)
  - [5. SQL 运行时报表不存在](#5. SQL 运行时报表不存在)
- 九、上线前建议保留的日志
- 十、小结

一、实验目标

本文完成以下目标：

在 Spring Boot 中配置金仓数据库连接。
使用独立环境配置区分开发、测试、生产。
增加启动自检，应用启动时确认数据库可用。
梳理常见连接错误的排查顺序。

示例环境（表中 IP 仅为示例，使用时替换为自己的服务器地址）：

text 复制代码

Windows 11 本地开发机
    |
    | JDBC
    v
CentOS 7.6 数据库服务器：192.168.10.101:54321
数据库：kb_app
账号：app_user
Schema：shop

二、准备项目依赖

如果驱动已经进入企业内部 Maven 仓库，可以直接按内部坐标引入。还没有的话，可以先把驱动 jar 安装到本地仓库。本文沿用第一篇找到的 kingbase8-9.0.0.jar：

powershell 复制代码

mvn install:install-file `
  -Dfile=D:\Tools\Kingbase\KESV9R2C13\KES\KESRealPro\V009R002C013\Interface\jdbc\kingbase8-9.0.0.jar `
  -DgroupId=com.kingbase `
  -DartifactId=kingbase8 `
  -Dversion=9.0.0 `
  -Dpackaging=jar

pom.xml 中引入：

xml 复制代码

<dependency>
    <groupId>com.kingbase</groupId>
    <artifactId>kingbase8</artifactId>
    <version>9.0.0</version>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>

如果你的项目使用 MyBatis、JPA 或其他数据访问框架，底层其实仍然离不开 DataSource 和 JDBC 连接，所以本文的配置思路依然适用。

三、基础连接配置

在 application-dev.yml 中配置开发环境连接：

yaml 复制代码

spring:
  datasource:
    url: jdbc:kingbase8://192.168.10.101:54321/kb_app
    username: app_user
    password: App_user_123
    driver-class-name: com.kingbase8.Driver

几个注意点：

url 中的 IP 是 CentOS 7.6 数据库服务器地址。
本文使用的 kingbase8-9.0.0.jar 驱动类为 com.kingbase8.Driver；如果后续换了驱动包，以实际驱动说明为准。
不要在生产配置中明文写密码，后面要交给环境变量、配置中心或密钥管理工具。

启动时指定开发配置：

powershell 复制代码

mvn spring-boot:run -Dspring-boot.run.profiles=dev

打包后运行：

powershell 复制代码

java -jar kb-app-demo.jar --spring.profiles.active=dev

四、写一个最小查询接口

为了验证应用真的能访问数据库，可以写一个简单的 Repository：

java 复制代码

import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Repository;

@Repository
public class ConnectionCheckRepository {

    private final JdbcTemplate jdbcTemplate;

    public ConnectionCheckRepository(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    public String findCheckName(Integer id) {
        return jdbcTemplate.queryForObject(
                "select check_name from shop.t_connection_check where id = ?",
                String.class,
                id
        );
    }
}

再写一个 Controller：

java 复制代码

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ConnectionCheckController {

    private final ConnectionCheckRepository repository;

    public ConnectionCheckController(ConnectionCheckRepository repository) {
        this.repository = repository;
    }

    @GetMapping("/db/check")
    public String check(@RequestParam(defaultValue = "1") Integer id) {
        return repository.findCheckName(id);
    }
}

启动应用后访问：

text 复制代码

http://localhost:8080/db/check?id=1

如果返回 jdbc_check_ready，说明 Spring Boot 已经通过 JDBC 访问到远端金仓数据库了。

五、增加启动自检

很多系统启动时只要端口起来了，就认为服务正常了。但其实如果数据库连接失败，应用即使启动成功，第一笔业务请求也会暴露问题。建议增加启动自检，把风险前置到启动阶段。

java 复制代码

import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;

@Component
public class DatabaseStartupChecker implements ApplicationRunner {

    private final JdbcTemplate jdbcTemplate;

    public DatabaseStartupChecker(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    @Override
    public void run(ApplicationArguments args) {
        String result = jdbcTemplate.queryForObject(
                "select current_database() || ',' || current_user",
                String.class
        );
        System.out.println("database startup check: " + result);
    }
}

这个自检不需要复杂 SQL，只要能拿到当前数据库名和用户名就够了。生产环境中建议把输出交给日志框架，自检失败时让应用直接退出，不要带病启动。

六、按环境拆分配置

不要把所有环境的连接串堆在一个文件里。推荐这样拆：

text 复制代码

application.yml
application-dev.yml
application-test.yml
application-prod.yml

application.yml 只保留公共配置：

yaml 复制代码

spring:
  application:
    name: kb-app-demo

application-dev.yml：

yaml 复制代码

spring:
  datasource:
    url: jdbc:kingbase8://192.168.10.101:54321/kb_app
    username: app_user
    password: App_user_123

application-prod.yml：

yaml 复制代码

spring:
  datasource:
    url: ${KB_DB_URL}
    username: ${KB_DB_USER}
    password: ${KB_DB_PASSWORD}

生产运行时注入环境变量：

bash 复制代码

export KB_DB_URL='jdbc:kingbase8://10.10.20.15:54321/kb_app'
export KB_DB_USER='app_user'
export KB_DB_PASSWORD='你的生产密码'
java -jar kb-app-demo.jar --spring.profiles.active=prod

这样可以减少生产密码写入代码仓库的风险。

七、不要忽略默认 Schema 问题

很多应用在本地运行没问题，换环境后提示表不存在，实际原因往往仅仅是 SQL 没写 Schema。

推荐在 SQL 中明确写：

sql 复制代码

select * from shop.t_connection_check where id = ?

而不是：

sql 复制代码

select * from t_connection_check where id = ?

如果团队确实要依赖默认 Schema，必须在应用启动时做明确验证，避免不同环境行为不一致。

八、常见错误排查

1. Failed to configure a DataSource

检查是否引入了 JDBC 依赖，是否配置了 spring.datasource.url，是否指定了正确的 profile。

2. No suitable driver

检查 JDBC 驱动是否进入 classpath，连接串前缀是否与驱动匹配。

3. Connection refused

回到环境基线检查。重点看 CentOS 防火墙、数据库监听地址、端口、安全组。

4. FATAL 或认证失败

检查账号密码、目标数据库、访问控制规则。不要直接换高权限账号绕过。

5. SQL 运行时报表不存在

优先检查 Schema。应用 SQL 建议显式写 shop. 前缀。

九、上线前建议保留的日志

应用启动阶段至少输出以下信息：

当前激活的 profile。
数据库连接地址的脱敏信息。
当前数据库名。
当前连接用户。
连接池最大连接数。
启动自检是否通过。

密码绝不能打印到日志里。

十、小结

Spring Boot 接入金仓数据库，关键不只是把 URL 写进去，而是让配置可分层、连接可验证、问题可排查。开发环境先用 Windows 11 到 CentOS 7.6 的链路打通，生产环境再通过 profile、环境变量和启动自检把风险前置到启动阶段。