Luckean's blog

Appearance

10：正式项目需求开发、测试与排错 ​

1. 从 Demo 进入正式项目的正确方式 ​

第一次改正式 CRM，不要选“客户新增联动跟进、合同、流程”的需求。优先选：

  • 在已有列表增加一个简单展示字段；
  • 给已有详情增加一个只读字段；
  • 增加一个已有表的筛选条件；
  • 修复一个单表的校验问题；
  • 增加一个不影响旧逻辑的小型查询接口。

先熟悉协作与环境，再做复杂业务。

2. 接到需求后的标准流程 ​

text
1. 读需求：用户要看到什么、能操作什么、边界是什么
2. 找入口：前端 URL 或接口 URL 对应哪个 Controller
3. 沿调用链阅读：Controller -> Service -> Mapper/Provider -> 表
4. 找相似实现：优先复用项目已有写法
5. 列影响面：接口、Form/VO、SQL、权限、日志、测试、前端
6. 写最小实现
7. 自测正常、异常、边界数据
8. 代码 Review 后再合入

对于客户列表，入口是：

text
前端路由：/crm/customer/customer-list
前端接口：/crm/web/client/customerInfo/query/page
后端：CustomerInfoController.queryPage
服务：CustomerInfoServiceImpl.queryPage
SQL：CustomerInfoProvider.queryPageList

3. 如何快速定位代码 ​

在项目根目录使用 rg：

bash
rg -n "customerInfo/query/page|CustomerInfoController" .
rg -n "queryPage\(" hc-crm-center-service/src/main/java
rg -n "customer_name" hc-crm-center-service/src/main/java

推荐阅读顺序：

text
Controller
  -> Service 接口
  -> ServiceImpl 的目标方法
  -> Mapper
  -> Provider / XML
  -> Entity、Form、VO、DTO、Converter
  -> 关联服务和表

不要一打开就从 CustomerInfoServiceImpl 第一行读到最后一行；先用方法名定位需求相关片段。

4. 正式项目新增字段的检查单 ​

假设需求是“客户列表增加客户来源字段”，至少检查：

层要确认的内容
数据库是否已有列；没有则迁移脚本、默认值、历史数据
Entity是否需要新增字段和枚举
Form新增/编辑是否允许填写
DTO / Converter是否有字段漏传
Provider分页 SELECT 是否能查出字段
VO / QueryResult详情或列表是否要返回
Controller是否要新增校验或接口
权限字段是否敏感、是否受数据权限影响
前端表头、筛选项、展示字典
测试新增、编辑、列表、详情、旧数据兼容

字段只加在 Entity 而没加 Provider，是正式项目中最常见的“数据库有值但列表不显示”原因之一。

5. 测试层次 ​

5.1 单元测试 ​

测试纯 Java 逻辑，例如分页参数修正、枚举转换、名称去重规则。Demo 已有 PageRequestResolverTest。

5.2 Service 测试 ​

测试业务规则，例如：

  • 新增重复名称会失败；
  • 更新不存在客户会失败；
  • 保存联系人失败时事务回滚。

可使用 Mock 模拟 Mapper，也可以连接专用测试数据库。

5.3 接口测试 ​

用 MockMvc、Postman 或 curl 发送真实 HTTP 请求，验证：

  • URL、请求方式、参数位置正确；
  • JSON 能反序列化为 Form；
  • 校验错误响应正确；
  • 成功响应字段与前端约定一致。

5.4 数据库验证 ​

写操作后必须查库：

sql
SELECT * FROM demo_customer WHERE id = ?;
SELECT * FROM demo_customer_contact WHERE customer_id = ?;

接口返回成功不等于数据一定正确。

6. 常见报错排查表 ​

现象优先检查
Maven 下载父 POM 401公司网络、Maven settings.xml、私服账号；不要先改 POM
服务启动失败连不上数据库MYSQL_URL、用户名密码、端口、数据库是否存在
404Controller 包是否被扫描、URL 前缀、请求方法是否一致
400Form 字段名、JSON 格式、@Valid 校验消息
500控制台堆栈最顶部的业务异常和 SQL 异常
SQL 列不存在Entity/SQL/迁移脚本/环境数据库版本不一致
列表没有新字段Provider 的 SELECT、header、VO 或前端列配置漏改
事务没有回滚异常被吞掉、方法不是 public、同类调用绕过 Spring 代理
分页总数不对count SQL、联表重复行、分页插件、排序条件
数据看不到租户、逻辑删除、数据权限、创建人部门过滤

7. 将 Demo 逐步重构成正式目录 ​

在你完成全部练习后，可以创建第二个分支或副本，按以下方式重构：

text
my-center/
├── hc-my-demo-api/
│   └── src/main/java/com/hc/my/demo/
│       ├── form/
│       ├── vo/
│       └── enums/
└── hc-my-demo-service/
    └── src/main/java/com/hc/my/demo/
        ├── controller/web/client/
        ├── converter/
        ├── dto/
        ├── entity/
        ├── mapper/
        ├── provider/
        └── service/impl/

重构前后接口行为必须保持一致。先跑测试，再移动类和改 package；一次只移动一小组文件。

8. 你可以开始正式需求前的自检 ​

  • [ ] 能解释 API 模块和 Service 模块分别放什么；
  • [ ] 能在 10 分钟内从一个 URL 定位到 Controller、Service、Mapper；
  • [ ] 能实现单表分页、详情和 CRUD；
  • [ ] 能写 Form 校验、VO 和 Converter；
  • [ ] 能设计并验证两表事务；
  • [ ] 知道正式环境要确认租户、数据权限、逻辑删除和操作日志；
  • [ ] 知道私服 401、数据库连不上、404、SQL 错误分别如何开始排查；
  • [ ] 改代码后会执行构建、接口测试和数据库验证。

9. 下一步练习建议 ​

按以下顺序在 Demo 实现，不要一次做完：

  1. CustomerDetailVo + findById；
  2. CustomerSaveForm + /save + 名称去重；
  3. /edit、/del、/del/batch；
  4. demo_customer_contact 的 Entity、Mapper、详情聚合；
  5. 客户与联系人的事务保存；
  6. 操作日志表；
  7. 请求头模拟当前用户，只允许修改本人数据；
  8. 将 Demo 拆成 api/service 两个 Maven 模块。

每完成一个步骤都保留可运行状态。遇到问题时，带上“请求 JSON、接口响应、完整异常、相关 SQL、表结构”来排查，而不要只说“接口不通”。

Lucking

粤ICP备2022078904号-1