docs: 增加DTO与统一响应改造计划
This commit is contained in:
414
docs/superpowers/plans/2026-05-18-dto-request-result-refactor.md
Normal file
414
docs/superpowers/plans/2026-05-18-dto-request-result-refactor.md
Normal file
@@ -0,0 +1,414 @@
|
||||
# DTO And RequestResult Refactor Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 将现有枚举、附件、RAG 三块接口统一改造成 DTO 入参与 DTO 返回，并引入 `RequestResult` 作为统一响应包装。
|
||||
|
||||
**Architecture:** `controller`、`service`、`mapper` 三层都尽量以 DTO 作为边界对象，实体类仅用于 MyBatis-Plus 持久化与表映射。控制层统一返回 `RequestResult<T>`，查询条件走 request/query DTO，列表和详情都返回 response DTO，避免继续直接暴露实体和零散参数。
|
||||
|
||||
**Tech Stack:** Java 21、Spring Boot 4、MyBatis-Plus、Spring MVC、JUnit 5
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 建立统一响应体和 DTO 包结构
|
||||
|
||||
**Files:**
|
||||
- Create: `src/main/java/com/bruce/common/dto/RequestResult.java`
|
||||
- Create: `src/main/java/com/bruce/common/dto/request/`
|
||||
- Create: `src/main/java/com/bruce/common/dto/response/`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/request/`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/response/`
|
||||
- Modify: `src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java`
|
||||
- Modify: `src/test/java/com/bruce/rag/RagComponentStructureTests.java`
|
||||
|
||||
- [ ] **Step 1: 写失败测试，固定统一返回体存在且控制层不再暴露裸实体**
|
||||
|
||||
在结构测试中增加如下断言思路：
|
||||
|
||||
```java
|
||||
Method saveOrUpdateMethod = SysEnumController.class.getMethod("saveOrUpdate", SysEnumSaveRequest.class);
|
||||
assertEquals(RequestResult.class, saveOrUpdateMethod.getReturnType());
|
||||
```
|
||||
|
||||
```java
|
||||
Method listMethod = RagStoreController.class.getMethod("list", RagStoreQueryRequest.class);
|
||||
assertEquals(RequestResult.class, listMethod.getReturnType());
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行测试并确认失败**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysEnumComponentStructureTests,RagComponentStructureTests" test`
|
||||
|
||||
Expected: FAIL，提示 DTO 或 `RequestResult` 类型不存在，或控制器方法签名不匹配。
|
||||
|
||||
- [ ] **Step 3: 最小化实现统一响应体和基础 DTO 目录**
|
||||
|
||||
`RequestResult.java` 采用如下结构：
|
||||
|
||||
```java
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
public class RequestResult<T> {
|
||||
private boolean success;
|
||||
private String code;
|
||||
private String message;
|
||||
private T data;
|
||||
|
||||
public static <T> RequestResult<T> success(T data) {
|
||||
return new RequestResult<>(true, "SUCCESS", "操作成功", data);
|
||||
}
|
||||
|
||||
public static <T> RequestResult<T> success(String message, T data) {
|
||||
return new RequestResult<>(true, "SUCCESS", message, data);
|
||||
}
|
||||
|
||||
public static <T> RequestResult<T> failure(String code, String message) {
|
||||
return new RequestResult<>(false, code, message, null);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 运行测试并确认通过**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysEnumComponentStructureTests,RagComponentStructureTests" test`
|
||||
|
||||
Expected: PASS 或只剩下后续控制器签名相关失败。
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/main/java/com/bruce/common/dto src/main/java/com/bruce/rag/dto src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java src/test/java/com/bruce/rag/RagComponentStructureTests.java
|
||||
git commit -m "refactor: 增加统一响应体与DTO结构"
|
||||
```
|
||||
|
||||
### Task 2: 重构 sys_enum 模块为 DTO 入参与 DTO 返回
|
||||
|
||||
**Files:**
|
||||
- Create: `src/main/java/com/bruce/common/dto/request/SysEnumQueryRequest.java`
|
||||
- Create: `src/main/java/com/bruce/common/dto/request/SysEnumSaveRequest.java`
|
||||
- Create: `src/main/java/com/bruce/common/dto/response/SysEnumResponse.java`
|
||||
- Modify: `src/main/java/com/bruce/common/controller/SysEnumController.java`
|
||||
- Modify: `src/main/java/com/bruce/common/service/ISysEnumService.java`
|
||||
- Modify: `src/main/java/com/bruce/common/service/impl/SysEnumServiceImpl.java`
|
||||
- Modify: `src/main/java/com/bruce/common/mapper/SysEnumMapper.java`
|
||||
- Modify: `src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java`
|
||||
|
||||
- [ ] **Step 1: 写失败测试，固定 sys_enum 控制器和服务都使用 DTO**
|
||||
|
||||
在 `SysEnumComponentStructureTests` 中增加断言：
|
||||
|
||||
```java
|
||||
Method queryMethod = SysEnumController.class.getMethod("queryByCatalogAndType", SysEnumQueryRequest.class);
|
||||
Method saveMethod = SysEnumController.class.getMethod("saveOrUpdate", SysEnumSaveRequest.class);
|
||||
Method serviceMethod = ISysEnumService.class.getMethod("listByCatalogAndType", SysEnumQueryRequest.class);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行测试并确认失败**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysEnumComponentStructureTests" test`
|
||||
|
||||
Expected: FAIL，提示方法签名仍然是 `String` 或 `SysEnum`。
|
||||
|
||||
- [ ] **Step 3: 最小化实现 request/response DTO**
|
||||
|
||||
`SysEnumQueryRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysEnumQueryRequest {
|
||||
private String catalog;
|
||||
private String type;
|
||||
}
|
||||
```
|
||||
|
||||
`SysEnumSaveRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysEnumSaveRequest {
|
||||
private Long id;
|
||||
private String catalog;
|
||||
private String type;
|
||||
private String name;
|
||||
private Integer value;
|
||||
private String strvalue;
|
||||
private Integer sort;
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
`SysEnumResponse.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysEnumResponse {
|
||||
private Long id;
|
||||
private String catalog;
|
||||
private String type;
|
||||
private String name;
|
||||
private Integer value;
|
||||
private String strvalue;
|
||||
private Integer sort;
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 修改 mapper/service/controller**
|
||||
|
||||
- `ISysEnumService` 返回 `List<SysEnumResponse>`，保存返回 `SysEnumResponse`
|
||||
- `SysEnumServiceImpl` 新增 DTO 与实体互转私有方法
|
||||
- `SysEnumMapper` 保留 MP 基础能力；如需自定义查询，新增 DTO 查询方法签名
|
||||
- `SysEnumController` 所有接口返回 `RequestResult<?>`
|
||||
|
||||
控制器目标形态：
|
||||
|
||||
```java
|
||||
@PostMapping("/query")
|
||||
public RequestResult<List<SysEnumResponse>> queryByCatalogAndType(@RequestBody SysEnumQueryRequest request) {
|
||||
return RequestResult.success(sysEnumService.listByCatalogAndType(request));
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 运行测试并确认通过**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysEnumComponentStructureTests" test`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/main/java/com/bruce/common/controller/SysEnumController.java src/main/java/com/bruce/common/service/ISysEnumService.java src/main/java/com/bruce/common/service/impl/SysEnumServiceImpl.java src/main/java/com/bruce/common/dto/request/SysEnumQueryRequest.java src/main/java/com/bruce/common/dto/request/SysEnumSaveRequest.java src/main/java/com/bruce/common/dto/response/SysEnumResponse.java src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java
|
||||
git commit -m "refactor: 调整sys_enum接口为DTO模式"
|
||||
```
|
||||
|
||||
### Task 3: 重构 sys_attachment 模块为 DTO 入参与 DTO 返回
|
||||
|
||||
**Files:**
|
||||
- Create: `src/main/java/com/bruce/common/dto/request/SysAttachmentUploadRequest.java`
|
||||
- Create: `src/main/java/com/bruce/common/dto/request/SysAttachmentQueryRequest.java`
|
||||
- Create: `src/main/java/com/bruce/common/dto/response/SysAttachmentResponse.java`
|
||||
- Modify: `src/main/java/com/bruce/common/controller/SysAttachmentController.java`
|
||||
- Modify: `src/main/java/com/bruce/common/service/ISysAttachmentService.java`
|
||||
- Modify: `src/main/java/com/bruce/common/service/impl/SysAttachmentServiceImpl.java`
|
||||
- Modify: `src/test/java/com/bruce/common/attachment/SysAttachmentComponentStructureTests.java`
|
||||
|
||||
- [ ] **Step 1: 写失败测试，固定附件接口返回 `RequestResult` 且 service 返回 DTO**
|
||||
|
||||
示例断言：
|
||||
|
||||
```java
|
||||
Method uploadMethod = SysAttachmentController.class.getMethod("upload", MultipartFile.class, SysAttachmentUploadRequest.class);
|
||||
assertEquals(RequestResult.class, uploadMethod.getReturnType());
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行测试并确认失败**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysAttachmentComponentStructureTests" test`
|
||||
|
||||
Expected: FAIL，提示控制器或服务方法签名不匹配。
|
||||
|
||||
- [ ] **Step 3: 新增附件 DTO**
|
||||
|
||||
`SysAttachmentUploadRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysAttachmentUploadRequest {
|
||||
private String sourceType;
|
||||
private Long sourceId;
|
||||
}
|
||||
```
|
||||
|
||||
`SysAttachmentQueryRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysAttachmentQueryRequest {
|
||||
private String sourceType;
|
||||
private Long sourceId;
|
||||
}
|
||||
```
|
||||
|
||||
`SysAttachmentResponse.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysAttachmentResponse {
|
||||
private Long id;
|
||||
private String sourceType;
|
||||
private Long sourceId;
|
||||
private String originalName;
|
||||
private String fileName;
|
||||
private String fileSuffix;
|
||||
private String contentType;
|
||||
private Long fileSize;
|
||||
private String storageType;
|
||||
private String filePath;
|
||||
private String fileUrl;
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 修改附件控制器和服务**
|
||||
|
||||
- `ISysAttachmentService.upload` 返回 `SysAttachmentResponse`
|
||||
- 控制器上传接口返回 `RequestResult<SysAttachmentResponse>`
|
||||
- 如补充列表查询，也走 `SysAttachmentQueryRequest`
|
||||
|
||||
- [ ] **Step 5: 运行测试并确认通过**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysAttachmentComponentStructureTests" test`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/main/java/com/bruce/common/controller/SysAttachmentController.java src/main/java/com/bruce/common/service/ISysAttachmentService.java src/main/java/com/bruce/common/service/impl/SysAttachmentServiceImpl.java src/main/java/com/bruce/common/dto/request/SysAttachmentUploadRequest.java src/main/java/com/bruce/common/dto/request/SysAttachmentQueryRequest.java src/main/java/com/bruce/common/dto/response/SysAttachmentResponse.java src/test/java/com/bruce/common/attachment/SysAttachmentComponentStructureTests.java
|
||||
git commit -m "refactor: 调整附件接口为DTO模式"
|
||||
```
|
||||
|
||||
### Task 4: 重构 rag_store 与 rag_document 模块为 DTO 入参与 DTO 返回
|
||||
|
||||
**Files:**
|
||||
- Create: `src/main/java/com/bruce/rag/dto/request/RagStoreQueryRequest.java`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/request/RagStoreSaveRequest.java`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/request/RagDocumentQueryRequest.java`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/request/RagDocumentSaveRequest.java`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/response/RagStoreResponse.java`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/response/RagDocumentResponse.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/controller/RagStoreController.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/controller/RagDocumentController.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/service/IRagStoreService.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/service/IRagDocumentService.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/service/impl/RagStoreServiceImpl.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/service/impl/RagDocumentServiceImpl.java`
|
||||
- Modify: `src/test/java/com/bruce/rag/RagComponentStructureTests.java`
|
||||
|
||||
- [ ] **Step 1: 写失败测试，固定 RAG 控制器和服务都使用 DTO**
|
||||
|
||||
示例断言：
|
||||
|
||||
```java
|
||||
Method storeListMethod = RagStoreController.class.getMethod("list", RagStoreQueryRequest.class);
|
||||
Method documentListMethod = RagDocumentController.class.getMethod("list", RagDocumentQueryRequest.class);
|
||||
assertEquals(RequestResult.class, storeListMethod.getReturnType());
|
||||
assertEquals(RequestResult.class, documentListMethod.getReturnType());
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行测试并确认失败**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=RagComponentStructureTests" test`
|
||||
|
||||
Expected: FAIL，提示控制器和 service 仍然暴露实体或无 DTO。
|
||||
|
||||
- [ ] **Step 3: 新增 RAG DTO**
|
||||
|
||||
`RagStoreQueryRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class RagStoreQueryRequest {
|
||||
private String storeCode;
|
||||
private String storeName;
|
||||
private String status;
|
||||
}
|
||||
```
|
||||
|
||||
`RagStoreResponse.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class RagStoreResponse {
|
||||
private Long id;
|
||||
private String storeCode;
|
||||
private String storeName;
|
||||
private String description;
|
||||
private String status;
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
`RagDocumentQueryRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class RagDocumentQueryRequest {
|
||||
private Long storeId;
|
||||
private Long attachmentId;
|
||||
private String parseStatus;
|
||||
private String indexStatus;
|
||||
private Boolean enabled;
|
||||
}
|
||||
```
|
||||
|
||||
`RagDocumentResponse.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class RagDocumentResponse {
|
||||
private Long id;
|
||||
private Long storeId;
|
||||
private Long attachmentId;
|
||||
private String documentTitle;
|
||||
private String documentSummary;
|
||||
private String parseStatus;
|
||||
private String indexStatus;
|
||||
private Boolean enabled;
|
||||
private String errorMessage;
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 修改 RAG service/controller**
|
||||
|
||||
- `IRagStoreService`、`IRagDocumentService` 返回 DTO
|
||||
- `RagStoreController` 和 `RagDocumentController` 返回 `RequestResult`
|
||||
- 查询接口改为 `@PostMapping("/query")` + `@RequestBody QueryRequest`
|
||||
|
||||
- [ ] **Step 5: 运行测试并确认通过**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=RagComponentStructureTests" test`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/main/java/com/bruce/rag/controller/RagStoreController.java src/main/java/com/bruce/rag/controller/RagDocumentController.java src/main/java/com/bruce/rag/service/IRagStoreService.java src/main/java/com/bruce/rag/service/IRagDocumentService.java src/main/java/com/bruce/rag/service/impl/RagStoreServiceImpl.java src/main/java/com/bruce/rag/service/impl/RagDocumentServiceImpl.java src/main/java/com/bruce/rag/dto/request src/main/java/com/bruce/rag/dto/response src/test/java/com/bruce/rag/RagComponentStructureTests.java
|
||||
git commit -m "refactor: 调整RAG接口为DTO模式"
|
||||
```
|
||||
|
||||
### Task 5: 全量验证与整理
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/test/java/com/bruce/common/attachment/SysAttachmentComponentStructureTests.java`
|
||||
- Modify: `src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java`
|
||||
- Modify: `src/test/java/com/bruce/rag/RagComponentStructureTests.java`
|
||||
|
||||
- [ ] **Step 1: 运行定向测试，确认三块 DTO 改造都覆盖到**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysAttachmentComponentStructureTests,SysEnumComponentStructureTests,RagComponentStructureTests" test`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 2: 运行全量测试**
|
||||
|
||||
Run: `.\mvnw.cmd test`
|
||||
|
||||
Expected: `BUILD SUCCESS`
|
||||
|
||||
- [ ] **Step 3: 检查工作区**
|
||||
|
||||
Run: `git status --short`
|
||||
|
||||
Expected: 仅显示本次预期文件，或为空（若已提交）。
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add src/test/java/com/bruce/common/attachment/SysAttachmentComponentStructureTests.java src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java src/test/java/com/bruce/rag/RagComponentStructureTests.java
|
||||
git commit -m "test: 校验DTO接口改造结构"
|
||||
```
|
||||
Reference in New Issue
Block a user