Doma框架常见问题排查：编译期SQL校验与工程实践

接手一个用Doma框架维护的存量项目时最先撞上的往往不是业务逻辑而是满屏的编译期报错SQL文件找不到、绑定变量对不上、生成的DAO实现类飘红。Doma这套Java数据库访问框架的思路很特别它把SQL从Java代码里彻底抽出来放进独立的SQL文件再靠注解处理器在编译阶段就把SQL和方法签名对齐等于把很多原本要跑到运行期才暴露的问题提前到了构建期。这个设计对喜欢把SQL攥在自己手里的团队非常友好但代价是项目结构、编译配置、IDE联动都得按它的规矩来一步没踩对就是一连串的为什么编译不过。这篇内容整理了我在多个项目里反复遇到的Doma常见问题从环境搭建、SQL文件路径、实体映射、动态SQL到事务和批量处理每个问题都给出现象、原因和可复现的处理方式适合刚接手Doma项目的新人也适合用了两三年但一直没系统梳理过踩坑点的老手。1. Doma框架的定位与核心设计再认识1.1 为什么选Doma编译期SQL校验的取舍很多人第一次接触Doma会拿它和MyBatis、JPA做对比。我的理解是Doma走的是SQL完全可控 编译期强校验这条中间路线。MyBatis把SQL写在XML或注解里灵活但拼写错误、参数名不匹配往往要等到运行时才报错JPA把SQL藏起来开发效率高但对复杂查询的控制力弱。Doma的做法是SQL写在独立的.sql文件里DAO接口用注解声明方法注解处理器在编译时读取SQL文件逐条检查绑定变量是否和方法参数对得上、返回类型是否能映射到结果集。这就意味着一个拼错的列别名、一个少写的#{}在mvn compile阶段就会失败而不是等到测试环境跑接口时才炸。这个取舍带来的好处很直接SQL review变得可行代码评审时能直接看.sql文件重构方法参数名时编译器会逼着你同步改SQL团队里不熟悉ORM黑盒的人也能一眼看懂数据访问层在干什么。代价同样明显构建流程多了一步注解处理IDE必须正确开启注解处理器SQL文件的位置和命名有硬性约定任何一环没配好报错信息往往不够直白。我在实际项目里见过最典型的情况是本地Windows开发一切正常推到Linux构建机就报SQL文件找不到原因仅仅是大写字母的文件名在大小写敏感的机器上对不上。所以选Doma之前要想清楚一件事团队愿不愿意为SQL可控付出构建配置上的学习成本。如果项目里复杂查询多、DBA要求SQL必须可审计Doma很合适如果项目以简单CRUD为主、追求开箱即用JPA或MyBatis可能更省心。这不是框架优劣问题是团队工作方式的匹配问题。1.2 注解处理器的工作机制与项目结构约束Doma的核心机制是Java的注解处理器Annotation Processor。你在DAO接口上标Dao在方法上标Select、Insert这些注解编译时doma-processor会扫描这些接口生成一个名为XxxDaoImpl的实现类同时读取对应的SQL文件做校验。生成的实现类默认落在target/generated-sources/annotations目录下和手写代码一起参与编译。理解这一点很关键因为后面遇到的找不到DaoImpl改动SQL不生效IDE飘红但命令行能编译这些问题根源几乎都和注解处理器的执行时机或输出目录有关。项目结构上有几个硬约束必须记住。第一DAO接口必须是接口而不是抽象类方法返回值、参数类型要符合Doma的约定。第二SQL文件的默认位置是和DAO接口相同的包路径下文件名格式为DAO接口简单名_方法名.sql比如com.example.dao.EmployeeDao的selectById方法对应com/example/dao/EmployeeDao_selectById.sql。第三实体类用Entity标注字段访问还是属性访问要统一默认是字段访问这意味着实体不一定需要getter/setter但需要无参构造。第四Config实现类要通过ServiceLoader机制注册否则运行时会抛配置找不到的异常。这些约束单看都不难组合在一起就容易出问题。比如多模块项目里DAO接口在dao模块SQL文件却被打包进了resources模块编译期处理器在dao模块的classpath里找不到SQL文件直接报错。再比如实体用了Lombok的Data字段访问模式下没问题但一旦项目里有人切到属性访问Lombok生成的getter命名和Doma预期的属性名对不上映射就静默失败。我在一个项目里就吃过这个亏实体字段叫userName数据库列叫user_name默认驼峰转下划线本来能对上但有人加了Accessors(chain true)属性访问模式下Doma拿到的属性名带了链式返回类型的影响映射结果直接为null排查了半天才定位到访问模式。1.3 版本与运行环境的对应关系Doma 2.x是目前主流版本基于javax命名空间JDK 8及以上都能跑。如果项目要迁移到Jakarta EE 9需要留意Doma对应的适配版本包名从javax切到jakarta不是改个依赖版本就完事注解处理器的行为、Spring Boot starter的版本都要一起对齐。下面这张表是我整理的环境对应关系实际选版本时建议先对照一遍避免依赖冲突。项目要素常见选择注意事项Doma版本2.5x系列2.x基于javax迁移Jakarta需确认适配版本JDK8 / 11 / 1717下注解处理器需确认处理器兼容性构建工具Maven 3.6 / Gradle 7注解处理器配置方式不同Spring Boot集成doma-spring-boot-starter版本要与Spring Boot主版本匹配数据库方言MysqlDialect / PostgresDialect / OracleDialect方言决定分页、引号、类型映射行为连接池HikariCPDoma本身不管连接池交给数据源这张表看着简单但每一项错配都可能引发连锁问题。我见过最隐蔽的一次是方言选错项目连的是PostgreSQLConfig里却写了MysqlDialect简单的增删改查完全正常一到分页查询就报语法错误因为两种方言生成分页SQL的方式不同。这类问题不会在启动时报错只会在特定SQL上暴露排查成本很高。2. 环境搭建与依赖配置的常见坑2.1 依赖版本与注解处理器配置Maven项目里Doma需要两个依赖运行时依赖doma和编译期处理器doma-processor。很多人只加了前者结果编译时根本不生成DaoImpl运行时抛ClassNotFoundException。正确做法是在maven-compiler-plugin的annotationProcessorPaths里显式声明处理器而不是简单地把doma-processor加进普通依赖。普通依赖的方式在某些Maven版本和IDE组合下会失效尤其是多模块项目。plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId configuration annotationProcessorPaths path groupIdorg.seasar.doma/groupId artifactIddoma-processor/artifactId version2.53.0/version /path /annotationProcessorPaths compilerArgs arg-parameters/arg /compilerArgs /configuration /plugin上面这段配置里有两个关键点。第一annotationProcessorPaths保证处理器只在编译期生效不会被打进最终产物。第二-parameters编译参数必须加否则方法参数名在字节码里会丢失Doma在处理SQL绑定变量时拿不到参数名轻则报错重则生成的代码里参数绑定错位。这个参数在Java 8之后默认是关闭的很多人不知道要开结果就是本地idea能跑、命令行编译失败的怪现象。Gradle项目的写法不同用annotationProcessor配置dependencies { implementation org.seasar.doma:doma-core:2.53.0 annotationProcessor org.seasar.doma:doma-processor:2.53.0 }Gradle里同样要确保-parameters开启可以在compileJava任务里加options.compilerArgs -parameters。我建议把这段配置写进构建脚本的公共部分而不是靠每个开发者本地配否则新人拉代码第一件事就是编译失败。注意doma-processor的版本必须和doma-core保持一致版本错配时处理器生成的代码可能引用不存在的方法报错信息通常指向生成类而不是配置本身很容易误判。2.2 编译期生成目录与IDE联动问题注解处理器生成的代码默认在target/generated-sources/annotationsMaven会自动把这个目录加进编译路径但IDE不一定认。IntelliJ IDEA里常见的情况是命令行mvn compile成功IDE里XxxDaoImpl一片飘红。解决方式有两种一是开启IDE的注解处理设置在Settings Build Compiler Annotation Processors里勾选启用并确认处理器路径二是直接执行一次mvn clean compile后重新导入Maven项目让IDE识别生成目录。我个人的习惯是每次拉新项目先跑一遍命令行编译确认生成目录有内容再让IDE重新索引比在IDE里瞎点设置高效得多。另一个高频问题是改了SQL文件不生效。Doma的SQL文件是在编译期被读取和校验的但运行期加载的是classpath里的副本。如果你只改了源码目录下的.sql文件而没有重新编译或者构建工具没有把.sql当作资源复制到target/classes运行时就还是旧SQL。Maven默认只把src/main/resources下的文件当资源如果SQL文件和DAO接口一起放在src/main/java下需要在pom.xml里配置resources包含**/*.sql。这个坑我在三个项目里都遇到过表现是SQL明明改了日志里打印的还是旧的查半天以为是缓存其实是资源没复制。build resources resource directorysrc/main/java/directory includes include**/*.sql/include /includes /resource resource directorysrc/main/resources/directory /resource /resources /build上面这段配置的意思是把src/main/java下的.sql文件也当作资源复制到输出目录同时保留src/main/resources的正常资源处理。配置完记得mvn clean一次避免旧的class文件残留造成误判。2.3 多模块项目中的处理器传递多模块项目是Doma配置问题的重灾区。假设项目分common、dao、web三个模块实体在commonDAO接口和SQL在daoweb依赖dao。常见错误是把注解处理器配置写在父POM的pluginManagement里以为子模块会自动继承实际上annotationProcessorPaths不会自动传递每个需要生成代码的模块都得单独声明。更隐蔽的情况是dao模块依赖common模块的实体但common模块编译时没有开启注解处理实体上的Entity、Column没有被处理到了dao模块编译时处理器读取实体元数据就可能缺信息。我的处理原则是哪个模块有Dao接口哪个模块就配注解处理器实体模块如果只放POJO不需要配处理器但要确保实体类本身编译正常。跨模块的SQL文件路径问题也要注意SQL文件必须和DAO接口在同一个模块的相同包路径下不能分散到别的模块的资源目录里否则编译期找不到。曾经有个项目为了资源统一管理把所有SQL文件集中放到web模块的resources/sql下结果dao模块编译时全部报SQL文件缺失最后只能把SQL文件挪回dao模块。3. SQL文件与注解处理器的高频报错排查3.1 SQL文件路径与命名约定SQL文件找不到是Doma最常见的一类报错。表现通常是编译失败提示某个DAO方法对应的SQL文件不存在。根因几乎都出在路径或命名上我总结了几条排查顺序。第一确认SQL文件和DAO接口在同一个包下目录结构要和包名完全一致。第二确认文件名格式是接口简单名_方法名.sql下划线不能少大小写要和接口名、方法名严格一致。第三确认构建时.sql被复制到了输出目录尤其是SQL放在src/main/java下的项目。大小写问题值得单独说。Windows文件系统不区分大小写Linux区分所以EmployeeDao_selectbyid.sql在Windows上可能被当成EmployeeDao_selectById.sql到了Linux构建机就找不到。我现在的习惯是文件名一律用IDE的重命名功能生成不手敲避免大小写笔误。另一个容易忽略的点是方法重载。Doma对方法重载的支持有限两个同名方法如果参数不同SQL文件名相同会冲突通常的做法是改用不同方法名而不是硬扛重载。如果项目确实需要把SQL文件放到非默认位置可以用SqlFile注解显式指定路径。这个注解在Doma 2.1之后提供适合把SQL集中管理在META-INF下的场景。但我不建议一上来就用默认约定能解决大部分问题自定义路径反而增加了路径写错但编译不报错的风险。3.2 注解处理器报错信息逐条解读Doma的报错信息有固定的前缀和编号看懂编号能少走很多弯路。虽然不同版本编号略有差异但大类是稳定的。下面这张表是我根据实际排查经验整理的常见报错方向和对应处理方式。报错方向典型现象排查重点SQL文件缺失编译提示某方法找不到SQL文件包路径、文件名大小写、资源复制配置绑定变量不匹配提示SQL中的变量在方法参数中不存在-parameters是否开启、参数名拼写、Parameter注解返回类型不匹配提示结果集无法映射到返回类型实体字段与列名映射、Column配置、构造函数主键配置错误更新或删除时提示缺少主键实体是否有Id、是否标在正确字段上方言相关错误编译通过但运行时报SQL语法错Config中方言是否与数据库匹配绑定变量不匹配这一类值得展开。Doma的SQL里用/* paramName */#{paramName}或者直接#{paramName}引用方法参数。如果编译时没开-parameters处理器拿不到参数名就会认为SQL里的变量不存在。还有一种情况是参数用了Parameter注解重命名SQL里却还在用原变量名。我的建议是方法参数名和SQL变量名保持完全一致不要玩重命名减少心智负担如果确实需要重命名在参数上标Parameter(newName)并全局搜一遍SQL里的引用。返回类型不匹配通常和实体映射有关。比如SQL查了user_name列实体字段叫userName默认驼峰转下划线能对上但如果实体上标了Accessors(accessType AccessType.PROPERTY)切到属性访问而getter命名不规范映射就会失败。这类问题编译期不一定报运行时才表现为字段为null排查时优先看实体的访问模式和列名注解。3.3 内联SQL与SQL文件的选择Doma允许在Select等注解里直接写sql属性也就是内联SQL适合非常简单的查询。比如按主键查一条记录写内联SQL能省掉一个文件。但我不建议在业务项目里大量用内联SQL原因有三个一是内联SQL在Java字符串里格式化和review都不方便二是复杂SQL拼接可读性差三是团队规范不统一时一半人在文件里写、一半人在注解里写维护成本翻倍。我的做法是超过三行的SQL一律放文件内联只用于极简的场景并且在团队规范里写清楚边界。内联SQL还有一个坑字符串里的#{}和Java的转义容易混。比如SQL里要写\n或者引号Java字符串得转义稍不注意就编译不过。SQL文件没有这个问题写起来更接近原生SQL。所以从长期维护角度SQL文件是更稳妥的选择。4. 实体映射与类型转换的疑难问题4.1 命名策略与列名映射Doma默认的命名策略是驼峰转下划线实体字段userName对应数据库列user_name。这个默认值覆盖了大部分规范建表的场景但现实项目里总有例外有的表用全大写列名有的带业务前缀有的历史遗留用拼音。处理方式是用Column(name 实际列名)逐个覆盖或者在Config里配置全局命名策略。逐个覆盖更可控全局策略改错影响面太大我倾向于前者。Table注解用于指定表名如果实体名和表名不一致就必须标。这里有个细节Table支持catalog和schema属性多schema的数据库里要写清楚否则生成的SQL会缺schema前缀运行时报表不存在。我在一个多租户项目里就遇到过代码里Table(name orders)实际表在tenant_a.orders没配schema导致查询全部失败而且报错信息是数据库层的表不存在很容易误以为是连接配错。主键映射用Id更新和删除依赖它。复合主键就在多个字段上标Id。这里常见的错误是把Id标在了getter上而不是字段上字段访问模式下处理器读不到更新时生成的条件缺主键变成全表更新。这个错误极其危险测试环境数据量小可能没感觉生产环境一次全表更新就是事故。我的习惯是实体一律用字段访问Id紧贴字段声明评审时重点看。4.2 常见类型转换异常与自定义转换器类型转换是Doma使用中第二大类问题。数据库的CHAR(n)定长类型在读取时会补空格如果实体字段是String拿到的值尾部带空格比较和展示都会出问题。处理方式是在SQL里用TRIM或者自定义Domain做清洗。TIMESTAMP和LocalDateTime的映射在新版本JDBC驱动下基本没问题但老驱动可能需要显式注册类型处理器。布尔字段如果数据库用char(1)存Y/NDoma默认的布尔映射对不上需要自定义转换。枚举映射用Enum注解可以指定按序号还是按名称存。按序号存的风险是枚举顺序一变历史数据全错位所以我一般要求按名称存。自定义类型用Domain注解配合ExternalDomain或者实现转换逻辑适合金额、身份证号这类有业务含义的值对象。下面是一个把char(1)的Y/N转成布尔值的简化思路Domain(valueType String.class, factoryMethod of) public class YesNoBoolean { private final String value; private YesNoBoolean(String value) { this.value value; } public static YesNoBoolean of(String value) { return new YesNoBoolean(value); } public String getValue() { return value; } public boolean toBoolean() { return Y.equalsIgnoreCase(value); } }实体字段用这个Domain类型数据库列还是char(1)读写时由Doma调用of和getValue完成转换。这种写法比在业务代码里到处写Y.equals(...)干净得多也把转换逻辑收口到了一处。需要注意的是Domain的factoryMethod必须是静态方法参数类型要和数据库列类型对得上否则运行时报转换失败。提示金额字段不要用double用BigDecimal并配合Column指定精度。Doma不会替你做精度校验数据库列是decimal(10,2)而Java侧传了三位小数时不同数据库的舍入行为不一致容易在测试环境看不出、生产环境对不上账。5. 动态SQL与条件构建的实操要点5.1 动态SQL语法与常见误用Doma的动态SQL用注释语法/*%if condition */ ... /*%end*/、/*%for item : list */ ... /*%end*/和MyBatis的标签风格完全不同。第一次用的人最容易把/*%if*/写成if编译器不报错运行时SQL里原样带着注释条件永远不生效。我在代码评审里见过好几次这种写法表现是条件查询不生效永远查全表排查时看日志里的SQL才发现注释没被解析。动态SQL的if条件里引用的是方法参数名判断null用param ! null判断字符串空值要写param ! null and param ! 。这里有个细节Doma的条件表达式是有限制的不是完整的Java表达式复杂逻辑建议在Java侧算好布尔值再传进来SQL里只做简单判断。比如多条件组合查询可以先在Service层拼一个condition对象SQL里判断对象字段是否为null而不是在SQL里写一长串and。for循环用于IN查询和批量条件。写法是/*%for id : idList */ #{id} /*%if id_has_next */,/*%end*/ /*%end*/注意id_has_next是Doma提供的循环变量用来判断是否还有下一个元素少了它就会多一个逗号导致SQL语法错误。这个错误很常见报错信息指向SQL语法实际根因在循环写法。5.2 条件分支与参数绑定陷阱动态SQL里最容易出安全问题的是${}和#{}的混用。#{}是预编译绑定安全${}是直接字符串拼接有注入风险。Doma里${}一般用于拼接表名、列名这类不能预编译的部分业务参数绝对不能用。我见过有人为了动态排序把前端传来的排序字段直接${}拼进去这就是典型的注入漏洞。正确做法是后端维护一个允许的排序字段白名单前端传枚举值后端映射到固定的列名再拼接。另一个陷阱是if分支里参数绑定的完整性。比如更新语句UPDATE employee SET /*%if name ! null */ name #{name}, /*%end*/ /*%if age ! null */ age #{age}, /*%end*/ updated_at CURRENT_TIMESTAMP WHERE id #{id}如果name和age都为null生成的SQL里SET后面直接跟updated_at语法没问题但如果只有第一个条件成立name #{name},后面的逗号还在也没问题。真正的问题出在最后一项如果最后一个条件分支也带逗号而后面没有其他字段就会生成SET age ?, , updated_at ...这种双逗号。处理方式是把逗号放在字段前面而不是后面或者用/*%if*/包住整个赋值段。这种细节不实测很难发现建议每个动态更新SQL都写单元测试覆盖全部参数为null和只有最后一个参数不为null两种边界。5.3 LIKE查询与特殊字符转义LIKE查询的转义问题在Doma里没有内置处理。用户输入%或_时如果直接拼进LIKE #{keyword}会被当作通配符导致查询结果不符合预期。处理方式有两种一是在SQL里用ESCAPE子句Java侧把%、_、\转义二是在Java侧拼好%keyword%再传参同时做转义。我倾向于后者逻辑集中在Service层SQL保持干净。public String escapeLike(String keyword) { if (keyword null) { return null; } return keyword.replace(\\, \\\\) .replace(%, \\%) .replace(_, \\_); }SQL里写LIKE CONCAT(%, #{keyword}, %) ESCAPE \。这样用户输入的%会被当作普通字符匹配。这个细节在后台管理系统的搜索框里特别重要不处理的话用户搜%会把全表查出来既是性能问题也是体验问题。6. 事务、连接池与批量处理的稳定性问题6.1 事务边界与连接管理Doma本身不管理连接池它只负责从DataSource拿连接、执行SQL、管理事务边界。事务通过TransactionManager控制手动模式下用LocalTransactionManagerSpring集成下用DomaTransactionManager。常见问题是事务边界没包住多条SQL导致部分成功部分失败。比如先插主表再插子表两条SQL分别在不同事务里执行主表成功子表失败就产生脏数据。正确做法是把它们放进同一个TransactionTemplate或者Spring的Transactional方法里。连接泄漏是另一个高频问题。Doma的LocalTransaction如果忘记commit或rollback连接不会归还连接池跑一段时间后连接池耗尽报等待连接超时。我排查过的一次是异常分支里直接return没有走finally里的rollback结果每次异常都泄漏一个连接。现在我的习惯是用try-with-resources或者TransactionTemplate把提交和回滚交给框架手写try-catch-finally容易漏。嵌套事务也要注意。Doma的LocalTransactionManager不支持真正的嵌套事务内层commit会把外层也提交掉容易造成以为回滚了实际提交了的误判。需要嵌套语义时要么用Spring的传播行为控制要么把逻辑合并到一个事务方法里。这一点在复杂业务里必须提前想清楚不能等出问题再改。6.2 批量插入与性能调优批量操作是Doma里坑最多的部分。BatchInsert返回BatchResult而不是直接抛异常。这意味着批量插入时如果某条记录违反唯一约束方法正常返回异常被吞进BatchResult里不检查就以为全部成功。我见过最严重的一次是批量导入十万条数据实际只成功了三万条因为主键冲突的记录被静默跳过业务方直到对账才发现。BatchResultEmployee result employeeDao.batchInsert(employees); if (result.isError()) { RuntimeException e result.getException(); // 记录日志定位是哪条数据、什么原因 throw e; }上面这段是必须写的防御代码。BatchResult还提供getUpdatedCounts()可以拿到每条的成功状态适合需要精确知道哪条失败导入的场景。批量大小也要调不是越大越好。批量太大容易撑爆内存或者触发数据库的包大小限制我一般在500到1000之间做压测找到当前数据库和网络环境下的拐点。Doma的批量大小可以通过注解属性或者Config配置具体看版本配置后务必用真实数据量压一次别拍脑袋。批量插入的自增主键回填也要注意。数据库和驱动支持getGeneratedKeys时Doma会把生成的主键回填到实体里但批量模式下部分驱动行为不一致。如果业务依赖回填的主键做后续关联插入建议先小批量验证确认实体里的主键字段确实被赋值了再放大批量。这个验证花不了几分钟能避免后面一连串的空指针。6.3 乐观锁与并发更新Version注解用于乐观锁更新时自动带上版本号条件影响行数为0时抛乐观锁异常。常见问题是实体忘了标Version或者版本字段类型和数据库对不上比如Java用int数据库用bigint。还有一种情况是更新语句手写了SQL没有带版本条件绕过了乐观锁并发下后写覆盖先写。我的建议是凡是需要并发控制的表实体必须标Version并且更新一律走Doma生成的条件更新不手写绕过。乐观锁异常的处理也要想清楚。捕获后是重试、提示用户还是记录冲突取决于业务。重试要注意次数上限和幂等性不能无限重试。我一般设置最多重试两次超过就返回明确的冲突提示让用户刷新后重试比后台死循环重试更可控。7. 常见异常速查与排查方法论7.1 异常速查表把前面散落的问题汇总成一张速查表方便出问题时快速定位。这张表按现象—可能原因—处理方向组织实际排查时从现象出发逐行对照比从头读文档快得多。现象可能原因处理方向编译报SQL文件找不到路径、文件名大小写、资源未复制核对包路径与命名检查resources配置编译报绑定变量不存在未开-parameters、参数名不一致加编译参数核对SQL变量名运行时DaoImpl找不到注解处理器未生效检查annotationProcessorPaths配置查询结果字段全为null命名策略不匹配、访问模式不一致核对Column与实体访问模式更新影响全表Id缺失或标错位置检查实体主键注解批量插入部分失败无感知未检查BatchResult增加异常检查与日志连接池耗尽事务未提交/回滚导致连接泄漏检查事务边界与异常分支分页SQL语法错误方言配置与数据库不匹配核对Config中的Dialect乐观锁异常频发并发更新同一记录评估重试策略与业务冲突处理表格里的每一行背后都是一类真实问题但排查时不能只盯一行。比如更新影响全表可能是Id缺失也可能是动态SQL的WHERE条件被if吞掉了要结合SQL日志一起看。我习惯在开发环境把SQL日志级别开到最详细每次执行都打印最终SQL和参数很多问题看一眼日志就能定位比断点调试快。7.2 日志配置与排查技巧Doma的SQL日志通过Config里的JdbcLogger和SqlLogType控制。开发环境建议用SqlLogType.FORMATTED打印格式化后的SQL和绑定参数直观生产环境用RAW或者关闭避免日志量过大。日志实现可以接SLF4J把Doma的日志输出到项目统一的日志框架里方便按DAO方法名过滤。public class AppConfig implements Config { Override public SqlLogType getSqlLogType() { return SqlLogType.FORMATTED; } Override public JdbcLogger getJdbcLogger() { return new Slf4jJdbcLogger(); } }排查动态SQL问题时重点看日志里最终生成的SQL。条件没生效、逗号多了、IN列表为空导致语法错误这些在格式化日志里一目了然。另一个技巧是把DAO方法名和业务场景对应起来日志里按方法名搜能快速定位是哪个查询慢、哪个更新影响了异常行数。我还会在关键更新语句执行后打印影响行数和预期对比能在测试阶段就发现条件写漏导致全表更新这类问题。注意生产环境打印完整SQL和参数可能包含敏感信息务必评估脱敏方案或者只在排查问题时临时开启排查完立即关闭。8. 几个让我印象深刻的实操教训第一个教训关于参数名。早期项目里我没加-parameters本地IDE编译正常CI上偶尔失败一直以为是不稳定。后来才发现IDE默认开了参数保留命令行没开两边行为不一致。从那以后构建脚本里的编译参数我都显式写死并且在README里注明不要依赖IDE默认配置新人上手少走弯路。第二个教训关于SQL文件位置。有个项目为了资源集中把SQL文件从src/main/java挪到了src/main/resources/sql同时用SqlFile注解指定路径。看似优雅实际带来两个问题一是路径字符串写错时编译期不报错运行时才找不到二是IDE里从DAO方法跳转到SQL文件的功能失效review效率下降。后来还是挪回了默认位置接受SQL和接口同包的约定换来的是零配置和可跳转。第三个教训关于批量操作的静默失败。那次问题之后我在团队里定了一条规矩所有BatchResult必须检查isError()不检查的代码评审直接打回。这条规矩救过好几次尤其是数据迁移和定时任务场景静默失败比直接报错危险得多。第四个教训关于事务边界。有个定时任务方法上没加事务注解内部两次更新分别提交中间抛异常导致数据不一致。修复方式是在方法入口加事务把两次更新包进同一个事务。这件事让我养成一个习惯凡是写操作超过一条先问自己这两条必须同生共死吗答案是肯定的就加事务不确定就按同生共死处理宁可事务大一点也别留下中间状态。这些教训没有一条是文档里会重点写的但每一条都在实际项目里造成过真实影响。Doma的机制决定了它对配置和约定比较敏感把约定吃透、把边界测到后面用起来其实很稳。我现在接手新项目第一件事是跑一遍编译确认注解处理器正常第二件事是打开SQL日志跑几个典型查询看生成的SQL这两步做完后面八成的问题都能提前发现。