苍穹外卖：接口设计理念深入与实战及对象属性拷贝

目录

新增员工表时，为什么需要接口设计

1. 实现数据与应用的解耦

2. 保障数据安全与权限控制

3. 规范业务流程与数据校验

4. 提供统一的交互契约

5. 便于监控、统计与限流

总结

接口设计的流程：

第一步：明确业务需求（做什么）

第二步：定义接口契约（长什么样）

1. 接口地址

2. 请求方法

3. 请求参数

4. 返回响应

5. 接口状态码

第三步：编写接口逻辑（怎么做）

第四步：生成接口文档

第五步：联调与测试

Jason数据的来源：

. 如果是“新增员工”时

如果是“查询/编辑员工”时

关于在新增员工中的对象属性拷贝：

1. 首先，为什么要分 DTO 和 Employee（实体）？

2. 为什么不能直接用 Employee 接收前端的参数？

3. 对象属性拷贝在这里起了什么作用？

具体流程：

前言：前面我们学习了项目开发环境的搭建，今天我们学习项目的具体业务操作，以及实现这些业务操作的原理。

新增员工表时，为什么需要接口设计

在新增员工表（或任何数据库表）时，接口设计并不是一个必须与建表同时发生的物理步骤，但它是系统开发中至关重要的一环。

简单来说，表是数据的“仓库”，而接口是操作这个仓库的“门”。如果只建表而不设计接口，数据就无法被安全、高效地使用。

以下是为什么在新增员工表时需要（或建议）进行接口设计的几个核心原因：

1. 实现数据与应用的解耦

2. 保障数据安全与权限控制

3. 规范业务流程与数据校验

4. 提供统一的交互契约

5. 便于监控、统计与限流

总结

新增员工表时考虑接口设计，本质上是将“数据存储”与“业务使用”分离开来。

所以，接口设计是为了让你的员工表用起来更安全、更稳定、更容易维护。

接口设计的流程：

第一步：明确业务需求（做什么）

在设计接口之前，需要先搞清楚业务场景。不能只想着“往表里插数据”，而要思考“用户操作时的真实意图”。

• 隐含逻辑：
  • 工号必须全局唯一。
  • 手机号必须验证（11位，符合号段）。
  • 如果没填密码，需要生成一个随机的默认密码。

第二步：定义接口契约（长什么样）

这是接口设计的核心产出，通常包含以下 5 个要素。我们可以使用工具（如 Swagger, Postman, YApi）或文档记录下来：

• 格式： 通常是 JSON。
• 示例报文： json { “empId”： “E2025001”， // 工号 [必填， 字符串， 唯一] “name”： “张三”， // 姓名 [必填， 字符串， 1-20位] “mobile”： “13800138000”， // 手机号 [必填， 字符串， 11位] “email”： “zhangsan@qq.com”，// 邮箱 [选填， 符合邮箱格式] “deptId”： “D01”， // 部门ID [必填] “hireDate”： “2026-03-01” // 入职日期 [必填， 日期格式] }

4. 返回响应 定义后端处理完后，返回什么给前端。

• 成功时的响应： 通常返回创建成功后的数据，或者简单的成功提示。 json { “code”： 200, “message”： “操作成功”， “data”： { “empId”： “E2025001”, “name”： “张三” // ... 可能返回完整的员工对象 } }
• 失败时的响应： json { “code”： 40001, “message”： “工号已存在，请重新输入” }

5. 接口状态码 定义通用的业务状态码，例如 200 成功、400 参数错误、500 服务器内部错误等。

第三步：编写接口逻辑（怎么做）

契约定义好后，后端开始写代码实现内部逻辑。这一步虽然是对表的操作，但绝不仅仅是 insert into 员工表 这么简单。通常会分为三层：

1. Service 层（业务层）： 编写核心逻辑。
   • 校验1： 工号 E2025001 在数据库里存在吗？如果存在，直接返回“工号重复”的错误。
   • 校验2： 手机号格式对吗？部门 ID 存在吗？
   • 处理： 如果没有传密码，调用工具类生成一个 123456 的加密哈希值。
   • 事务： 如果还需要同时创建员工账户，这里需要用事务包裹，保证两个表同时成功或失败。

Dao/Mapper 层（数据层）： 最终拼接成 SQL，执行 insert into employee ...。

第四步：生成接口文档

第五步：联调与测试

Jason数据的来源：

. 如果是“新增员工”时

场景： 你在网页表单里填好信息，点提交。这时候发往后端的 JSON，来源于你的操作。

• 来源： 浏览器的内存 + 用户的输入。
• 产生过程：
  1. 你在输入框里打字（比如姓名：张三）。
  2. 前端JavaScript脚本监听到输入，或者在你点击提交时，读取这些输入框里的值。
  3. 前端JS代码把这些散乱的“值”拼装成一个 JSON 对象：

如果是“查询/编辑员工”时

场景： 你打开编辑页面，发现表单里自动填好了张三的信息。这时候你看到的 JSON 数据，来源于数据库。

• 来源： 数据库（DB） -> 后端服务器 -> 网络 -> 前端。
• 产生过程：
  • 第一步：数据库提供原料
    • 数据库里有一行记录：张三， 13800138000， D01。
  • 第二步：后端加工（最关键的一步）
    • 后端代码执行 SQL：select * from employee where id = 123；
    • 后端从数据库取出一堆字段（这时的数据在内存里还是ResultSet格式）；
    • 后端代码会把这些数据，按照接口设计文档的要求，一个一个字段地塞进一个对象里，然后用JSON库（如Jackson、Fastjson）把这个对象序列化**成 JSON 文本。
  • 第三步：网络传输
    • 后端通过HTTP响应，把这串文本返给前端：
  • 第四步：前端解析
  • 前端拿到这个JSON字符串后，JS引擎会把它解析成JavaScript对象。
  • 然后代码读取 obj.name 的值，把它填充到页面的输入框里

关于在新增员工中的对象属性拷贝：

1. 首先，为什么要分 DTO 和 Employee（实体）？

在项目中，这两个类虽然长得很像，但职责完全不同：

• Employee（实体）：
  • 对应数据库表。 它的字段结构通常和数据库的 employee 表一一对应。
  • 位置： entity 包。
  • 敏感度： 它包含了所有数据库字段，比如数据库里有个字段 password（密码）、create_time（创建时间）。
• EmployeeDTO（数据传输对象）：
  • 对应前端请求。 前端传了什么参数，DTO 就写什么字段。
  • 位置： dto 包。
  • 特点： 它只包含前端允许传入的数据。
  • 举例： 在“新增员工”的接口里，前端只需要传用户名、姓名、手机号。前端不应该传密码（即使传了后端也不能信），也不需要传创建时间（这是后端自动生成的）。

2. 为什么不能直接用 Employee 接收前端的参数？

如果你在 Controller 里直接写成 public Result save(@RequestBody Employee employee)，会发生两个严重问题：

1. 安全隐患（关键）：
   • 正常情况下，前端只传 {“name”：“张三”}。
   • 恶意用户抓到接口后，可能会额外传一个 {“name”：“张三”， “password”：“123456”， “status”：0}。
   • 如果后端直接用 Employee 接收，数据库里的 password 和 status 就可能被前端传过来的值覆盖，造成严重的数据篡改。

数据冗余/无效： 前端根本不知道 create_time 是什么格式，也不应该由前端传。

3. 对象属性拷贝在这里起了什么作用？

当你通过了校验，确认前端发来的数据是合法的之后，就需要把数据从 DTO 转移到 Employee 上。

• 拷贝完基础信息后，通常紧接着会手动补充一些 DTO 里没有的字段：

具体流程：

[前端请求]
    |
    |  (只包含：name, phone, username)
    v
[EmployeeDTO]  <-- 这是"干净"的，只包含允许用户输入的数据
    |
    |  使用 BeanUtils.copyProperties
    |  (只拷贝同名属性，如 name->name, phone->phone)
    v
[Employee]     <-- 这是"完整"的，即将入库的数据
    |
    |  手动补充：id, password, createTime, createUser...
    v
[数据库]

结语：如果对你有帮助，请点赞，关注，收藏，你的支持就是我最大的动力！！