12 KiB
12 KiB
后端扩展开发模式
基于 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 实体类模板
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 接口模板
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 常用模式
// 关键字模糊查询
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 接口
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 实现
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 模板
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 参数获取方式
@PathVariable("id") // URL 路径参数
@RequestBody @Valid // 请求体 + JSR-303 校验
@RequestParam("name") // 查询参数
5.4 统一返回值
ActionResult.success(vo) // 成功
ActionResult.fail(MsgCode.XX.get()) // 失败
ActionResult.page(list, paginationVO) // 分页
六、Model 类
6.1 分页模型
package jnpf.model;
@Data
public class PaginationXxx extends Page {
private String keyword; // 关键字
private String field; // 字段过滤
// ... 业务特定字段
}
6.2 VO 模型
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 模型
package jnpf.model;
// 创建表单
@Data
public class XxxCrForm {
@NotBlank(message = "字段不能为空")
private String fieldName;
}
// 更新表单
@Data
public class XxxUpForm {
private String fieldName;
}
七、导入导出模式(参考 EmployeeController)
7.1 导出 Excel
@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 导入预览
@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 导入数据
@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* |
树形+复杂结构 |