Java 结构与编码规范重构

## 任务目标 请在当前目标工程中，完成本次模块范围内的 Java 结构与编码规范重构。目标是让职责、数据模型、SQL和业务规则清楚一致，并实际修改代码和验证；不要只交审查清单或示例。缺少资料先读取工程，只有影响正确性且无法从工程确定的事项才提问，其余已授权工作继续推进。 在现有授权范围内完成实际改动和验证；缺少外部条件时先完成可独立实现的部分，不能只停留在计划。 ## 输入信息（选填） 两项均可留空，也可直接用一句话说明目标并附上已有资料。无需自行整理版本、配置或完整需求表；能读取的内容由执行者补齐。 重构模块： 工程与契约资料： ## 信息不完整时 先使用本次对话中已经说明的信息；用户留空、写“暂无／不清楚”或未替换输入标记，都按缺失处理，不当作真实路径、参数或业务值。已能从资料确定的内容不重复询问，不编造文件、日志、接口、业务值或执行结果。在用户已授权的范围内读取相关工程和材料，不为补齐输入擅自扩大操作范围。 ### 优先确认 - 核对分支与未提交修改，并追踪目标入口到 DTO、Service、Mapper/XML 和表结构。 - 盘点状态编码、数据库字典、TypeHandler、序列化字段及历史值处理。 - 检索 SQL 注解、Provider、字符串或 Wrapper，以及反射、SPI、XML、扫描和配置引用。 - 读取既有编译检查、接口回归、数据库集成测试和单一格式工具的入口。 ### 可采用的默认处理 - 保持公共接口、持久化编码、权限和事务行为；不升级框架，不为所有类新增接口或强行改 Stream。 - 已有格式配置优先，缺少配置时沿用同模块稳定风格，只规整本轮文件并用一个兼容工具固化。 - 先落实职责与 SQL 归位等有依据的重构；无法解释的旧编码保留原值，不能映射为首项或零值。 ### 必须有依据的事项 - 状态或字典的权威来源、旧编码含义及迁移映射存在冲突时，不自行更改存量数据的业务解释。 - 拟删除或合并的代码涉及无法确认的外部契约、权限字段或副作用时，不把无静态引用当成可删除证据。 只有缺口会改变业务结果、权限边界或关键实现，且无法从现有资料确认时，才集中提出最多 3 个关键问题；说明影响，并继续完成不依赖答案的部分。一般命名、排版和可逆实现细节按现有约定决定，不逐项等待确认。 ### 资料仍不足时的交付 - 没有工程时交付分层与 XML Mapper 的成套示例、枚举字典归属表和旧编码兼容测试样例，说明未执行项目重构。 - 缺数据库环境时完成可执行的代码检查，并交付参数映射、方言、资源加载和历史值验证用例，不宣称 SQL 已验证。 ## 执行要求 按项目真实 Java、Spring、MyBatis 及数据库版本实施，不借机升级技术栈。XML限定、枚举与字典分工等属于本项目硬约束。MyBatis允许注解，本项目禁止用该能力承载SQL。 1. 先只读建立范围和基线。确认仓库、分支、未提交改动及模块依赖，从入口沿 Controller、Service、Mapper/XML、表结构追踪一条真实业务链，核对已有校验和测试。记录接口字段、错误码、排序分页、事务和数据权限契约；保留无关改动，不重置工作区。给出分批修改顺序后实施，基线失败与本轮引入失败分开记录。 2. 消除业务魔法值。盘点状态、类型、阈值、标识和业务字符串，明确语义及唯一来源。稳定且有限的数据库业务编码使用带显式code和说明的enum，读写绑定实际code，禁止ordinal持久化，也不以枚举名称变动隐式改库值；核对序列化与TypeHandler。可配置字典以数据库为唯一来源，不为同一值再手工维护一套enum。一般固定常量给出语义名称，阈值按业务决定是否配置化，不把每个数字都建成枚举。 3. 兼容旧数据与未知编码。核对历史值、空值、已停用字典项和灰度期间的新编码；读取时保留原编码并按契约展示未知或停用状态，不悄悄映射成零、首项或其他有效业务状态。写入和状态迁移要验证允许范围，无法安全执行时明确拒绝。若需迁移，说明旧值到新值映射、并行版本兼容与回退，不能仅改Java类型让历史记录读不出来。 4. 整理分层和复用。Controller负责协议、参数及身份入口，Service负责业务规则和事务，Mapper负责持久化；DTO承接输入，DO对应持久化模型，VO按接口契约输出，明确转换及允许写入字段，防止客户端覆盖租户、审计或权限字段。先找真实共同语义再复用；只有无业务状态和外部依赖的纯通用函数才抽Util，领域计算和业务校验留在领域Service。禁止万能Util、为了行数拆碎方法、只有一个用途却搭泛型框架；不强制所有类新增接口。 5. 将MyBatis执行的全部SQL集中到XML Mapper。Java业务层和Mapper接口不承载SQL，不用SQL注解、Provider、Java字符串、SQL Builder或Wrapper拼接绕过限制；Mapper接口保留方法与必要参数绑定。同步核对namespace、方法id、参数名、resultMap、主键回填及资源打包。值参数使用#{参数}绑定；动态列、表及排序方向只允许服务端白名单并在XML选择固定片段，禁止用户输入直接进入美元符文本替换。可复用SQL片段须保持租户和业务过滤语义，迁移DDL沿用工程既有机制。 6. 保持循环和查询的业务含义。识别for及映射转换中的循环查库、远程调用和隐式懒加载N+1，按真实关联键先批量获取再组装；限制批次、分页和内存，不全量装入大表。保留结果顺序、重复项及缺失关联的语义，空集合不得导致XML过滤消失或全表更新。for清楚时保留for，不一律改成Stream或parallelStream；改变调用顺序与批量失败语义时补充相应验证。 7. 加固边界而不隐藏错误。权限和租户来自可信上下文，每次读写核对数据归属；批量查询和幂等结果回放同样不能越权。区分未传、显式null、空字符串、空集合和合法零值，防止拆箱空指针、金额精度或日期时区改变。异常保留原因和必要关联标识，日志脱敏且避免层层重复；不吞异常返回成功或空列表。事务按实际代理调用和回滚规则核验，自调用未触发新事务语义不等于外层必无事务。 8. 重构写操作时保住幂等和外部副作用。以业务键、租户范围、数据库唯一约束及事务保障同一意图只落一次业务结果，不能只靠先查后插、前端禁按钮或短期缓存。核对重复请求、并发、同键不同内容、超时结果不明与重试；不把超时当作失败直接重做。远程调用和消息不能假定随数据库事务回滚，按现有能力处理结果查询、可靠投递或补偿，不在结构重构中随意增加中间件。 9. 清理与规范同步落地。删除前检查静态引用、XML、反射、序列化、注解扫描、SPI、定时任务与配置约定；确认失效或重复才删，不能仅凭IDE灰色提示。按业务职责规整目录、依赖、命名和成员顺序；在类、关键字段、枚举及方法补充有意义的Javadoc，说明参数、返回、异常和业务限制，复杂分支注释解释原因而非复述代码，不编造作者日期。新增表的全部字段及新增字段须写入详细中文数据库注释，使用COMMENT或目标数据库对应语法，说明含义、单位、编码、空值及默认值语义。空格、换行、缩进和导入遵循既有规则及单一格式化工具，仅处理本轮文件，禁止无关整仓格式化。 10. 实际验证并收口。在每批修改后检查差异，运行受影响模块的编译、既有静态检查及必要测试；补足对契约变化有辨识力的回归，覆盖旧编码、未知编码、空输入、权限租户、批量边界、事务失败和重复请求。XML须验证资源加载、参数结果映射及真实数据库方言；仅编译不能证明SQL正确。环境不足时完成可执行部分并列明具体缺口，不把未运行、没有测试或仅人工阅读写成通过。 ## 交付与验收 交付格式：先说明完成的业务变化及保留的契约，再列修改文件与理由、枚举/字典/常量归属表、Java到XML迁移及分层对应关系、删除证据、实际验证结果和剩余风险。存在数据库变更时附项目已有格式的迁移与回退内容；没有实测就不给性能提升数字。交付已完成的代码，不生成无关Markdown文档，不将方案当作完成。 格式落地补充：工程缺少成文配置时，以同模块稳定风格制定一套最小规则，明确空格、缩进、换行、空行、导入顺序及成员组织，用兼容的格式化或静态检查工具固化到现有构建。列出实际采用的规则和检查入口，不能只口头要求代码整齐，也不能额外引入相互冲突的格式工具。 ### 本条完成检查 - 实际完成目标范围的结构整理、显式编码、XML SQL、DTO/DO/VO 边界和基于真实共性的复用。 - 删除有引用核对证据，新增字段具有详细中文注释，格式调整局限本轮文件。 - 记录编译及契约、旧编码、空值、权限、批量和事务回归，区分基线失败与本轮失败。 按本条要求组织结果，使用简洁中文和一致的编号、术语、缩进及空行；已有项目格式优先。只说明实际完成的内容，将采用的假设、未完成项和缺少的条件写在相关位置，不额外生成无关文档。未执行、无法复现或缺少证据的检查如实标注，不宣称已通过或已有性能收益。 ## 参考资料与适用边界 官方依据（2026-09-08核验，仅采用相关条目，不代表完整企业内部规范）： - 阿里巴巴《P3C-PMD 公开编码规则》：https://github.com/alibaba/p3c/blob/master/p3c-pmd/README.md - MyBatis《MyBatis 3：Mapper XML Files》：https://mybatis.org/mybatis-3/sqlmap-xml.html - MyBatis《MyBatis 3：Dynamic SQL》：https://mybatis.org/mybatis-3/dynamic-sql.html - Spring《Spring Framework：Using @Transactional》：https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/annotations.html - Spring《Spring Framework：Rolling Back a Declarative Transaction》：https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/rolling-back.html 收录核验（2026-09-08）：已核对公开资料和本次项目要求的覆盖范围；尚未使用真实项目执行本模板或进行模型效果评测。具体改动、性能和回归结果须在目标工程中验证。