Spring Boot 与 MyBatis 完整接口实战

本案例以“新增订单分页查询接口”为例，覆盖参数校验、分层实现、MyBatis SQL、权限边界、测试和构建验收。

教程目标

在不改数据库结构的前提下，完成一个可测试、可回滚的只读查询接口。

第 1 步：只读审计项目

请只读分析当前 Spring Boot + MyBatis 项目。

确认：
1. JDK、Spring Boot、Maven/Gradle、MyBatis 版本。
2. Controller、Service、Mapper、DTO、异常处理的项目惯例。
3. XML Mapper 或注解 SQL 的真实用法。
4. 鉴权、租户、数据权限和分页方案。
5. 单元/集成测试与构建命令。
6. 目标表、索引和字段含义；无法确认时明确提问。

不要根据 Java 实体猜表结构。迁移文件、建表 SQL 或数据库元数据才是依据。

第 2 步：定义接口契约

示例验收：GET /api/orders?page=1&pageSize=20&status=PAID，页码和大小有边界，状态值受枚举限制，返回统一分页 DTO，不泄露内部字段。

请先给出接口契约、校验规则、错误响应、权限条件和 SQL 计划，不修改文件。
说明会改哪些层，以及为什么每一层都必要。

第 3 步：先写测试

至少覆盖：正常分页、空结果、非法页码、非法状态、无权限、租户隔离和 Mapper 参数绑定。数据库集成测试使用项目已有测试容器或测试库，不连接生产库。

第 4 步：分层实现

按确认契约实现最小改动。

要求：
1. Controller 只做协议与校验。
2. Service 处理业务和权限边界。
3. Mapper 参数显式命名，动态 SQL 使用安全绑定。
4. 禁止字符串拼接用户输入到 SQL。
5. 只读查询不要新增无意义事务；需要事务时说明传播与只读属性。
6. 不修改表结构和无关接口。

第 5 步：审查 SQL

让 Codex检查分页语义、排序稳定性、空条件、索引利用、N+1、字段选择和租户条件。排序字段如来自用户输入，必须使用白名单映射，不能直接 ${orderBy}。

第 6 步：完整验证

请运行目标测试、完整测试和项目构建。
如有可用测试环境，再验证 200、400、401/403 和空结果。
展示完整 diff，并确认没有数据库迁移、生产配置、密钥或无关格式化。

常见失败分支

• Invalid bound statement：检查 Mapper namespace、方法名和资源打包路径。
• 参数为 null：检查 @Param、DTO 映射和动态 SQL 条件。
• 分页重复或丢数据：增加稳定且唯一的排序键。
• 本地成功、CI 编译失败：确认 JDK 与 Maven Toolchain/Compiler 配置一致。
• 测试误连生产：立即停止，移除凭据并固定测试 profile。

验收结果

1. 接口契约、校验、权限和错误响应明确。
2. SQL 不拼接用户输入，租户和数据权限条件未遗漏。
3. 测试覆盖正常、边界、失败和隔离场景。
4. 目标测试、完整测试和构建有真实结果。
5. diff 没有表结构、生产配置或无关改动。

下一篇看：Maven 与 JDK 版本排障。