# 后端扩展开发模式 > 基于 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 { @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 { // ========== 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 getList(PaginationXxx pagination) { QueryWrapper wrapper = new QueryWrapper<>(); // 关键字查询 if (!StringUtils.isEmpty(pagination.getKeyword())) { wrapper.lambda() .like(XxxEntity::getFieldName, pagination.getKeyword()); } // 排序 wrapper.lambda().orderByDesc(XxxEntity::getCreatorTime); Page 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 page = new Page<>(current, pageSize); IPage 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 getList(); List 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 implements XxxService { @Override public List getList() { return this.baseMapper.getList(); } @Override public List 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 { private final XxxService xxxService; // ========== CRUD ========== @Operation(summary = "获取列表") @GetMapping @SaCheckPermission("extend.xxx.list") public ActionResult> list(PaginationXxx pagination) { List data = xxxService.getList(pagination); List 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 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 exportData(PaginationXxx pagination) { List list = xxxService.getList(pagination); List voList = JsonUtil.getJsonToList(list, XxxExportVO.class); // 构建导出列 List 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 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 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*` | 树形+复杂结构 |