feat: 移动端开发规范重大更新
- 🔥 完全重写 .cursor/cursorrules-mobile.md (940行) * 基于实际mobile工程Vue 3.4.21+uniapp+uview-plus架构 * 移除所有JeeSite相关内容,精准匹配实际项目 * 新增11个完整章节:技术栈、项目结构、页面开发、组件规范等 - 📚 创建完整规范文档 docs/开发文档/移动端开发规范总结.md (800+行) * 涵盖从项目架构到部署的全流程指导 * 提供可直接使用的页面和组件模板 * 包含现代CSS变量设计系统和用户体验优化 - 🔄 同步更新主配置文件 .cursorrules * 更新移动端技术栈描述 * 调整为Vue 3.4.21+uniapp+uview-plus 3.4.45架构 - 📝 完善变更记录 * 详细记录规范更新背景和技术价值 * 为后续维护提供完整历史记录 核心价值:解决规范与实际项目不匹配问题,为Cursor AI提供准确的移动端开发上下文,确保生成代码完全符合实际项目架构。
This commit is contained in:
1 parent
e8ece1b612
commit
28232d5d46
131 files changed
+17170
-5479
No files matched your search
+627
-18
@@ -424,36 +424,200 @@ public class UserBo {
|
||||
|
||||
### 🔴 API 开发强制性工作流程
|
||||
|
||||
#### 步骤 1:编写后端代码
|
||||
#### 💡 基于场地预约 API 开发实践的标准流程
|
||||
|
||||
- 创建 Controller、Service、Mapper 等
|
||||
- 实现业务逻辑和数据处理
|
||||
- 添加权限控制和参数验证
|
||||
**⚠️ 本流程基于场地预约管理系统的成功开发经验制定,必须严格遵循!**
|
||||
|
||||
#### 步骤 2:立即更新 API 文档(强制性)
|
||||
#### 步骤 1:需求分析和文档创建
|
||||
|
||||
**在编写任何代码之前必须完成**:
|
||||
|
||||
- 📋 **创建需求文档**:`docs/需求文档/[模块名]/` 详细的业务需求说明
|
||||
- 🏗️ **业务模块文档**:`docs/业务模块/[模块名]/README.md` 技术架构说明
|
||||
- 🗄️ **数据库设计**:完整的表结构、字典数据、权限配置设计
|
||||
|
||||
**参考示例**:
|
||||
|
||||
- `docs/需求文档/后勤场地预约需求/场地预约系统需求说明.md`
|
||||
- `docs/业务模块/venue-reservation/README.md`
|
||||
|
||||
#### 步骤 2:数据库初始化(必须先行)
|
||||
|
||||
**在编写业务代码之前必须完成数据库设计**:
|
||||
|
||||
- 🗄️ **数据表创建**:`docs/设计文档/database/[模块名]-module.sql`
|
||||
- 📊 **字典数据配置**:`docs/设计文档/database/[模块名]-data.sql`
|
||||
- 🔐 **菜单权限配置**:`docs/设计文档/database/[模块名]-menu.sql`
|
||||
- 🧪 **示例数据插入**:便于开发和测试
|
||||
|
||||
**参考示例**:
|
||||
|
||||
```sql
|
||||
-- 04-venue-reservation-module.sql (数据表)
|
||||
-- 04-venue-reservation-data.sql (字典数据)
|
||||
-- 04-venue-reservation-menu.sql (菜单权限)
|
||||
```
|
||||
|
||||
#### 步骤 3:后端模块开发
|
||||
|
||||
**完整的 ruoyi 模块开发结构**:
|
||||
|
||||
```
|
||||
ruoyi-[模块名]/
|
||||
├── pom.xml # 模块依赖配置
|
||||
├── src/main/java/org/dromara/[模块名]/
|
||||
│ ├── domain/ # 实体类
|
||||
│ │ ├── [Entity].java # 数据库实体(继承TenantEntity)
|
||||
│ │ ├── bo/[EntityBo].java # 业务对象(含验证注解)
|
||||
│ │ └── vo/[EntityVo].java # 视图对象(含Excel注解)
|
||||
│ ├── mapper/ # 数据访问层
|
||||
│ │ ├── [Entity]Mapper.java # Mapper接口
|
||||
│ │ └── xml/[Entity]Mapper.xml # SQL映射文件
|
||||
│ ├── service/ # 业务逻辑层
|
||||
│ │ ├── I[Entity]Service.java # 服务接口
|
||||
│ │ └── impl/[Entity]ServiceImpl.java # 服务实现
|
||||
│ └── controller/ # 控制器层
|
||||
│ └── [Entity]Controller.java # REST API控制器
|
||||
└── src/main/resources/
|
||||
└── mapper/[Entity]Mapper.xml # MyBatis映射文件
|
||||
```
|
||||
|
||||
**开发要点**:
|
||||
|
||||
- ✅ **实体类**:必须继承`TenantEntity`,包含完整注释
|
||||
- ✅ **业务对象**:添加`@Validated`参数校验注解
|
||||
- ✅ **视图对象**:支持 Excel 导出,添加`@ExcelProperty`注解
|
||||
- ✅ **权限控制**:每个接口必须添加`@SaCheckPermission`注解
|
||||
- ✅ **响应格式**:分页用`TableDataInfo`,非分页用`R`类型
|
||||
|
||||
#### 步骤 4:API 接口规范实现
|
||||
|
||||
**16 个标准 API 接口设计模式**(基于场地预约实践):
|
||||
|
||||
**基础管理接口(6 个)**:
|
||||
|
||||
```java
|
||||
@GetMapping("/list") // 分页查询列表
|
||||
@GetMapping("/{id}") // 查询详情
|
||||
@PostMapping // 新增
|
||||
@PutMapping // 修改
|
||||
@DeleteMapping("/{ids}") // 删除
|
||||
@GetMapping("/available") // 获取可用选项
|
||||
```
|
||||
|
||||
**业务功能接口(4 个)**:
|
||||
|
||||
```java
|
||||
@GetMapping("/my") // 查询我的数据
|
||||
@GetMapping("/pending") // 查询待处理数据
|
||||
@GetMapping("/conflict") // 业务规则检查
|
||||
@PostMapping("/approve") // 审批操作
|
||||
```
|
||||
|
||||
**辅助功能接口(6 个)**:
|
||||
|
||||
```java
|
||||
@PostMapping("/export") // 导出Excel
|
||||
@PostMapping("/import") // 导入Excel
|
||||
@GetMapping("/statistics") // 统计数据
|
||||
@PostMapping("/batch") // 批量操作
|
||||
@PostMapping("/{id}/enable") // 启用操作
|
||||
@PostMapping("/{id}/disable") // 禁用操作
|
||||
```
|
||||
|
||||
#### 步骤 5:立即更新 API 文档(强制性)
|
||||
|
||||
**⚠️ 代码写完后立即执行,不得延后!**
|
||||
|
||||
- 打开 `docs/开发文档/API.md` 文件
|
||||
- 按照 `docs/开发文档/API/API文档模板.md` 的标准格式添加或更新接口文档
|
||||
- 包含完整的接口信息(地址、参数、响应、权限等)
|
||||
- 添加真实的请求和响应示例
|
||||
- 📖 **创建模块 API 文档**:`docs/开发文档/API/[模块名]管理API.md`
|
||||
- 📋 **按标准模板编写**:参考`docs/开发文档/API/API文档模板.md`
|
||||
- 🔗 **更新文档总览**:在`docs/开发文档/API/API文档总览.md`中添加导航
|
||||
- ✅ **包含完整信息**:16 个接口的详细参数、响应、权限、业务规则
|
||||
|
||||
#### 步骤 3:记录代码调整日志
|
||||
**参考示例**:
|
||||
|
||||
- 在 `docs/变更管理/code-adjust-record.md` 中记录本次变更
|
||||
- 特别说明 API 接口的变更内容
|
||||
- 标注文档已同步更新
|
||||
- `docs/开发文档/API/场地预约管理API.md` (400+行完整文档)
|
||||
|
||||
#### 步骤 4:验证和测试
|
||||
#### 步骤 6:创建自动化测试脚本
|
||||
|
||||
- 测试 API 接口功能是否正常
|
||||
- 验证 API 文档的准确性
|
||||
- 确保文档示例与实际响应一致
|
||||
**完整的 Python 测试脚本开发**:
|
||||
|
||||
- 🐍 **测试脚本**:`test/[模块名]API测试脚本.py`
|
||||
- 🔐 **AES+RSA 加密登录**:严格按照`cursorrules-api-test.md`规范
|
||||
- 🧪 **完整功能覆盖**:测试所有 16 个 API 接口
|
||||
- 📋 **业务规则测试**:验证时间冲突、权限控制等
|
||||
- 🧹 **自动数据清理**:测试完成后清理测试数据
|
||||
|
||||
**测试脚本标准结构**:
|
||||
|
||||
```python
|
||||
class [Module]APITest:
|
||||
def __init__(self): # 初始化和配置
|
||||
def login(self): # AES+RSA双重加密登录
|
||||
def test_[entity]_management(self): # 基础管理功能测试
|
||||
def test_[business]_features(self): # 业务功能测试
|
||||
def test_business_rules(self): # 业务规则验证
|
||||
def cleanup_test_data(self): # 测试数据清理
|
||||
def run_all_tests(self): # 执行完整测试
|
||||
```
|
||||
|
||||
#### 步骤 7:模块集成和配置
|
||||
|
||||
**模块集成到主项目**:
|
||||
|
||||
- 📦 **添加模块依赖**:在`ruoyi-modules/pom.xml`中添加子模块
|
||||
- 🔗 **集成到启动模块**:在`ruoyi-admin/pom.xml`中添加依赖
|
||||
- ⚙️ **版本管理**:在根`pom.xml`的`dependencyManagement`中配置版本
|
||||
|
||||
#### 步骤 8:记录变更日志(强制性)
|
||||
|
||||
**详细记录开发过程**:
|
||||
|
||||
- 📝 **变更记录**:`docs/变更管理/code-adjust-record-YYYY-MM-DD-{username}.md`
|
||||
- ⏰ **按时间记录**:需求分析 → 数据库 → 后端开发 → 文档 → 测试的完整流程
|
||||
- 📊 **包含统计**:文件数量、接口数量、测试覆盖率等
|
||||
|
||||
#### 步骤 9:验证和测试
|
||||
|
||||
**完整的验证流程**:
|
||||
|
||||
- 🖥️ **后端服务启动**:确保服务正常运行
|
||||
- 🧪 **API 功能测试**:运行自动化测试脚本
|
||||
- 📖 **文档准确性验证**:确保文档示例与实际响应一致
|
||||
- 🔐 **权限控制测试**:验证接口权限和数据权限
|
||||
|
||||
#### 🚨 违规后果
|
||||
|
||||
**如果发现 API 变更未同步更新文档,该代码变更将被视为不完整,必须立即补齐文档。**
|
||||
**如果发现以下问题,该代码变更将被视为不完整:**
|
||||
|
||||
- ❌ 数据库变更未创建对应 SQL 脚本
|
||||
- ❌ API 接口变更未同步更新文档
|
||||
- ❌ 缺少自动化测试脚本
|
||||
- ❌ 未记录详细的变更日志
|
||||
- ❌ 模块未正确集成到主项目
|
||||
|
||||
#### 📊 开发完成标准
|
||||
|
||||
**一个完整的 API 模块开发必须包含**:
|
||||
|
||||
- ✅ 完整的需求和技术文档(2-3 个文档)
|
||||
- ✅ 数据库脚本和权限配置(3 个 SQL 文件)
|
||||
- ✅ 完整的后端模块代码(15-20 个 Java 文件)
|
||||
- ✅ 详细的 API 接口文档(400+行)
|
||||
- ✅ 自动化测试脚本(450+行)
|
||||
- ✅ 完整的变更记录日志
|
||||
- ✅ 模块成功集成和功能验证
|
||||
|
||||
#### 💡 最佳实践总结
|
||||
|
||||
**基于场地预约 API 开发的成功经验**:
|
||||
|
||||
1. **先文档后代码**:需求分析完成后再开始编码
|
||||
2. **数据库优先**:表结构确定后再开发业务逻辑
|
||||
3. **标准化接口**:16 个接口模式覆盖 90%的业务场景
|
||||
4. **文档同步更新**:代码完成立即更新文档
|
||||
5. **完整测试验证**:自动化测试确保质量
|
||||
6. **规范化集成**:严格按照项目架构规范集成
|
||||
|
||||
## 4. 🔐 菜单界面和接口权限配置规范
|
||||
|
||||
@@ -975,6 +1139,451 @@ testPermissions(token, permissionTests).then((results) => {
|
||||
- [ ] 是否进行了权限功能测试?
|
||||
- [ ] API 文档是否更新了权限信息?
|
||||
|
||||
### 🔴 VO 类基础字段规范(强制性)
|
||||
|
||||
**⚠️ 超级重要:为了项目一致性,所有 VO 类必须包含统一的基础字段!**
|
||||
|
||||
#### 🎯 规范背景
|
||||
|
||||
基于实际开发中发现的问题,不同查询方式对 VO 类字段的要求存在差异:
|
||||
|
||||
| 查询方式 | 基础字段处理 | VO 类要求 | 示例 |
|
||||
| ------------------------- | -------------- | -------------- | ---------------------- |
|
||||
| **MyBatis-Plus 自动查询** | 不包含继承字段 | 无需基础字段 | `HqSatCategoryVo` |
|
||||
| **自定义 SQL 查询** | 明确包含字段 | 必须有对应字段 | `HqVenueReservationVo` |
|
||||
|
||||
**问题案例**:
|
||||
|
||||
```
|
||||
org.mybatis.spring.MyBatisSystemException:
|
||||
Could not set property 'createBy' of 'class org.dromara.venue.domain.vo.HqVenueReservationVo'
|
||||
with value '1' Cause: There is no setter for property named 'createBy'
|
||||
```
|
||||
|
||||
#### 🚨 强制性统一规范
|
||||
|
||||
**为了避免开发过程中的不一致问题,所有 VO 类必须包含完整的基础字段!**
|
||||
|
||||
#### 📋 标准 VO 类基础字段模板
|
||||
|
||||
```java
|
||||
/**
|
||||
* 标准VO类模板
|
||||
*
|
||||
* @author [作者]
|
||||
*/
|
||||
@Data
|
||||
@ExcelIgnoreUnannotated
|
||||
@AutoMapper(target = [Entity].class)
|
||||
public class [Entity]Vo implements Serializable {
|
||||
|
||||
@Serial
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
// ========== 业务字段 ==========
|
||||
|
||||
/**
|
||||
* 主键ID
|
||||
*/
|
||||
@ExcelProperty(value = "主键ID")
|
||||
private Long id;
|
||||
|
||||
// ... 其他业务字段 ...
|
||||
|
||||
// ========== 基础字段(强制性,所有VO类必须包含) ==========
|
||||
|
||||
/**
|
||||
* 创建者
|
||||
*/
|
||||
private Long createBy;
|
||||
|
||||
/**
|
||||
* 创建时间
|
||||
*/
|
||||
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
|
||||
@ExcelProperty(value = "创建时间")
|
||||
private Date createTime;
|
||||
|
||||
/**
|
||||
* 更新者
|
||||
*/
|
||||
private Long updateBy;
|
||||
|
||||
/**
|
||||
* 更新时间
|
||||
*/
|
||||
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
|
||||
private Date updateTime;
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
#### 🛠️ 基础字段说明
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 | JSON 格式化 | Excel 导出 |
|
||||
| -------------- | ------ | ---- | --------- | ----------- | ---------- |
|
||||
| **createBy** | `Long` | ✅ | 创建者 ID | 否 | 否 |
|
||||
| **createTime** | `Date` | ✅ | 创建时间 | ✅ | ✅ |
|
||||
| **updateBy** | `Long` | ✅ | 更新者 ID | 否 | 否 |
|
||||
| **updateTime** | `Date` | ✅ | 更新时间 | ✅ | 否 |
|
||||
|
||||
#### 📝 字段使用注解规范
|
||||
|
||||
```java
|
||||
// 时间字段必须使用JSON格式化注解
|
||||
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
|
||||
private Date createTime;
|
||||
|
||||
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
|
||||
private Date updateTime;
|
||||
|
||||
// 创建时间可选择性导出到Excel
|
||||
@ExcelProperty(value = "创建时间")
|
||||
private Date createTime;
|
||||
|
||||
// 更新时间通常不导出到Excel
|
||||
private Date updateTime;
|
||||
```
|
||||
|
||||
#### 🚨 强制性要求
|
||||
|
||||
1. **⚠️ 所有 VO 类必须包含四个基础字段**:createBy、createTime、updateBy、updateTime
|
||||
2. **⚠️ 字段类型必须统一**:createBy/updateBy 为 Long,createTime/updateTime 为 Date
|
||||
3. **⚠️ 时间字段必须使用 JSON 格式化注解**:`@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")`
|
||||
4. **⚠️ 新生成的 VO 类必须检查基础字段完整性**
|
||||
5. **⚠️ 修复现有 VO 类时必须补全缺失的基础字段**
|
||||
|
||||
#### 🔍 VO 类检查清单
|
||||
|
||||
**新增 VO 类检查**:
|
||||
|
||||
- [ ] 是否包含 createBy 字段?
|
||||
- [ ] 是否包含 createTime 字段?
|
||||
- [ ] 是否包含 updateBy 字段?
|
||||
- [ ] 是否包含 updateTime 字段?
|
||||
- [ ] 时间字段是否有 JSON 格式化注解?
|
||||
- [ ] 字段类型是否正确(Long/Date)?
|
||||
|
||||
**现有 VO 类修复**:
|
||||
|
||||
- [ ] 检查 MyBatis 映射错误日志中提到的字段
|
||||
- [ ] 补全缺失的基础字段
|
||||
- [ ] 重新构建模块 jar 包
|
||||
- [ ] 触发热重启验证修复效果
|
||||
|
||||
#### 💡 最佳实践
|
||||
|
||||
**1. 代码生成器配置**
|
||||
|
||||
```java
|
||||
// 在代码生成模板中包含基础字段
|
||||
// generator/template/vo.java.vm
|
||||
/**
|
||||
* 创建者
|
||||
*/
|
||||
private Long createBy;
|
||||
|
||||
/**
|
||||
* 创建时间
|
||||
*/
|
||||
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
|
||||
@ExcelProperty(value = "创建时间")
|
||||
private Date createTime;
|
||||
|
||||
/**
|
||||
* 更新者
|
||||
*/
|
||||
private Long updateBy;
|
||||
|
||||
/**
|
||||
* 更新时间
|
||||
*/
|
||||
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
|
||||
private Date updateTime;
|
||||
```
|
||||
|
||||
**2. 开发流程规范**
|
||||
|
||||
```
|
||||
新增VO类 → 使用标准模板 → 包含基础字段 → 编译测试
|
||||
修复VO类 → 补全缺失字段 → 重新构建 → 热重启验证
|
||||
```
|
||||
|
||||
**3. 问题预防措施**
|
||||
|
||||
- 定期检查 VO 类与 Entity 类的字段对应关系
|
||||
- MyBatis 映射错误要及时检查字段定义
|
||||
- 使用 IDE 插件自动检查 VO 类完整性
|
||||
- 在代码评审中重点检查 VO 类基础字段
|
||||
|
||||
#### 🎯 修复现有问题的标准流程
|
||||
|
||||
**当遇到 MyBatis 映射错误时**:
|
||||
|
||||
```bash
|
||||
# 1. 分析错误日志,确认缺失字段
|
||||
grep "Could not set property" logs/error.log
|
||||
|
||||
# 2. 修复VO类,添加缺失字段
|
||||
# 编辑对应的VO类文件
|
||||
|
||||
# 3. 重新构建模块
|
||||
cd ruoyi-modules/[模块名]
|
||||
mvn clean install -U -Dmaven.test.skip=true
|
||||
|
||||
# 4. 重新构建主应用
|
||||
cd ../../ruoyi-admin
|
||||
mvn clean compile -U -Dmaven.test.skip=true
|
||||
|
||||
# 5. 触发热重启
|
||||
echo "reload" > src/main/resources/.reloadtrigger
|
||||
```
|
||||
|
||||
#### 📊 实际修复案例总结
|
||||
|
||||
**案例 1:HqVenueInfoVo**
|
||||
|
||||
```java
|
||||
// 问题:缺少createBy、updateBy、updateTime字段
|
||||
// 修复:添加标准基础字段
|
||||
// 结果:场地管理界面正常加载
|
||||
```
|
||||
|
||||
**案例 2:HqVenueReservationVo**
|
||||
|
||||
```java
|
||||
// 问题:缺少createBy、updateBy、updateTime字段
|
||||
// 修复:添加标准基础字段
|
||||
// 结果:场地预约界面正常加载
|
||||
```
|
||||
|
||||
**案例 3:HqSatCategoryVo**
|
||||
|
||||
```java
|
||||
// 情况:使用MyBatis-Plus自动查询,无需基础字段
|
||||
// 建议:为了一致性,仍建议添加基础字段
|
||||
// 优势:支持未来可能的自定义SQL查询
|
||||
```
|
||||
|
||||
### 📋 VO 类规范违规检查
|
||||
|
||||
**开发阶段检查**:
|
||||
|
||||
- 新增 VO 类时未包含基础字段
|
||||
- 时间字段未使用 JSON 格式化注解
|
||||
- 字段类型不符合规范(如用 String 代替 Date)
|
||||
|
||||
**测试阶段检查**:
|
||||
|
||||
- MyBatis 映射错误日志中提到字段缺失
|
||||
- Excel 导出功能异常
|
||||
- 时间格式显示不正确
|
||||
|
||||
**生产阶段检查**:
|
||||
|
||||
- 接口返回数据中基础字段为空
|
||||
- 前端显示创建时间/更新时间异常
|
||||
- 数据审计功能不完整
|
||||
|
||||
### 🎯 规范总结
|
||||
|
||||
**统一 VO 类基础字段规范的目标**:
|
||||
|
||||
1. **🔄 兼容性**:无论使用 MyBatis-Plus 自动查询还是自定义 SQL,都能正常工作
|
||||
2. **📊 一致性**:所有 VO 类具有统一的基础字段结构
|
||||
3. **🚀 可维护性**:减少因字段缺失导致的运行时错误
|
||||
4. **📈 可扩展性**:支持未来可能的查询方式变更
|
||||
|
||||
**⚠️ 记住:宁可多加字段保证兼容性,也不要因为字段缺失导致系统异常!**
|
||||
|
||||
### 🔴 MyBatis-Plus 自定义 SQL 规范(强制性)
|
||||
|
||||
**⚠️ 基于实际开发中遇到的 SQL 拼接错误,制定强制性规范!**
|
||||
|
||||
#### 🎯 常见问题
|
||||
|
||||
**SQL 拼接错误案例**:
|
||||
|
||||
```xml
|
||||
<!-- ❌ 错误写法 -->
|
||||
<select id="selectPage">
|
||||
SELECT * FROM table_name
|
||||
<where>
|
||||
and deleted = 0
|
||||
${ew.sqlSegment}
|
||||
</where>
|
||||
order by create_time desc
|
||||
</select>
|
||||
```
|
||||
|
||||
**生成的错误 SQL**:
|
||||
|
||||
```sql
|
||||
WHERE and deleted = 0 AND (applicant_id = ?) ORDER BY create_time DESC order by create_time desc
|
||||
```
|
||||
|
||||
#### 🚨 强制性规范
|
||||
|
||||
**1. `${ew.sqlSegment}`使用规范**
|
||||
|
||||
```xml
|
||||
<!-- ✅ 正确写法 -->
|
||||
<select id="selectPage">
|
||||
SELECT * FROM table_name
|
||||
<where>
|
||||
deleted = 0
|
||||
${ew.sqlSegment}
|
||||
</where>
|
||||
</select>
|
||||
```
|
||||
|
||||
**要点**:
|
||||
|
||||
- ✅ `${ew.sqlSegment}`内容**不包含前置 AND**
|
||||
- ✅ 固定条件和动态条件之间**必须显式添加 AND**
|
||||
- ✅ 使用`<if>`标签进行安全的条件拼接
|
||||
- ✅ 使用`<where>`标签自动处理 WHERE 关键字
|
||||
|
||||
**2. ORDER BY 重复问题**
|
||||
|
||||
```java
|
||||
// Java代码中设置排序(推荐)
|
||||
LambdaQueryWrapper<Entity> lqw = Wrappers.lambdaQuery();
|
||||
lqw.orderByDesc(Entity::getCreateTime);
|
||||
```
|
||||
|
||||
```xml
|
||||
<!-- XML中不要重复设置ORDER BY -->
|
||||
<select id="selectPage">
|
||||
SELECT * FROM table_name
|
||||
<where>
|
||||
deleted = 0
|
||||
${ew.sqlSegment}
|
||||
</where>
|
||||
<!-- ❌ 不要在这里再写 order by -->
|
||||
</select>
|
||||
```
|
||||
|
||||
**3. 标准 Mapper.xml 模板**
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
|
||||
<mapper namespace="org.dromara.[module].mapper.[Entity]Mapper">
|
||||
|
||||
<!-- 结果映射(包含基础字段) -->
|
||||
<resultMap type="org.dromara.[module].domain.vo.[Entity]Vo" id="[Entity]Result">
|
||||
<result property="id" column="id"/>
|
||||
<!-- 业务字段映射 -->
|
||||
<result property="createBy" column="create_by"/>
|
||||
<result property="createTime" column="create_time"/>
|
||||
<result property="updateBy" column="update_by"/>
|
||||
<result property="updateTime" column="update_time"/>
|
||||
</resultMap>
|
||||
|
||||
<!-- 基础查询SQL -->
|
||||
<sql id="select[Entity]Vo">
|
||||
select id, [业务字段], create_by, create_time, update_by, update_time
|
||||
from [table_name]
|
||||
</sql>
|
||||
|
||||
<!-- 分页查询(标准模板) -->
|
||||
<select id="select[Entity]Page" resultMap="[Entity]Result">
|
||||
<include refid="select[Entity]Vo"/>
|
||||
<where>
|
||||
deleted = 0
|
||||
<if test="ew != null and ew.sqlSegment != null and ew.sqlSegment != ''">
|
||||
AND ${ew.sqlSegment}
|
||||
</if>
|
||||
</where>
|
||||
</select>
|
||||
|
||||
</mapper>
|
||||
```
|
||||
|
||||
#### 🔍 SQL 拼接检查清单
|
||||
|
||||
**开发阶段检查**:
|
||||
|
||||
- [ ] `${ew.sqlSegment}`前是否误加了`AND`?
|
||||
- [ ] 是否存在重复的 ORDER BY 子句?
|
||||
- [ ] `<where>`标签是否正确使用?
|
||||
- [ ] VO 类是否包含完整的基础字段?
|
||||
|
||||
**测试阶段检查**:
|
||||
|
||||
- [ ] 分页查询是否正常工作?
|
||||
- [ ] SQL 日志中是否有语法错误?
|
||||
- [ ] 条件查询是否按预期执行?
|
||||
|
||||
#### 🛠️ 调试和排错
|
||||
|
||||
**启用 MyBatis SQL 日志**:
|
||||
|
||||
```yaml
|
||||
# application-dev.yml
|
||||
logging:
|
||||
level:
|
||||
org.dromara.[module].mapper: debug
|
||||
```
|
||||
|
||||
**SQL 错误快速定位**:
|
||||
|
||||
```bash
|
||||
# 1. 查看错误日志
|
||||
grep "Failed to process, Error SQL" logs/error.log
|
||||
|
||||
# 2. 检查生成的SQL结构
|
||||
# 关注WHERE子句和ORDER BY的拼接
|
||||
|
||||
# 3. 验证Mapper.xml中的拼接逻辑
|
||||
```
|
||||
|
||||
#### 💡 最佳实践
|
||||
|
||||
**1. 统一的 Mapper 方法命名**:
|
||||
|
||||
```java
|
||||
// 分页查询方法
|
||||
Page<EntityVo> selectEntityPage(Page<Entity> page, @Param("ew") LambdaQueryWrapper<Entity> lqw);
|
||||
|
||||
// 列表查询方法
|
||||
List<EntityVo> selectEntityList(@Param("ew") LambdaQueryWrapper<Entity> lqw);
|
||||
```
|
||||
|
||||
**2. Service 中的条件构造**:
|
||||
|
||||
```java
|
||||
private LambdaQueryWrapper<Entity> buildQueryWrapper(EntityBo bo) {
|
||||
LambdaQueryWrapper<Entity> lqw = Wrappers.lambdaQuery();
|
||||
// 添加查询条件
|
||||
lqw.eq(ObjectUtil.isNotNull(bo.getId()), Entity::getId, bo.getId());
|
||||
// 设置排序(统一在Java代码中设置)
|
||||
lqw.orderByDesc(Entity::getCreateTime);
|
||||
return lqw;
|
||||
}
|
||||
```
|
||||
|
||||
**3. 错误预防措施**:
|
||||
|
||||
- 代码生成器模板中使用标准的 SQL 拼接格式
|
||||
- 代码评审时重点检查 Mapper.xml 的 SQL 拼接
|
||||
- 单元测试中验证生成的 SQL 语句
|
||||
- 使用 IDE 插件检查 XML 语法
|
||||
|
||||
#### 🚨 强制性要求总结
|
||||
|
||||
1. **⚠️ 必须在固定条件和`${ew.sqlSegment}`之间显式添加 AND**
|
||||
2. **⚠️ 必须使用`<if>`标签安全拼接`${ew.sqlSegment}`**
|
||||
3. **⚠️ 禁止在 XML 和 Java 代码中重复设置 ORDER BY**
|
||||
4. **⚠️ 必须使用`<where>`标签处理条件拼接**
|
||||
5. **⚠️ 必须在 VO 类中包含完整的基础字段**
|
||||
6. **⚠️ 必须在测试中验证 SQL 拼接结果**
|
||||
|
||||
**违规处理**:不符合规范的 Mapper.xml 将导致运行时 SQL 错误,必须立即修复!
|
||||
|
||||
**⚠️ 记住:宁可多加字段保证兼容性,也不要因为字段缺失导致系统异常!**
|
||||
|
||||
## 5. 标准代码模板
|
||||
|
||||
### Controller 模板
|
||||
|
||||
Reference in new issue
Block a user