【项目开发日记 | 根据业务流程产出前后端交互文档】第二天

🌈 个人主页: Hygge_Code
🔥 热门专栏:从0开始学习Java | Linux学习| 计算机网络
💫 个人格言: "既然选择了远方，便不顾风雨兼程"

文章目录

• 项目开发日记
• • [今日总结 🤔🐦‍🔥🤔](#今日总结 🤔🐦‍🔥🤔)
  • [前期 - 部分业务流程图分析](#前期 - 部分业务流程图分析)
  • • 分配的工单
    • 流程图
  • [要求：快速产出前后端交互文档 👏👏👏](#要求：快速产出前后端交互文档 👏👏👏)
  • 完成的目录结构
  • • 业务对应的DTO类：`PositionDataPermissionDTO`
    • [接口类： `PositionDataPermissionApis`](#接口类： PositionDataPermissionApis)
    • 控制层：`PositionDataPermissionController`
  • [生成的API交互文档 📖](#生成的API交互文档 📖)
  • [完成分支推送 ⏏️](#完成分支推送 ⏏️)
  • [细节 & 复习 🤔🍂🤔](#细节 & 复习 🤔🍂🤔)
  • • [1. 四个请求映射注解：`@GetMapping`、`@PutMapping`、`@DeleteMapping`、`@PostMapping`](#1. 四个请求映射注解：@GetMapping、@PutMapping、@DeleteMapping、@PostMapping)
    • [2. 三个用来接收前端传参的注解： `@RequestParam`、`@PathVariable` 、 `@RequestBody`](#2. 三个用来接收前端传参的注解： @RequestParam、@PathVariable 、 @RequestBody)
    • 3.映射数据库字段时最好使用`Integer`，而非`int`
    • [4. Knife4j生成API 文档注解](#4. Knife4j生成API 文档注解)

项目开发日记

今日总结 🤔🐦‍🔥🤔

• 完成了部分业务的流程图分析（前期）
• 在团队开发中，接口先行，如果等后端把 service/mapper/dao 全写完，前端才能拿到接口文档，那前端只能干等，严重拖慢整体进度，所以后端要先尽快产出前后端交互文档，让团队知道接口的设计是否合理，提高联合开发效率
• 完成了业务模块的目录结构搭建与代码分支推送
• 巩固了 Spring Boot 接口开发与 Knife4j 文档生成的核心知识点

前期 - 部分业务流程图分析

分配的工单

流程图

以下是我对于部分业务的流程分析示意图：

要求：快速产出前后端交互文档 👏👏👏

完成的目录结构

业务对应的DTO类：PositionDataPermissionDTO

@ApiModel("数据权限实体类")
@Data
public class PositionDataPermissionDTO {

    @ApiModelProperty(value = "数据表表名",required = true,example = "staff")
    private String entity_name;

    @ApiModelProperty(value = "数据权限范围类型，不填则表示按系统默认",required = false,example = "1全部 2本校 3本部门 4自己")
    private Integer scope_type;


    @ApiModelProperty(value = "负责人字段,如果是修改数据,则要传,新增则不用",required = false,example = "creator")
    private String owner_field;

    @ApiModelProperty(value = "数据所属组织字段名，不填则表示按系统默认",required = false,example = "org_id")
    private String owner_org_field;

}

接口类： PositionDataPermissionApis

/**
 * 职位数据权限相关接口
 */
public interface PositionDataPermissionApis {

    /**
     * 分页查询数据权限信息
     * @param condition 分页条件
     * @return 数据权限信息
     */
    JsonVO<PageDTO<PositionDataPermissionDTO>> queryPage(PositionDataPermissionQuery condition);

    /**
     * 保存职位数据权限信息（新增/修改）
     * @param positionDataPermissionDTO 职位数据权限信息
     * @return 保存结果对应的id(新增则无)
     */
    JsonVO<Long> addPositionDataPermission(PositionDataPermissionDTO positionDataPermissionDTO);

    /**
     * 批量删除职位数据权限信息
     * @param ids 要删除的职位数据权限信息的id列表
     * @return 删除结果对应的id
     */
    JsonVO<List<Long>> removePositionDataPermission(List<Long> ids);
}

控制层：PositionDataPermissionController

@Api(tags = "职位管理")
@RestController("j1/org")
public class PositionDataPermissionController implements PositionDataPermissionApis {

    @GetMapping("j1/org/query")
    @ApiOperation("获取职位数据权限列 表（条件+分页）")
    @Override
    public JsonVO<PageDTO<PositionDataPermissionDTO>> queryPage(@RequestParam PositionDataPermissionQuery condition) {
        return null;
    }

    @PostMapping("j1/org/save")
    @ApiOperation("保存职位数据权限")
    @Override
    public JsonVO<Long> addPositionDataPermission(@RequestBody PositionDataPermissionDTO positionDataPermissionDTO) {
        return null;
    }

    @DeleteMapping("j1/org/remove")
    @ApiOperation("删除职位数据权限（支持批量删除）")
    @ApiImplicitParam(name = "ids",value = "职位数据权限对应的id列表",type = "Array",required = true,example = "1")
    @Override
    public JsonVO<List<Long>> removePositionDataPermission(@RequestBody List<Long> ids) {
        return null;
    }
}

生成的API交互文档 📖

完成分支推送 ⏏️

细节 & 复习 🤔🍂🤔

1. 四个请求映射注解：@GetMapping、@PutMapping、@DeleteMapping、@PostMapping

• 查数据 → @GetMapping
• 增数据 → @PostMapping
• 改数据 → @PutMapping
• 删数据 → @DeleteMapping

2. 三个用来接收前端传参的注解： @RequestParam、@PathVariable 、 @RequestBody

问题：什么时候该用哪个呢？🤔

1. @RequestParam

• 作用：接收 URL?key=value 或 form表单 提交的参数
  举例：前端传参方式为：GET /api/user?name=张三&age=20
• 什么时候使用？
  • 参数数量少
  • 用 GET 查询 数据
  • 前端传 键值对 而非 JSON

---

2. @PathVariable

• 作用：接收 URL 路径 里面提交的参数
  **举例：**前端传参方式为：GET /api/user/1001
  后端代码例子🌰：

@GetMapping("/api/user/{id}")  // {id} 就是路径变量
public String getUserById(@PathVariable Integer id) {
    return "用户ID：" + id;
}

• 什么时候使用？
  • RESTful 风格接口
  • 查询、删除、修改某条数据 时传 id
  • 参数是 URL 路径一部分

---

3. @RequestBody

• 作用：接收 前端传来的 JSON 对象 ，一般用于提交数据
  **举例：**前端传参方式为：GET /api/user?name=张三&age=20
  前端传参方式🌰：

// POST 请求，body 里传 JSON
{
    "username": "admin",
    "password": "123456",
    "age": 20
}

• 什么时候使用？
  • POST / PUT 提交大量数据
  • 前端用 axios / fetch 传 JSON
  • 参数是一个对象（表单、用户信息、商品信息）

---

3.映射数据库字段时最好使用Integer，而非int

当数据库字段类型为tinyint时，若使用int，默认值为0的话（没有输入），可能会跟类型 = 0 ，容易搞混淆

而使用Integer的话，可以为null，即表示用户没有传参，不会混淆

4. Knife4j生成API 文档注解

1. @Api → 写在 Controller 类上面
   作用：给整个控制器起中文名、加描述

@Api(tags = "职位管理")
@RestController("j1/org")
public class PositionDataPermissionController implements PositionDataPermissionApis {
}

---

2. @ApiOperation → 写在 接口方法上面
   作用：描述这个接口是干嘛的

@ApiOperation("获取职位数据权限列 表（条件+分页）")
@Override
public JsonVO<PageDTO<PositionDataPermissionDTO>> queryPage(@RequestParam PositionDataPermissionQuery condition) {
    return null;
}

---

3. @ApiModel → 写在 实体类（Bean）上面
   **作用：**给实体类加说明（比如 User、Order）

@ApiModel("数据权限实体类")
@Data
public class PositionDataPermissionDTO {
}

---

4. @ApiModelProperty → 写在 实体类字段上
   **作用：**给字段加中文名、是否必填、示例值

@ApiModelProperty(value = "数据权限记录ID（新增不传，修改必传）", example = "1")
private Long id;

@ApiModelProperty(value = "数据表表名", required = true, example = "staff")
private String entity_name;

---

5. @ApiParam → 写在 参数前面 （与6的作用一样，只是书写位置不同）
   **作用：**给参数加中文说明

@DeleteMapping("j1/org/remove")
@ApiOperation("删除职位数据权限（支持批量删除）")
@Override
public JsonVO<List<Long>> removePositionDataPermission(
    @RequestBody 
    @ApiParam(value = "职位数据权限对应的id列表", required = true, example = "[1,2,3]")
    List<Long> ids
) {
    return null;
}

---

6. @ApiParam → 写在 方法前面，并且要指定哪个是参数
   **作用：**给参数加中文说明

@DeleteMapping("j1/org/remove")
@ApiOperation("删除职位数据权限（支持批量删除）")
@ApiImplicitParam(name = "ids",value = "职位数据权限对应的id列表",type = "Array",required = true,example = "1")
@Override
public JsonVO<List<Long>> removePositionDataPermission(@RequestBody List<Long> ids) {
    return null;
}

---

如果我的内容对你有帮助，请 点赞 ， 评论 ， 收藏 。创作不易，大家的支持就是我坚持下去的动力！