Java连接smarterasp.net数据库遇ClassNotFoundException问题求助

问题场景 #

以下是用于连接smarterasp.net上SQL Server数据库的Java代码：

package org.example;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
public class Main {

    private static final String JDBC_URL = "jdbc:sqlserver://SQL5113.site4now.net;databaseName=*********;";
    private static final String JDBC_USER = "*******";
    private static final String JDBC_PASSWORD = "********";
    public static void main(String[] args) {
        try {
            // Load the JDBC driver
            Class.forName("com.microsoft.sqlserver.jdbc.SQLServerDriver");
            Connection connection = DriverManager.getConnection(JDBC_URL, JDBC_USER, JDBC_PASSWORD);
    
            if (connection != null) {
                System.out.println("Connected to the database");
                connection.close();
            }
        } catch (ClassNotFoundException e) {
            System.out.println("Error1: " + e.getMessage());
        } catch (SQLException e) {
            System.out.println("Error2: " + e.getMessage());
        }
    }

}

运行时抛出ClassNotFoundException，完整栈追踪：

java.lang.ClassNotFoundException: com.microsoft.sqlserver.jdbc.SQLServerDriver
    at java.net.URLClassLoader.findClass(URLClassLoader.java:387)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:418)
    at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:355)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:351)
    at java.lang.Class.forName0(Native Method)
    at java.lang.Class.forName(Class.java:264)
    at org.example.Main.main(Main.java:15)

已将JDBC jar包放入libs目录并在build.gradle中添加implementation依赖，但问题仍未解决。

解决步骤 #

1. 确认驱动版本与Java版本兼容 #

SQL Server JDBC驱动（mssql-jdbc）的版本和Java版本存在对应关系，比如：

• mssql-jdbc 12.x 支持 Java 8、11、17、21
• mssql-jdbc 11.x 支持 Java 8-17
• mssql-jdbc 10.x 支持 Java 8-16
  确保下载的驱动版本适配你的Java运行环境，避免因版本不兼容导致类加载失败。

2. 检查Gradle依赖配置正确性 #

• 如果使用本地libs目录的jar包，确保依赖路径和文件名完全正确，比如：

  implementation files('libs/mssql-jdbc-12.4.2.jre8.jar')
  

  注意替换为你实际的jar文件名，包括完整版本号。
• 更推荐直接使用Maven中央仓库的依赖，避免本地jar包损坏或路径错误问题：

  // 根据Java版本选择对应的jre后缀，比如jre8、jre11
  implementation 'com.microsoft.sqlserver:mssql-jdbc:12.4.2.jre8'
  

3. 验证依赖是否被正确引入 #

• 执行Gradle命令查看依赖树，确认mssql-jdbc已被加载：

  gradle dependencies
  

  在输出中查找compileClasspath或runtimeClasspath下的com.microsoft.sqlserver:mssql-jdbc条目。
• 如果使用IDE（如IntelliJ IDEA），点击Gradle面板的「Refresh all Gradle projects」按钮，重新同步依赖，确保IDE已识别到驱动jar。

4. 移除不必要的显式驱动加载（可选但推荐） #

JDBC 4.0及以上版本（Java 6+）会自动通过META-INF/services/java.sql.Driver文件注册驱动，无需显式调用Class.forName("com.microsoft.sqlserver.jdbc.SQLServerDriver")。删除这行代码，既能简化逻辑，也能避免因驱动类名变更导致的问题。

5. 检查运行配置的类路径 #

• IDE运行场景：打开「Run/Debug Configurations」，查看「Classpath」选项，确认mssql-jdbc的jar包已包含在类路径中。
• 命令行运行场景：使用java命令时，需通过-cp参数指定包含驱动jar的类路径，比如：

  java -cp build/libs/your-project.jar:libs/mssql-jdbc-12.4.2.jre8.jar org.example.Main
  

6. 清理Gradle缓存并重新构建 #

如果依赖缓存存在问题，执行以下命令清理缓存并重新构建项目：

gradle clean build --refresh-dependencies

内容的提问来源于stack exchange，提问作者Kael