docs: 补齐代码规范与评审清单,记录 HTTP 边界与 Checkstyle 决策
This commit is contained in:
@@ -0,0 +1,49 @@
|
||||
# Agent Note: HTTP 边界不再返回实体,入参改用请求 DTO
|
||||
|
||||
Status: implemented
|
||||
|
||||
## Problem
|
||||
|
||||
接口层的类型直接复用了持久化实体与 `Map`,导致三件事同时发生:
|
||||
|
||||
- **实体即契约**:`CommonResult<TaskApplicationEntity>` 这类返回把库表形状暴露成 API。实体加一个字段就等于改接口,
|
||||
而 `createdBy` / `lastModifiedBy` / `deviceInfo` / `deleted` 这些列本来就不该出现在响应里。
|
||||
- **`Map<String, String>` 当请求体**:10 个端点用 `@RequestBody Map`,字段名只在 `body.get("xxx")` 里出现,
|
||||
拼错 key 不报错、无法被 Bean Validation 校验、OpenAPI 文档里是空对象。
|
||||
- **实体当请求体**:`savePriorityWeights(@RequestBody UserPriorityWeightsEntity)` 让调用方能顺手改 `id`、`createdBy`。
|
||||
|
||||
## Decision
|
||||
|
||||
在 controller 边界做转换,service 层签名不动:
|
||||
|
||||
- 出参:`dto/response/<东西>Response`,字段与实体同名(类型不变),另带 `createdTime` / `lastModifiedTime`;
|
||||
不含 `createdBy` / `lastModifiedBy` / `deviceInfo` / `deleted`。每个类提供 `static of(Entity)` 工厂,实体为 null 时返回 null。
|
||||
- `Page<Entity>` 返回:`new Page<>(current, size, total)` + `setRecords(records.stream().map(X::of).toList())`。
|
||||
- 入参:`dto/request/<动作>Request`,字段名与原先 `body.get("key")` 的 key 完全一致;必要字段加 `@NotBlank` 并在 controller 上 `@Valid`。
|
||||
- 局部更新改用 `update(new Entity(), lambdaUpdate().set(...))`,显式写「改哪几列」,不再依赖 MyBatis-Plus 的全局 null 策略;
|
||||
传入空实体是为了让 `MetaObjectHandler` 继续填 `lastModifiedBy` / `lastModifiedTime` / `deviceInfo`。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**① 直接在 service 层返回 DTO,controller 只透传。**
|
||||
最强理由:转换点更靠里,controller 变薄,未来换实现(比如加缓存层)时不用再改 controller。
|
||||
否掉的原因:service 接口与实现遍布 40 多个类,签名一改要跟着改 600 多个测试与所有调用方;
|
||||
而「实体不出 controller」这条约束只需要在边界做一次转换就成立。等真有了第二个入口(gRPC、MQ handler)再下沉不迟。
|
||||
|
||||
**② 让实体自己 `@JsonIgnore` 掉审计列,不建 DTO。**
|
||||
最强理由:改动最小,一个注解解决泄漏,响应体里也不会再有 `createdBy`。
|
||||
否掉的原因:注解只解决序列化,解决不了「实体能当请求体」和「库表形状即契约」;而且把 API 决策藏在实体里,
|
||||
以后 lpt-ai 或内部服务需要这些列时会互相拉扯。
|
||||
|
||||
**③ 保留 `Map` 请求体,只加 `@Valid` 常量约束。**
|
||||
最强理由:不动前端契约,也没有 10 个新类。
|
||||
否掉的原因:`Map` 拿不到字段级校验与文档,`body.get("markerName")` 拼错永远是 null;
|
||||
本轮恰好要为 18 个出参加 DTO,入参顺手一起做,边际成本远低于再开一轮。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 响应体少了 4 个字段(`createdBy` / `lastModifiedBy` / `deviceInfo` / `deleted`)。已核对 `lpt-fe`:
|
||||
这 4 个字段零使用,`createdTime`(16 处)与 `lastModifiedTime`(2 处)保留,前端无需改动。
|
||||
- service 仍返回实体,controller 里多了一次映射调用;`Page` 需要手工重建(MyBatis-Plus 的 `convert` 返回 `IPage`,类型对不上)。
|
||||
- 请求 DTO 里加了 `@NotBlank`,校验失败的文案由 DTO 决定;原本由 service 抛 `ErrorParameterException` 的路径仍在(DTO 未覆盖的语义校验)。
|
||||
- 回归由 608 个测试守住;改动后 `./mvnw validate` 仍为 0 违规。
|
||||
Reference in New Issue
Block a user