一、为什么谈谈Mapper代理就不得不提“规范”
在MyBatis里，只要写一个接口，再配一段XML，框架就能在运行时生成实现类，把SQL执行结果映射成Java对象——这种“代理魔法”曾让无数开发者感叹：终于不用写Impl了。然而魔法一旦落入生产环境，就会暴露一系列“不那么魔幻”的问题：
在MyBatis里，只要写一个接口，再配一段XML，框架就能在运行时生成实现类，把SQL执行结果映射成Java对象——这种“代理魔法”曾让无数开发者感叹：终于不用写Impl了。然而魔法一旦落入生产环境，就会暴露一系列“不那么魔幻”的问题：
-
同名方法被重复扫描，启动阶段报“绑定异常”，日志却只说“not found”
-
参数解析错误，看起来是字符串，实际被当成对象，最终生成一条带问号却缺失参数的SQL
-
批量插入性能陡降，根源是动态代理每次都新建解析器，缓存形同虚设
-
新人照猫画虎，把数据库字段直接暴露在方法签名，一旦列名改动，接口与实现“两边地震”
规范的价值就在于：把“踩坑经验”沉淀为“集体共识”，让团队在任何时期打开仓库，都能像阅读母语一样顺畅。
二、目录与分包：先给Mapper找个“家”
-
模块级隔离
按照“一个业务域一个包”而非“一个表一个包”来组织，当订单域需要同时操作order_header、order_item、inventory三张表时，把三个XML放在同一包下，减少“跨目录引用”带来的相对路径错误。 -
文件命名
接口名与XML名保持完全一致，大小写敏感的操作系统会在编译期就暴露拼写错误；若出现重名，用“业务动作”做后缀区分：OrderMapper、OrderExportMapper，而非“OrderMapperNew”“OrderMapperV2”这种时间戳式命名。 -
资源路径
XML放在resources目录，包路径与Java接口对齐，确保打包后框架能用“类名.class.getName()”直接定位资源；切忌把XML塞进java源码根目录，再靠build插件强行复制，结果导致IDE能跳转，运行时却“找不到绑定”。 -
多租户拆分
若同一套服务需要连接不同库，先考虑“包级命名空间+独立SqlSessionFactory”，而非“一个Mapper里写两套SQL”，否则动态数据源切换时，缓存键会相互覆盖，出现“A库读B库缓存”的幽灵数据。
三、接口命名：让方法名成为“自解释文档”
-
动词在前
selectOne、insertBatch、updateStatus、deleteById，一眼可见操作类型，配合日志切面时能直接输出方法名，方便定位慢SQL。 -
主键结尾
selectById、selectByOrderNo、selectByUserIdAndStatus，把“查询依据”放在最后，避免方法签名膨胀后无法肉眼区分。 -
布尔返回值
若方法仅判断“是否存在”，命名成existsById而非selectCountById，语义更精准；同时可在XML里用select 1 limit 1，减少网络传输。 -
避免“Map作参数”泛化
Map<String,Object>作为查询条件，看似灵活，实则把编译期检查推迟到运行期；维护者只能翻XML才能知道该传哪些key，违背“Fail Fast”原则。推荐用“查询对象”封装，哪怕只有两三个字段，也能享受类型安全和IDE重构红利。
四、参数设计：把“边界”搬到编译器眼前
-
单值参数
当查询条件仅一个字段，直接传基本类型；框架内部会走“基本类型→包装类型→JdbcType”的短路，节省TypeHandler解析开销。 -
多值参数
若出现IN语句，用List而非数组，避免“空数组”被MyBatis误判为null；同时把“空List”在Service层提前拦截，给出业务语义异常，而不是“SQL语法错误”。 -
分页一致性
分页查询统一封装Page对象，内含pageNum、pageSize、orderBy、isCount，并在插件里强制追加“隐式排序”——主键倒序；防止“第1页与第2页出现重复数据”引发用户投诉。 -
枚举映射
数据库用tinyint，代码用Enum，务必提供全局TypeHandler，并在Handler内部校验“非法值”直接抛运行时异常，禁止用“默认值”吞掉未知枚举，否则新增枚举项后，老数据会“悄无声息”被转换，造成逻辑黑洞。
五、缓存与一级缓存：别把“性能良药”吃成“毒药”
-
本地缓存
SqlSession级别的一级缓存默认开启，但生命周期绑定会话；若用“每次请求新开会话”模式，则一级缓存永远失效，看似“缓存”实则“累赘”。
规范：读多写少且数据量小的表，在Service层显式开启“同一线程复用SqlSession”，并在finally块关闭，既利用缓存，又避免连接泄漏。 -
二级缓存
Mapper级二级缓存跨SqlSession，但默认不开启；一旦开启，必须评估“更新频率”与“一致性容忍度”。
原则：
-
配置flushInterval，让缓存最多滞后N秒
-
所有增删改语句统一加useCache=false，防止“更新后缓存未清”
-
缓存对象必须实现序列化，否则深拷贝会失败，但序列化又带来CPU与大小开销；若实体里含大字段，用DTO专门承载缓存
-
自定义缓存
当业务需要“分布式缓存”时，优先在Service层手动调用缓存SDK，而非直接替换MyBatis的Cache接口；避免“缓存集群抖动”导致Mapper级缓存全部阻塞，进而拖垮数据库连接池。
六、事务边界：让“代理”与“事务”同频
-
事务粒度
Mapper代理本身不含事务，需要Service层@Transactional标注；
规范：
-
查询方法禁用事务，只读标志设为true，减少获取连接时间
-
多表更新放在同一Service方法，避免“同业务不同事务”造成中间状态被其他线程读到
-
嵌套与传播
若出现“ServiceA调用ServiceB”且都需要写库，统一用REQUIRED，禁止REQUIRES_NEW；新事务会占用新连接，高并发时连接池被“竖着切”成两段，吞吐量骤降。 -
回滚策略
默认只在运行时异常回滚；若业务里主动抛受检异常，需要在catch块里手动setRollbackOnly，防止“部分成功”污染数据。 -
超时与重试
事务超时时间设定要大于“最慢SQL+网络抖动”之和；否则出现“SQL还在执行，事务已被标记回滚”的怪异异常，日志里却找不到任何SQL错误。
七、测试与可观测性：给Mapper戴“听诊器”
-
单元测试
用内存数据库做BaseTest，每个测试方法结束回滚事务，保证“测试零残留”；同时加@Sql注解初始化数据，避免“测试A插入的ID影响测试B”。 -
日志级别
开发环境打开DEBUG，观察“Preparing→Parameters→Updates”三行是否连贯；生产环境只留INFO，防止大对象toString把磁盘打满。 -
慢SQL治理
通过“代理包装+切面”统一记录耗时，超过1秒自动输出到独立文件；每周 review 一次，把“索引缺失”与“N+1查询”在上线前消灭。 -
链路追踪
把SqlSessionId与TraceId绑定，一次请求里所有SQL打印相同TraceId；分布式追踪里能直接关联“哪条SQL属于哪个用户请求”，排障效率提升10倍。
八、安全与防注入：代理再好用，也别把SQL“裸奔”
-
参数化
MyBatis天生#{}预编译，但遇到动态排序字段，有人习惯${}拼接，一旦前端把sort=create_time desc, (select sleep(5))传进来，就成功注入。
规范：
-
排序字段用Map封装“白名单”，前端传key，后端反向映射列名
-
所有模糊查询使用bind标签，避免‘%#{}%’写法被转义成?
-
SQL审计
引入第三方审计插件，拦截“批量更新不带where”语句；即使开发者在XML里误写<where> -
权限最小化
连接池账号只拥有“增删改查+执行”权限，禁止alter、drop；即便程序被SQL注入，也无法直接破坏表结构。 -
敏感字段
手机号、身份证号用对称加密存储，加密密钥放在环境变量；Mapper里统一加TypeHandler，自动“写入加密，读取解密”，对业务代码透明，避免“谁漏写加密”造成泄露。
九、性能调优：把“慢”拆解成可量化的小块
-
预编译缓存
MyBatis会为每条SQL生成“预编译键”，若SQL里含动态标签，键里会带“是否展开”标记；
若用大量if标签拼接，键值空间膨胀，缓存命中率下降；
解决：
-
把稳定条件提到外层，减少动态分支
-
用choose/when/otherwise代替多重if，压缩键长度
-
批量操作
foreach插入看似方便，但size过大时会生成“巨型SQL”，网络包超长；
规范：
-
单批次数量控制在500～1000
-
使用BatchExecutor，配合事务一次性提交，减少PreparedStatement重复创建
-
惰性加载
关联查询用association、collection时，默认lazy=true；但若实体里触发了toString，会隐式访问代理对象，导致“N+1”在日志里看不到，却在数据库端狂刷SQL；
解决：
-
重写实体toString，避开代理字段
-
Service层若需序列化，先openSessionInView，再手动遍历填充，避免在JSON转换期触发懒加载
-
连接池调优
连接池大小不是“越大越好”；
公式：
并发线程数 = CPU核数 *（1 + 等待时间/计算时间）
按公式算出理论值，再通过压测把maxActive定在理论值+20%冗余，防止突发流量瞬间占满连接。
十、文档与回滚：让“写文档”比“写代码”更先上线
-
注释即文档
每个XML头加入<!—功能描述、作者、创建日期—>；
若出现“业务规则”判断，用<!-- 当且仅当状态=已支付时更新 --> -
版本diff
在CI里加“SQL变更检查”，把本次分支与目标分支的XML做文本diff，若出现“update不加where”或“delete”关键字，自动标红，阻塞合并。 -
回滚脚本
凡是在XML里写alter table，必须同步提供rollback语句文件，命名成*.rollback.sql，放在同一目录；上线时由发布系统一并执行，确保“能前进也能后退”。 -
接口变更通知
Mapper方法签名一旦删除或改参，使用静态分析工具扫描所有调用方，自动生成“变更清单”发邮件给相关团队；避免“A团队改签名，B团队代码编译期就爆炸”。
十一、常见翻车现场与速效救心丸
-
大小写歧义
Windows开发环境不区分大小写，生产环境是Linux，导致“OrderMapper.xml”与“Ordermapper.xml”绑定失败；
解决：统一小写命名，提交前用git钩子强制检查。 -
重载方法
接口里写selectById(Long id)与selectById(String id)，框架按类型解析时冲突；
解决：方法名加后缀区分场景，如selectByIdString、selectByIdLong。 -
事务未提交
单元测试里默认回滚，开发者误以为“插入成功”，上线后发现主键冲突；
解决：在BaseTest里提供commit辅助方法，专门用于“需要断言数据库结果”的用例。 -
二级缓存序列化失败
实体新增字段后未实现Serializable，导致缓存重启时反序列化报错；
解决：把“实现Serializable”写进团队规约，IDE检查模板里加自动提醒。
十二、渐进式治理：如何把“老项目”拉上岸
-
静态扫描先行
引入规则引擎，扫描“Map参数”“${}拼接”“方法重载”等历史债务，按严重程度打标签，先生成“技术债看板”。 -
分层重构
先改“目录结构”，再改“方法命名”，最后动“SQL逻辑”；每一步都独立MR，减少“一次性改动过大”带来的回滚风险。 -
双轨验证
新SQL与老SQL并行跑，通过“影子流量”对比结果一致性，100%通过后再切换正式路由。 -
奖励机制
每消除一个“高危标签”，给予“构建加速券”或“发布绿色通道”，让团队成员从“被动改”变成“主动改”。
