简介这份资源面向需要通过 Java 直连 Access 数据库mdb 文件的开发者核心是开源免费的 ucanaccess-4.0.4.jar 及其配套依赖可替代 Access_JDBC30.jar规避其单次查询 50 次、每次最多 1000 条的限制采用 JDBC 直连方式无需走 JDBC-ODBC 桥连查询次数与条数均不受约束适合报表导出、批量数据迁移等高频读取场景。压缩包共 16 个文件以 6 个 jar 依赖包和 8 个 txt 说明文档为主另附 bat 与 sh 启动脚本整体约 2.57MBjar 覆盖 ucanaccess 主包及 hsqldb、jackcess、commons 等支撑库txt 则包含版本、版权与许可证信息便于快速核对依赖与合规使用。目前已有 741 人学习下载。包内附有使用说明用法与 Access_JDBC30.jar 大同小异读者可直接参照完成依赖引入与连接配置省去自行拼装依赖和排查版本冲突的时间。1. 一个 jar 包解决 Java 读 Access 的老大难接手一个老系统维护项目时最让人头疼的不是业务逻辑而是数据源——后台还挂着一个.accdb格式的 Access 数据库业务方要求新写的 Java 服务能直接读里面的表。JDBC 标准里压根没有 Access 的驱动ODBC 桥接在 64 位 JVM 上又经常翻车这时候ucanaccess-4.0.4.jar就是那个能救场的开源免费方案。它用纯 Java 实现了 Access 数据库的读写不需要装 Office、不需要配 ODBC 数据源把 jar 丢进 classpath 就能用标准 JDBC 接口操作.mdb和.accdb文件。这篇笔记拆的是这个包怎么落地、参数怎么配、哪些坑必须提前知道适合正在做遗留系统对接、数据迁移或者临时取数的 Java 从业者。2. 先搞清楚 UCanAccess 的驱动链路它凭什么能纯 Java 读 Access很多人第一次用会疑惑Access 是微软的私有格式一个开源 jar 怎么可能不依赖 Office 就读出来答案在于 UCanAccess 并不是自己从零解析文件而是站在两个底层库的肩膀上——Jackcess 负责读写 Access 文件本身HXTT 或内置的 SQL 引擎负责把 SQL 语句翻译成对文件的操作。理解这条链路后面配连接串和排错才不会抓瞎。2.1 驱动分层Jackcess 管文件UCanAccess 管 JDBC 语义拆开 jar 看依赖关系核心是三层。最底层 Jackcess 直接操作.accdb/.mdb的页结构负责表、索引、记录的物理读写中间层是 UCanAccess 自己实现的 SQL 解析与执行引擎把SELECT、INSERT、JOIN这些标准 SQL 映射到 Jackcess 的 API 上最上层才是 JDBC 的Driver、Connection、Statement接口。这意味着你写的rs.getString(name)最终会落到 Jackcess 的游标读取上中间没有 ODBC、没有本地库纯 JVM 内完成。这个分层带来一个直接后果UCanAccess 的 SQL 支持是够用但不完整。简单查询、条件过滤、多表关联基本没问题但窗口函数、复杂子查询、部分聚合写法会报语法错误。我一般会在正式接入前先把业务要用的 SQL 逐条在 UCanAccess 上跑一遍而不是假设它和 MySQL 一样全能。2.2 依赖不止一个 jar四个包缺一不可这是新手最容易翻车的地方。ucanaccess-4.0.4.jar单独放进去启动就报NoClassDefFoundError。它运行时依赖另外三个包版本要匹配依赖包作用缺失时的典型报错ucanaccess-4.0.4.jarJDBC 驱动与 SQL 引擎驱动类找不到jackcess-2.1.x.jarAccess 文件物理读写NoClassDefFoundError: com/healthmarketscience/jackcess/Databasecommons-lang-2.6.jar字符串与工具方法NoClassDefFoundError: org/apache/commons/lang/StringUtilscommons-logging-1.1.x.jar日志门面初始化阶段空指针或日志类缺失hsqldb-2.3.x.jar内存 SQL 引擎部分查询需要复杂查询执行时报引擎未初始化提示4.0.4 这个版本对 hsqldb 的依赖在简单查询下可能不触发但只要涉及排序、聚合或子查询就会用到别省这个包。Maven 项目里最省事的做法是直接引net.sf.ucanaccess:ucanaccess:4.0.4它会自动拉齐传递依赖如果是老项目手工管 jar就按上表把五个包一起放进WEB-INF/lib或 classpath。我见过有人只放主 jar调了两小时以为是代码问题其实是依赖没齐——这种坑一次就够记一辈子。2.3 连接串的写法路径、密码、只读三个参数决定成败驱动类名是net.ucanaccess.jdbc.UcanaccessDriver连接 URL 的格式是jdbc:ucanaccess://文件绝对路径后面可以跟分号分隔的参数。最常用的三个参数memoryfalse默认会把整个库加载进内存做 SQL 处理大库要显式关掉或设memorytrue但控制并发readonlytrue只读场景强烈建议加上避免误写和文件锁问题passwordxxx库有密码时传没密码不要传空串直接省略。import java.sql.Connection; import java.sql.DriverManager; import java.sql.ResultSet; import java.sql.Statement; public class AccessReader { public static void main(String[] args) throws Exception { // 驱动类在 4.x 可省略显式加载老容器里建议保留 Class.forName(net.ucanaccess.jdbc.UcanaccessDriver); // 绝对路径 只读 关闭全内存加载适合几十 MB 的库 String url jdbc:ucanaccess:///data/legacy/app.accdb;readonlytrue;memoryfalse; try (Connection conn DriverManager.getConnection(url); Statement stmt conn.createStatement(); ResultSet rs stmt.executeQuery(SELECT id, name FROM t_user WHERE status 1)) { while (rs.next()) { System.out.println(rs.getInt(id) \t rs.getString(name)); } } } }这段代码的逻辑很直白加载驱动、建连接、执行查询、遍历结果集。参数上要注意readonlytrue会让写操作直接抛异常这是保护不是 bugmemoryfalse在数据量大时能降内存但复杂 SQL 会退化成临时文件处理速度会慢一些。路径必须是绝对路径Windows 下写成jdbc:ucanaccess:///D:/data/app.accdb这种形式反斜杠要换成正斜杠否则解析会出问题。3. 把 jar 接进项目三种落地方式与验证步骤知道原理之后真正落地时项目形态不一样接法也不一样。有人是 Maven 新项目有人是丢 jar 的老 Web 工程还有人是临时写个脚本取数。这一章按这三种场景给可抄的步骤每种都附验证方法确保接完能跑通而不是看起来配好了。3.1 Maven 项目一行依赖加一个仓库配置UCanAccess 在中央仓库有坐标正常情况直接引就行dependency groupIdnet.sf.ucanaccess/groupId artifactIducanaccess/artifactId version4.0.4/version /dependency如果公司内网镜像里没有这个包或者拉下来依赖不全就补一个仓库声明或者干脆走 system scope 把本地 jar 引进来不推荐但老项目常见dependency groupIdnet.sf.ucanaccess/groupId artifactIducanaccess/artifactId version4.0.4/version scopesystem/scope systemPath${project.basedir}/lib/ucanaccess-4.0.4.jar/systemPath /dependency用 system scope 时打包插件默认不会把 jar 打进 fat jar需要在maven-assembly-plugin或spring-boot-maven-plugin里额外配置includeSystemScope否则本地跑得好好的一上服务器就ClassNotFoundException。这个细节坑过不少人血泪经验是能用中央仓库坐标就别用 system scope。验证方式写一个main方法跑 2.3 那段代码能打印出数据就说明依赖链完整。如果报NoClassDefFoundError按 2.2 的表逐个补包。3.2 传统 Web 工程jar 放对位置驱动注册别漏没有 Maven 的工程把五个 jar 全部拷到WEB-INF/lib下然后确认两件事一是容器启动时能扫描到这些 jar二是驱动被正确注册。Tomcat 下常见的问题是驱动类加载了但DriverManager找不到原因是驱动注册发生在错误的 ClassLoader 里。稳妥做法是在应用初始化时手动注册一次import java.sql.Driver; import java.sql.DriverManager; import net.ucanaccess.jdbc.UcanaccessDriver; public class AccessDriverInitializer { static { try { // 显式 new 一个实例并注册绕开 SPI 在容器里的加载问题 Driver driver new UcanaccessDriver(); DriverManager.registerDriver(driver); } catch (Exception e) { throw new RuntimeException(Access 驱动注册失败, e); } } }这段静态块在类首次加载时执行把驱动实例直接注册进DriverManager不依赖META-INF/services的 SPI 机制。参数上没有可调的关键是这个类要在任何取连接代码之前被加载——可以放在 Servlet 的init里也可以配成 Spring 的init-method。验证方式在容器里打一条日志输出DriverManager.getDrivers()的枚举能看到UcanaccessDriver就说明注册成功。3.3 临时取数脚本单文件跑通的最小闭环有时候只是要把 Access 里的几张表导成 CSV不值得建工程。这时候用java -cp直接跑最省事# 把五个 jar 放同一目录编译后直接运行 javac -cp lib/* AccessExport.java java -cp lib/*:. AccessExport /data/app.accdb t_user out.csvAccessExport里读参数、拼连接串、遍历结果集写文件即可。注意-cp里 Windows 用分号;分隔Linux/Mac 用冒号:lib/*的通配符在 Java 6 以后才支持老环境要逐个列全。这种脚本方式适合一次性迁移不适合长期跑因为没连接池、没异常重试库文件被占用时直接失败。验证方式跑完检查 CSV 行数和 Access 里SELECT COUNT(*)的结果是否一致差几行通常是编码或空值处理的问题。4. 避坑排查五个真实翻车现场与解法这个包用起来门槛不高但坑集中在文件锁、编码、SQL 兼容性和大库性能上。下面五条都是我在实际项目里踩过或见别人踩过的按现象 → 原因 → 解决记下来遇到时能少走弯路。4.1 现象报 file is already in use 或 unable to open database原因Access 文件被 Office 进程或其他 JVM 占用UCanAccess 默认以独占方式打开同一文件不能多连接并发写。解决只读场景加readonlytrue并确保没有别的进程开着这个文件需要并发读时把库文件复制一份到临时目录再读别直接怼原文件。生产环境我一般会约定Access 文件只允许一个服务读从部署层面规避。4.2 现象中文全部变成乱码或问号原因Access 的文本字段有字符集信息但 UCanAccess 在某些版本下对非 UTF-8 的库处理不一致尤其是老.mdb文件。解决连接串里加charSetUTF-8试不行就在读取时用new String(rs.getBytes(col), GBK)手动转写入时反过来。根治办法是迁移前先用 Access 本身把库另存为 UTF-8 兼容格式但老库往往动不了只能代码层兜。4.3 现象简单查询正常带 ORDER BY 或 GROUP BY 就报 SQL 语法错误原因这类查询会走 hsqldb 内存引擎SQL 方言和标准有差异比如对NULLS LAST、某些聚合别名不支持。解决先确认 hsqldb 依赖在不在在的话把 SQL 改写成引擎能认的形式比如排序放到 Java 层做或者拆成两步查询。我的习惯是复杂统计不在 Access 上做先把原始表拉出来再在应用层算。4.4 现象几十万行的表查询极慢甚至 OOM原因默认memorytrue会把整库或整表加载进内存大库直接撑爆堆。解决连接串加memoryfalse同时给 JVM 加-Xmx留足余量查询务必带WHERE条件并setMaxRows限制返回量别SELECT *全表拉。数据量再大就该考虑一次性迁移到正式数据库而不是长期用 UCanAccess 顶着。4.5 现象写入后数据丢了或读不到刚写的内容原因UCanAccess 的写入有缓冲连接没正确关闭时事务没提交或者多个连接同时写导致覆盖。解决写操作放在显式事务里conn.setAutoCommit(false)后手动commit()用完close()确保同一时刻只有一个写连接。只读服务就别开写权限从源头杜绝。5. 进阶用连接池和批量迁移把 Access 数据安全搬出来单次查询用DriverManager够了但只要服务要长期跑、并发取数就得考虑连接管理。UCanAccess 的连接创建成本不低要打开文件、初始化引擎频繁开关会拖慢响应。常见做法是套一层连接池但要注意它和普通数据库连接池的差异——Access 文件锁决定了池大小不能大一般 2 到 4 个连接就够再多只会互相等锁。下面是一个基于简单对象池的写法控制最大连接数并复用import java.sql.Connection; import java.sql.DriverManager; import java.util.concurrent.ArrayBlockingQueue; import java.util.concurrent.BlockingQueue; public class AccessConnectionPool { private final BlockingQueueConnection pool; private final String url; public AccessConnectionPool(String url, int size) throws Exception { this.url url; this.pool new ArrayBlockingQueue(size); for (int i 0; i size; i) { // 预热连接避免首次请求抖动 pool.offer(DriverManager.getConnection(url)); } } public Connection borrow() throws InterruptedException { return pool.take(); // 池空时阻塞天然限流 } public void release(Connection conn) { try { if (conn ! null !conn.isClosed()) { pool.offer(conn); // 归还而非关闭 } } catch (Exception ignored) { } } }这段代码的关键参数是size设成 2 到 4 之间别照搬 MySQL 的 10 或 20borrow()用take()阻塞取池满时自动排队避免无限建连接把文件锁死。release()里判断isClosed()是防止归还已失效连接实际项目里还应该加一个健康检查取出来先isValid(1)验一下。批量迁移的场景我一般分三步走先用只读连接把每张表的COUNT(*)和字段结构导出来做对照表再按主键分页拉数据WHERE id BETWEEN ? AND ?每批 5000 行写目标库最后跑一遍行数和关键字段的校验 SQL。分页而不是全量拉是为了避免大表把内存打满这个习惯从那以后我每次做数据迁移都强制走一遍没再出过 OOM。注意迁移脚本一定要在库文件的副本上跑别直接操作生产 Access 文件一旦中途失败原文件可能处于不一致状态。还有一个容易被忽略的点是字段类型映射。Access 的YESNO字段在 UCanAccess 里读出来是BooleanMEMO是String但可能超长DATETIME有时带毫秒有时不带。迁移前用ResultSetMetaData把每列的类型和精度打出来和目标库字段对齐比事后修数据省事得多。希望这些细节能帮到你少踩几个我已经踩过的坑。本文还有配套的精品资源点击获取