462 lines
12 KiB
Markdown
462 lines
12 KiB
Markdown
# 后端扩展开发模式
|
||
|
||
> 基于 jnpf-extend 模块的 Controller → Service → Mapper → Entity 分层架构
|
||
> 源码分析时间:2026-04-01
|
||
|
||
---
|
||
|
||
## 一、目录结构
|
||
|
||
```
|
||
jnpf-extend/
|
||
├── jnpf-extend-controller/ # 控制层
|
||
│ └── src/main/java/jnpf/controller/{Xxx}Controller.java
|
||
├── jnpf-extend-biz/ # 业务层
|
||
│ ├── src/main/java/jnpf/service/{Xxx}Service.java # 接口
|
||
│ ├── src/main/java/jnpf/service/impl/{Xxx}ServiceImpl.java
|
||
│ └── src/main/java/jnpf/mapper/{Xxx}Mapper.java
|
||
└── jnpf-extend-entity/ # 实体层
|
||
├── src/main/java/jnpf/entity/{Xxx}Entity.java
|
||
└── src/main/java/jnpf/model/{module}/*{VO,Form}.java
|
||
```
|
||
|
||
---
|
||
|
||
## 二、Entity 层
|
||
|
||
### 2.1 实体类模板
|
||
|
||
```java
|
||
package jnpf.entity;
|
||
|
||
import com.baomidou.mybatisplus.annotation.TableField;
|
||
import com.baomidou.mybatisplus.annotation.TableName;
|
||
import jnpf.base.entity.SuperExtendEntity;
|
||
import lombok.Data;
|
||
import lombok.EqualsAndHashCode;
|
||
import java.math.BigDecimal;
|
||
import java.util.Date;
|
||
|
||
@EqualsAndHashCode(callSuper = true)
|
||
@Data
|
||
@TableName("Xxx") // 表名:PascalCase 无前缀
|
||
public class XxxEntity extends SuperExtendEntity<String> {
|
||
|
||
@TableField("f_fieldName")
|
||
private String fieldName;
|
||
|
||
@TableField("f_amount")
|
||
private BigDecimal amount; // 金额用 BigDecimal
|
||
|
||
@TableField("f_createTime")
|
||
private Date createTime;
|
||
}
|
||
```
|
||
|
||
### 2.2 命名规范
|
||
|
||
| 类型 | 规范 | 示例 |
|
||
|------|------|------|
|
||
| 表名 | PascalCase 无前缀 | `TableExample` |
|
||
| 字段 | `f_` 前缀 + PascalCase | `f_projectName` |
|
||
| Java字段 | 驼峰命名 | `projectName` |
|
||
|
||
### 2.3 主键策略
|
||
|
||
- 主键类型:`String` (UUID)
|
||
- 主键生成:`RandomUtil.uuId()`
|
||
- 排序码:`RandomUtil.parses()`
|
||
|
||
### 2.4 审计字段
|
||
|
||
继承 `SuperExtendEntity` 自动获得:
|
||
- `creatorTime` / `creatorUserId` - 创建人
|
||
- `lastModifyTime` / `lastModifyUserId` - 修改人
|
||
- `sortCode` - 排序码
|
||
- `deleteMark` - 删除标记
|
||
|
||
---
|
||
|
||
## 三、Mapper 层
|
||
|
||
### 3.1 Mapper 接口模板
|
||
|
||
```java
|
||
package jnpf.mapper;
|
||
|
||
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
|
||
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
|
||
import jnpf.base.mapper.SuperMapper;
|
||
import jnpf.entity.XxxEntity;
|
||
import jnpf.model.PaginationXxx;
|
||
import jnpf.util.RandomUtil;
|
||
import jnpf.util.UserProvider;
|
||
import org.apache.ibatis.annotations.Mapper;
|
||
import java.util.Date;
|
||
|
||
@Mapper
|
||
public interface XxxMapper extends SuperMapper<XxxEntity> {
|
||
|
||
// ========== CRUD ==========
|
||
|
||
default XxxEntity getInfo(String id) {
|
||
return this.selectById(id);
|
||
}
|
||
|
||
default void create(XxxEntity entity) {
|
||
entity.setId(RandomUtil.uuId());
|
||
entity.setSortCode(RandomUtil.parses());
|
||
entity.setCreatorTime(new Date());
|
||
entity.setCreatorUserId(UserProvider.getUser().getUserId());
|
||
this.insert(entity);
|
||
}
|
||
|
||
default boolean update(String id, XxxEntity entity) {
|
||
entity.setId(id);
|
||
entity.setLastModifyTime(new Date());
|
||
entity.setLastModifyUserId(UserProvider.getUser().getUserId());
|
||
return this.updateById(entity) > 0;
|
||
}
|
||
|
||
default void delete(XxxEntity entity) {
|
||
this.deleteById(entity.getId());
|
||
}
|
||
|
||
// ========== 分页查询 ==========
|
||
|
||
default Page<XxxEntity> getList(PaginationXxx pagination) {
|
||
QueryWrapper<XxxEntity> wrapper = new QueryWrapper<>();
|
||
|
||
// 关键字查询
|
||
if (!StringUtils.isEmpty(pagination.getKeyword())) {
|
||
wrapper.lambda()
|
||
.like(XxxEntity::getFieldName, pagination.getKeyword());
|
||
}
|
||
|
||
// 排序
|
||
wrapper.lambda().orderByDesc(XxxEntity::getCreatorTime);
|
||
|
||
Page<XxxEntity> page = new Page<>(
|
||
pagination.getCurrentPage(),
|
||
pagination.getPageSize()
|
||
);
|
||
return this.selectPage(page, wrapper);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 QueryWrapper 常用模式
|
||
|
||
```java
|
||
// 关键字模糊查询
|
||
wrapper.lambda()
|
||
.like(Entity::getField, keyword)
|
||
.or()
|
||
.like(Entity::getField2, keyword);
|
||
|
||
// 精确查询
|
||
wrapper.lambda().eq(Entity::getField, value);
|
||
|
||
// 范围查询
|
||
wrapper.lambda().between(Entity::getTime, start, end);
|
||
|
||
// IN 查询
|
||
wrapper.lambda().in(Entity::getId, list);
|
||
|
||
// 分页
|
||
Page<Entity> page = new Page<>(current, pageSize);
|
||
IPage<Entity> result = this.selectPage(page, wrapper);
|
||
```
|
||
|
||
---
|
||
|
||
## 四、Service 层
|
||
|
||
### 4.1 Service 接口
|
||
|
||
```java
|
||
package jnpf.service;
|
||
|
||
import jnpf.entity.XxxEntity;
|
||
import jnpf.model.PaginationXxx;
|
||
import java.util.List;
|
||
|
||
public interface XxxService {
|
||
List<XxxEntity> getList();
|
||
List<XxxEntity> getList(PaginationXxx pagination);
|
||
XxxEntity getInfo(String id);
|
||
void create(XxxEntity entity);
|
||
boolean update(String id, XxxEntity entity);
|
||
void delete(XxxEntity entity);
|
||
}
|
||
```
|
||
|
||
### 4.2 Service 实现
|
||
|
||
```java
|
||
package jnpf.service.impl;
|
||
|
||
@Service
|
||
public class XxxServiceImpl extends SuperServiceImpl<XxxMapper, XxxEntity>
|
||
implements XxxService {
|
||
|
||
@Override
|
||
public List<XxxEntity> getList() {
|
||
return this.baseMapper.getList();
|
||
}
|
||
|
||
@Override
|
||
public List<XxxEntity> getList(PaginationXxx pagination) {
|
||
return this.baseMapper.getList(pagination);
|
||
}
|
||
|
||
@Override
|
||
public XxxEntity getInfo(String id) {
|
||
return this.baseMapper.getInfo(id);
|
||
}
|
||
|
||
@Override
|
||
public void create(XxxEntity entity) {
|
||
this.baseMapper.create(entity);
|
||
}
|
||
|
||
@Override
|
||
public boolean update(String id, XxxEntity entity) {
|
||
return this.baseMapper.update(id, entity);
|
||
}
|
||
|
||
@Override
|
||
public void delete(XxxEntity entity) {
|
||
this.baseMapper.delete(entity);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、Controller 层
|
||
|
||
### 5.1 Controller 模板
|
||
|
||
```java
|
||
package jnpf.controller;
|
||
|
||
@Tag(name = "功能名称", description = "Xxx")
|
||
@RestController
|
||
@RequestMapping("/api/extend/Xxx")
|
||
@RequiredArgsConstructor
|
||
public class XxxController extends SuperController<XxxService, XxxEntity> {
|
||
|
||
private final XxxService xxxService;
|
||
|
||
// ========== CRUD ==========
|
||
|
||
@Operation(summary = "获取列表")
|
||
@GetMapping
|
||
@SaCheckPermission("extend.xxx.list")
|
||
public ActionResult<PageListVO<XxxListVO>> list(PaginationXxx pagination) {
|
||
List<XxxEntity> data = xxxService.getList(pagination);
|
||
List<XxxListVO> list = JsonUtil.getJsonToList(data, XxxListVO.class);
|
||
return ActionResult.page(list, JsonUtil.getJsonToBean(pagination, PaginationVO.class));
|
||
}
|
||
|
||
@Operation(summary = "获取信息")
|
||
@GetMapping("/{id}")
|
||
@SaCheckPermission("extend.xxx.list")
|
||
public ActionResult<XxxInfoVO> info(@PathVariable("id") String id) {
|
||
XxxEntity entity = xxxService.getInfo(id);
|
||
return ActionResult.success(JsonUtil.getJsonToBean(entity, XxxInfoVO.class));
|
||
}
|
||
|
||
@Operation(summary = "新建")
|
||
@PostMapping
|
||
@SaCheckPermission("extend.xxx.list")
|
||
public ActionResult create(@RequestBody @Valid XxxCrForm form) {
|
||
XxxEntity entity = JsonUtil.getJsonToBean(form, XxxEntity.class);
|
||
xxxService.create(entity);
|
||
return ActionResult.success(MsgCode.SU001.get());
|
||
}
|
||
|
||
@Operation(summary = "更新")
|
||
@PutMapping("/{id}")
|
||
@SaCheckPermission("extend.xxx.list")
|
||
public ActionResult update(@PathVariable("id") String id,
|
||
@RequestBody @Valid XxxUpForm form) {
|
||
XxxEntity entity = JsonUtil.getJsonToBean(form, XxxEntity.class);
|
||
boolean flag = xxxService.update(id, entity);
|
||
return flag ? ActionResult.success(MsgCode.SU004.get())
|
||
: ActionResult.fail(MsgCode.FA002.get());
|
||
}
|
||
|
||
@Operation(summary = "删除")
|
||
@DeleteMapping("/{id}")
|
||
@SaCheckPermission("extend.xxx.list")
|
||
public ActionResult delete(@PathVariable("id") String id) {
|
||
XxxEntity entity = xxxService.getInfo(id);
|
||
if (entity != null) {
|
||
xxxService.delete(entity);
|
||
return ActionResult.success(MsgCode.SU003.get());
|
||
}
|
||
return ActionResult.fail(MsgCode.FA003.get());
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 接口定义模式
|
||
|
||
| 操作 | 注解 | 路径 | 权限 |
|
||
|------|------|------|------|
|
||
| 列表 | `@GetMapping` | `/api/extend/Xxx` | `@SaCheckPermission` |
|
||
| 详情 | `@GetMapping("/{id}")` | `/{id}` | `@SaCheckPermission` |
|
||
| 创建 | `@PostMapping` | `/api/extend/Xxx` | `@SaCheckPermission` |
|
||
| 更新 | `@PutMapping("/{id}")` | `/{id}` | `@SaCheckPermission` |
|
||
| 删除 | `@DeleteMapping("/{id}")` | `/{id}` | `@SaCheckPermission` |
|
||
|
||
### 5.3 参数获取方式
|
||
|
||
```java
|
||
@PathVariable("id") // URL 路径参数
|
||
@RequestBody @Valid // 请求体 + JSR-303 校验
|
||
@RequestParam("name") // 查询参数
|
||
```
|
||
|
||
### 5.4 统一返回值
|
||
|
||
```java
|
||
ActionResult.success(vo) // 成功
|
||
ActionResult.fail(MsgCode.XX.get()) // 失败
|
||
ActionResult.page(list, paginationVO) // 分页
|
||
```
|
||
|
||
---
|
||
|
||
## 六、Model 类
|
||
|
||
### 6.1 分页模型
|
||
|
||
```java
|
||
package jnpf.model;
|
||
|
||
@Data
|
||
public class PaginationXxx extends Page {
|
||
private String keyword; // 关键字
|
||
private String field; // 字段过滤
|
||
// ... 业务特定字段
|
||
}
|
||
```
|
||
|
||
### 6.2 VO 模型
|
||
|
||
```java
|
||
package jnpf.model;
|
||
|
||
// 列表 VO
|
||
@Data
|
||
public class XxxListVO {
|
||
private String id;
|
||
private String fieldName;
|
||
// 仅包含需要返回的字段
|
||
}
|
||
|
||
// 详情 VO
|
||
@Data
|
||
public class XxxInfoVO {
|
||
private String id;
|
||
private String fieldName;
|
||
private BigDecimal amount;
|
||
// 包含所有字段
|
||
}
|
||
```
|
||
|
||
### 6.3 Form 模型
|
||
|
||
```java
|
||
package jnpf.model;
|
||
|
||
// 创建表单
|
||
@Data
|
||
public class XxxCrForm {
|
||
@NotBlank(message = "字段不能为空")
|
||
private String fieldName;
|
||
}
|
||
|
||
// 更新表单
|
||
@Data
|
||
public class XxxUpForm {
|
||
private String fieldName;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 七、导入导出模式(参考 EmployeeController)
|
||
|
||
### 7.1 导出 Excel
|
||
|
||
```java
|
||
@GetMapping("/ExportData")
|
||
public ActionResult<DownloadVO> exportData(PaginationXxx pagination) {
|
||
List<XxxEntity> list = xxxService.getList(pagination);
|
||
List<XxxExportVO> voList = JsonUtil.getJsonToList(list, XxxExportVO.class);
|
||
|
||
// 构建导出列
|
||
List<ExcelExportEntity> entitys = new ArrayList<>();
|
||
entitys.add(new ExcelExportEntity("列名", "field"));
|
||
|
||
ExportParams params = new ExportParams(null, "标题");
|
||
Workbook workbook = ExcelExportUtil.exportExcel(params, entitys, voList);
|
||
|
||
// 上传并返回
|
||
String fileName = "导出_" + DateUtil.dateNow("yyyyMMddHHmmss") + ".xlsx";
|
||
// ... 上传逻辑
|
||
return ActionResult.success(vo);
|
||
}
|
||
```
|
||
|
||
### 7.2 导入预览
|
||
|
||
```java
|
||
@GetMapping("/ImportPreview")
|
||
public ActionResult importPreview(@RequestParam("fileName") String fileName) {
|
||
// 下载文件并解析
|
||
List<XxxModel> list = ExcelUtil.importExcelByInputStream(inputStream, 0, 1, XxxModel.class);
|
||
return ActionResult.success(xxxService.importPreview(list));
|
||
}
|
||
```
|
||
|
||
### 7.3 导入数据
|
||
|
||
```java
|
||
@PostMapping("/ImportData")
|
||
public ActionResult importData(@RequestBody XxxModel data) {
|
||
List<XxxEntity> list = JsonUtil.getJsonToList(data.getList(), XxxEntity.class);
|
||
// ... 处理并插入
|
||
return ActionResult.success(result);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 八、关键配置项
|
||
|
||
| 配置项 | 值 |
|
||
|--------|-----|
|
||
| 表名 | PascalCase 无前缀 |
|
||
| 字段前缀 | `f_` |
|
||
| 主键类型 | String (UUID) |
|
||
| 主键生成 | `RandomUtil.uuId()` |
|
||
| 审计字段 | 自动从 `SuperExtendEntity` 继承 |
|
||
| API 路径 | `/api/extend/Xxx` |
|
||
| 权限格式 | `extend.xxx.yyy` |
|
||
|
||
---
|
||
|
||
## 九、参考示例
|
||
|
||
| 示例 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| TableExample | `jnpf-extend/.../TableExample*` | 完整 CRUD + 特殊操作 |
|
||
| Employee | `jnpf-extend/.../Employee*` | 导入导出完整流程 |
|
||
| Order | `jnpf-extend/.../Order*` | 主子表结构 |
|
||
| ProjectGantt | `jnpf-extend/.../ProjectGantt*` | 树形+复杂结构 |
|