围成语实战速查手册：告别StackTrace报错

刚拿到“围成语”实战项目的代码，是不是直接运行就崩了？满屏红色的 StackTrace 像天书一样滚过去，头都大了。别慌，这正是大多数开发者卡在起步期的原因。今天这份速查手册，就是为了解决这个痛点。我们不讲虚的，直接上干货，带你从零把这个项目跑通，并且看懂每一行代码背后的逻辑。

项目目标：不只是跑通，更要懂透

很多人做实战项目，目标是“能跑就行”。但在市政公用工程这类严谨领域，代码的可维护性和稳定性才是核心。我们定义的“围成语”实战项目，模拟的是一个小型的市政设施巡检数据管理模块。

核心目标有三个：

1. 数据闭环：实现巡检数据的录入、校验、存储和查询。
2. 异常兜底：当输入数据不合法或数据库连接失败时，系统不能直接崩溃，而要给出友好的错误提示。
3. 性能基线：单次查询响应时间控制在 200ms 以内，保证在前端界面上操作流畅。

为什么强调异常处理？因为在 Stack Overflow 上，关于 NullPointerException 或 ConnectionRefused 的问题常年霸榜。90% 的初级开发者，死在不会优雅地处理错误上。这个项目，就是练这个“肌肉记忆”。

目录结构：清晰即正义

在写第一行代码前，先把骨架搭好。混乱的目录结构是后期维护的噩梦。我们采用标准的分层架构，但针对小型项目做了精简。

project-wei-yu/
├── src/
│   ├── main/
│   │   ├── java/com/municipal/inspector/
│   │   │   ├── config/       # 配置类：数据库、日志
│   │   │   ├── controller/   # 控制层：接收HTTP请求
│   │   │   ├── service/      # 业务层：核心逻辑
│   │   │   ├── repository/   # 数据层：JPA/MyBatis接口
│   │   │   ├── model/        # 实体类：数据库映射
│   │   │   └── exception/    # 异常处理：全局异常捕获
│   │   └── resources/
│   │       ├── application.yml # 配置文件
│   │       └── mapper/         # SQL映射文件
│   └── test/                 # 单元测试
├── pom.xml                   # Maven依赖
└── README.md

关键点解析：

• config 包：不要把所有配置写死在代码里。application.yml 里放数据库账号密码、日志级别。
• exception 包：这是本次重点。我们需要一个全局异常处理器，把底层的技术错误转换成用户能看懂的业务错误。
• model 包：严格区分 DTO（数据传输对象）和 Entity（数据库实体）。前端传进来的参数，不要直接丢给数据库，防止恶意篡改。

核心代码实现：逐行拆解

1. 定义数据模型与校验

首先，我们定义一个巡检记录实体。注意看 @Valid 和 @NotNull 注解，这是防止垃圾数据入库的第一道防线。

package com.municipal.inspector.model;import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Table;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;@Entity
@Table(name = "inspection_record")
public class InspectionRecord {@Idprivate Long id;// 设施编号，不能为空，长度限制20@NotNull(message = "设施编号不能为空")@Size(max = 20, message = "设施编号长度不能超过20位")private String facilityCode;// 巡检结果：1-正常, 2-故障private Integer status;// 备注信息private String remark;// Getter/Setter 省略
}

2. Service 层：业务逻辑与异常抛出

在 Service 层，我们处理核心业务。这里有一个常见的坑：当设施编号不存在时，直接返回 null 会导致后续代码报 NullPointerException。正确的做法是抛出明确的业务异常。

package com.municipal.inspector.service;import com.municipal.inspector.exception.BusinessException;
import com.municipal.inspector.model.InspectionRecord;
import com.municipal.inspector.repository.InspectionRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;@Service
public class InspectionService {@Autowiredprivate InspectionRepository repo;/*** 创建巡检记录* @param record 巡检数据* @return 保存后的记录*/@Transactionalpublic InspectionRecord createRecord(InspectionRecord record) {// 1. 校验设施是否存在（假设通过另一个服务查询，这里简化）if (record.getFacilityCode() == null || record.getFacilityCode().isEmpty()) {throw new BusinessException("BIZ_001", "设施编号无效");}// 2. 执行保存InspectionRecord saved = repo.save(record);return saved;}/*** 根据ID查询记录* @param id 记录ID* @return 巡检记录*/public InspectionRecord getById(Long id) {InspectionRecord record = repo.findById(id).orElseThrow(() -> new BusinessException("BIZ_404", "记录不存在: ID=" + id));return record;}
}

逐行讲解：

• @Transactional：保证数据一致性。如果保存失败，整个事务回滚，避免产生脏数据。
• orElseThrow：这是 Java Optional 类的经典用法。不要写成 if (record == null) throw ...，这样更函数式，也更简洁。
• BusinessException：自定义异常。它继承自 RuntimeException，但携带了错误码和消息。这样前端可以根据错误码做不同的提示。

3. 全局异常处理：StackTrace 的终结者

这是解决“报错一堆看不懂”的核心。我们在 Controller 层或者全局配置一个 @ControllerAdvice。

package com.municipal.inspector.exception;import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;import java.util.HashMap;
import java.util.Map;@RestControllerAdvice
public class GlobalExceptionHandler {// 处理业务异常@ExceptionHandler(BusinessException.class)@ResponseStatus(HttpStatus.BAD_REQUEST)public Map<String, Object> handleBusinessException(BusinessException ex) {Map<String, Object> error = new HashMap<>();error.put("code", ex.getCode());error.put("message", ex.getMessage());// 生产环境不要返回详细的 stack trace，防止泄露源码error.put("timestamp", System.currentTimeMillis());return error;}// 处理参数校验异常@ExceptionHandler(MethodArgumentNotValidException.class)@ResponseStatus(HttpStatus.BAD_REQUEST)public Map<String, Object> handleValidationException(MethodArgumentNotValidException ex) {Map<String, Object> error = new HashMap<>();error.put("code", "VALIDATION_ERROR");// 提取第一个错误消息String message = ex.getBindingResult().getFieldErrors().get(0).getDefaultMessage();error.put("message", message);return error;}// 兜底：处理所有未知异常@ExceptionHandler(Exception.class)@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)public Map<String, Object> handleException(Exception ex) {// 日志记录详细堆栈，方便排查log.error("Unexpected error", ex);Map<String, Object> error = new HashMap<>();error.put("code", "SERVER_ERROR");error.put("message", "系统繁忙，请稍后重试");return error;}
}

为什么这样写？

1. 分层响应：业务错误返回 400，服务器内部错误返回 500。前端可以根据 HTTP 状态码决定是弹窗提示还是跳转错误页。
2. 信息脱敏：handleException 中，我们只记录日志，不向前端暴露 ex.printStackTrace() 的内容。这是安全规范，也是 Stack Overflow 上多位资深架构师强烈建议的做法。
3. 统一格式：无论哪种错误，返回给前端的 JSON 结构保持一致（code, message）。前端解析逻辑只需写一次。

运行与测试：验证闭环

代码写完了，怎么证明它是对的？靠猜是不行的。

1. 启动服务

确保 application.yml 中数据库配置正确：

spring:datasource:url: jdbc:mysql://localhost:3306/municipal_db?useSSL=falseusername: rootpassword: 123456jpa:hibernate:ddl-auto: updateshow-sql: true # 开发阶段打开，看SQL执行

执行 mvn spring-boot:run，看到 Started InspectorApplication 即成功。

2. 模拟异常场景测试

使用 Postman 或 Curl 发送请求，故意触发错误。

场景一：参数缺失

curl -X POST http://localhost:8080/api/inspections \
-H "Content-Type: application/json" \
-d '{"facilityCode": "", "status": 1}'

预期结果：

{"code": "VALIDATION_ERROR","message": "设施编号不能为空","timestamp": 1718000000000
}

如果这里报 500 错误，检查 @Valid 注解是否加在 Controller 参数上。

场景二：查询不存在的ID

curl -X GET http://localhost:8080/api/inspections/99999

预期结果：

{"code": "BIZ_404","message": "记录不存在: ID=99999","timestamp": 1718000001000
}

如果这里报 500 错误，检查 GlobalExceptionHandler 是否被 Spring 扫描到（通常在主启动类同级或子包下）。

3. 单元测试：防止回归

写一个简单的 Service 层测试，确保核心逻辑不被后续修改破坏。

@Test
public void testCreateRecordWithNullCode() {InspectionRecord record = new InspectionRecord();record.setFacilityCode(null); // 故意设置nulltry {inspectionService.createRecord(record);fail("应该抛出 BusinessException");} catch (BusinessException e) {assertEquals("BIZ_001", e.getCode());}
}

优化扩展：从能用好用

项目跑通了，但离生产环境还有距离。这里有几个进阶技巧，能让你的代码更健壮。

1. 日志规范：别用 System.out.println

很多新人喜欢用 System.out.println 调试。这在生产环境是灾难。请使用 SLF4J + Logback。

private static final Logger log = LoggerFactory.getLogger(InspectionService.class);public InspectionRecord createRecord(InspectionRecord record) {log.info("Creating inspection for facility: {}", record.getFacilityCode());// ...log.debug("Saved record with ID: {}", saved.getId());return saved;
}

• info：关键业务节点，如“订单创建成功”。
• debug：详细参数，生产环境通常关闭。
• error：异常堆栈，必须带上异常对象 ex。

2. 数据库索引优化

如果 facilityCode 是高频查询字段，务必建立索引。在 JPA 实体中添加：

@Entity
@Table(name = "inspection_record", indexes = {@Index(name = "idx_facility_code", columnList = "facilityCode")
})
public class InspectionRecord { ... }

否则，当数据量达到百万级时，查询时间会从毫秒级飙升到秒级，前端直接超时。

3. 接口幂等性

在网络抖动时，前端可能重复发送请求。对于 createRecord 接口，可以引入 Redis 分布式锁或数据库唯一键约束，防止重复插入。

小结：把报错变成朋友

回顾整个项目，我们从目录结构到异常处理，核心其实就一点：不要害怕报错，要驯服报错。

• StackTrace 不是敌人，它是线索。
• 全局异常处理器是你的盾牌，挡住杂乱的技术细节，给用户清晰的反馈。
• 日志是你的眼睛，在无声的生产环境中记录一切。

这份速查手册里的代码片段，你可以直接复制到你的项目中。建议你先手动敲一遍，而不是复制粘贴。只有亲手敲过，遇到 MethodArgumentNotValidException 时，你才会下意识地去查全局异常配置，而不是对着屏幕发呆。

编程是一场长跑，工具链和习惯比单次代码更重要。希望这个“围成语”实战项目能成为你构建良好开发习惯的起点。

你更常用哪种异常处理写法？是倾向于在每个方法里 try-catch，还是像我这样集中管理？或者你有更好的日志规范建议？评论区交流，咱们一起避坑。