feat: initial commit

This commit is contained in:
admin committed 2026-05-18 09:28:15 +08:00
commit 539b115e38
232 files changed
+31223

No files matched your search

+461
View File
@@ -0,0 +1,461 @@
# 后端扩展开发模式
> 基于 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*` | 树形+复杂结构 |