JDBC连接MySQL：macOS正常Windows报no suitable driver found错误

问题描述 #

使用JDBC连接MySQL数据库时抛出no suitable driver found错误，该问题仅在Windows环境出现，macOS环境下连接可正常运行。此前macOS环境也曾触发相同错误，通过Mac系统设置中的MySQL偏好设置面板启动MySQL服务、确认代码中配置的数据库密码正确后，macOS端连接问题已修复。

项目相关代码如下：

主类代码 #

public class Library {
    public static void main(String[] args){
        final String DB_URL="jdbc:mysql://localhost";
        final String USER = "root";
        final String PASS = "root";

        // 建立连接
        try(Connection conn = DriverManager.getConnection(DB_URL, USER, PASS);
            Statement stmt = conn.createStatement();
        ) {
            String sql = "CREATE DATABASE Biblioteca";
            stmt.executeUpdate(sql);
            System.out.println("Database created successfully...");
        } catch (SQLException e) {
            System.out.println(e);
        }

        ConnectionProvider connection=new ConnectionProvider(USER,PASS,"Biblioteca");
        UserTable userTable=new UserTable(connection.getMySQLConnection());
        userTable.createTable("Users");
        AddressTable addressTable=new AddressTable(connection.getMySQLConnection());
        addressTable.createTable("Address");
        AdminTable adminTable=new AdminTable(connection.getMySQLConnection());
        adminTable.createTable("Admin");
    }
}

连接类代码 #

public final class ConnectionProvider {
    private final String username;
    private final String password;
    private final String dbName;

    /**
     * @param username 连接数据库使用的用户名
     * @param password 连接数据库使用的密码
     * @param dbName 要连接的数据库名称
     */
    public ConnectionProvider (final String username, final String password, final String dbName) {
        this.username = username;
        this.password = password;
        this.dbName = dbName;
    }

    /**
     * @return 指向构造方法指定数据库的连接对象
     * @throws IllegalStateException 数据库连接建立失败时抛出
     */
    public Connection getMySQLConnection() {
        final String dbUri = "jdbc:mysql://127.0.0.1/"+dbName;
        try {
            // 通过JDBC DriverManager获取数据库连接
            return DriverManager.getConnection(dbUri, this.username, this.password);
        } catch (final SQLException e) {
            throw new IllegalStateException("Could not establish a connection with db", e);
        }
    }
}

修复步骤 #

no suitable driver found错误的核心原因是JDBC DriverManager没有找到能识别jdbc:mysql://协议前缀的驱动，和之前macOS遇到的服务未启动、密码错误属于完全不同的问题类型，按以下顺序排查即可：

• 优先检查Windows环境下项目的MySQL JDBC驱动依赖配置
  跨系统运行表现不一致，绝大多数情况是macOS环境下项目已经正确引入MySQL Connector/J驱动，但Windows侧打开项目时依赖未正确加载：
  • 如果是Maven/Gradle管理的项目，在Windows侧执行一次依赖刷新，确认mysql-connector-j依赖没有报红、已成功下载到本地仓库
  • 如果是手动导入jar包的普通Java项目，检查驱动jar包是否被正确加入项目构建路径，不要仅把jar包放在项目目录下就直接运行
• 兼容旧版本驱动，显式注册驱动类
  如果使用的是5.x及更早版本的MySQL Connector/J，驱动不会自动向DriverManager注册，需要在第一次调用DriverManager.getConnection()前，添加一行代码强制加载驱动类：

  // 8.x及以上版本驱动使用该类名
  Class.forName("com.mysql.cj.jdbc.Driver");
  // 5.x版本替换为 Class.forName("com.mysql.jdbc.Driver");
  

• 补全JDBC连接URL的标准参数
  当前使用的连接URL没有指定端口、时区等必要参数，部分版本的驱动在Windows环境下解析URL时，会因为参数缺失判定URL格式不匹配，建议修改为标准格式：

  // 主类中DB_URL修改为
  final String DB_URL="jdbc:mysql://localhost:3306/?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true";
  // ConnectionProvider类中dbUri修改为
  final String dbUri = "jdbc:mysql://127.0.0.1:3306/"+dbName+"?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true";
  

• 顺带检查Windows侧MySQL服务状态
  打开Windows服务面板，找到MySQL服务确认处于运行状态，同时检查3306端口没有被其他程序占用。

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