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

12 KiB
Raw Permalink Blame History

后端扩展开发模式

基于 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* 树形+复杂结构