Files
aibridge/docs/codedev/01-backend-pattern.md
2026-05-18 09:28:15 +08:00

462 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 后端扩展开发模式
> 基于 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*` | 树形+复杂结构 |