猴哥博客实战：5步图解原理，告别Stack Trace报错

盯着屏幕上滚动的红色 StackTrace，是不是脑子瞬间一片空白？那行 java.lang.NullPointerException 像天书一样，根本看不出哪行代码在“作妖”。别慌，这不是你的错，是传统调试方式太反人类。

今天咱们不背八股文，直接上手搭建【猴哥博客】。通过这个项目，用图解原理的方式，把后端开发中那些看不见的内存交互、请求流转，彻底拆解清楚。你不需要死记硬背，只要跟着代码跑一遍，那些晦涩的报错逻辑，立马变成你能看懂的流程图。

项目目标：不只是跑通，更要懂“为什么”

很多新手做博客项目，目标是“能显示文章列表”、“能发表评论”。这没错，但太浅了。

【猴哥博客】的目标设定得更硬核一点：构建一个可复现、可调试、原理透明的小型后端服务。

我们选择 Java + Spring Boot + MySQL 这套经典组合。为什么？因为它是目前就业市场的主力，也是报错最多、最让人头疼的技术栈之一。攻克它，其他语言也就通了。

核心目标有三个：

极简闭环：实现用户注册、登录、发布文章、查看列表四大核心功能。
错误可视化：通过自定义异常处理和日志打印，让每一个 Exception 都能追溯到具体业务逻辑。
图解思维：在每个关键步骤，我都会用文字描述数据流动的路径，帮助你在脑海中建立“图”，而不是“代码块”。

别小看这个“图”。当你遇到 500 Internal Server Error 时，如果你脑子里有一张从 Controller 到 Service 再到 DAO 的链路图，你就能立刻判断问题出在哪一层，而不是盲目地加 try-catch 吞掉异常。

目录结构：代码即文档，结构即逻辑

打开 IDE，新建一个 Spring Boot 项目。不要一上来就写业务代码，先看目录结构。好的目录结构，就是代码的“地图”。

com.houge.blog
├── BlogApplication.java      # 启动类
├── config
│   └── WebConfig.java        # 全局配置，如跨域、拦截器
├── controller
│   ├── UserController.java   # 用户接口
│   └── ArticleController.java# 文章接口
├── service
│   ├── UserService.java      # 用户业务逻辑
│   ├── ArticleService.java   # 文章业务逻辑
│   └── impl
│       ├── UserServiceImpl.java
│       └── ArticleServiceImpl.java
├── mapper
│   ├── UserMapper.java       # MyBatis 或 JPA 接口
│   └── ArticleMapper.java
├── entity
│   ├── User.java             # 用户实体
│   └── Article.java          # 文章实体
└── exception├── GlobalExceptionHandler.java # 全局异常处理器└── BizException.java     # 自定义业务异常

注意看 exception 包。这是解决“报错看不懂”的关键。很多项目里，异常处理是散落在各个 Service 里的 try-catch，导致日志碎片化，排查困难。我们将所有异常统一收口到 GlobalExceptionHandler，这样无论哪一层抛出异常，都能被统一格式化输出。

再注意 mapper 包。如果你用的是 MyBatis，这里放接口；如果是 JPA，这里放 Repository。无论哪种，核心思想都是：数据访问层与业务逻辑层分离。

核心代码实现：逐行拆解请求生命周期

接下来是重头戏。我们以“发布文章”为例，走一遍完整链路。

1. 定义实体与映射

先定义 Article 实体。不要偷懒，加上必要的校验注解。

package com.houge.blog.entity;import jakarta.persistence.*;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import lombok.Data;
import java.time.LocalDateTime;@Data
@Entity
@Table(name = "t_article")
public class Article {@Id@GeneratedValue(strategy = GenerationType.IDENTITY)private Long id;@NotBlank(message = "标题不能为空")@Size(max = 100, message = "标题不能超过100字")private String title;@NotBlank(message = "内容不能为空")private String content;private Long authorId;@Column(updatable = false)private LocalDateTime createTime;@PrePersistpublic void prePersist() {this.createTime = LocalDateTime.now();}
}

图解原理时刻： @NotBlank 和 @Size 是 Bean Validation 注解。当请求进入 Controller 时，Spring 会自动触发校验。如果校验失败，抛出的不是普通的 Exception，而是 ConstraintViolationException。这是第一道防线，能在数据入库前拦截脏数据。

2. 业务逻辑层 (Service)

ArticleServiceImpl.java 中，我们处理核心业务。

package com.houge.blog.service.impl;import com.houge.blog.entity.Article;
import com.houge.blog.exception.BizException;
import com.houge.blog.mapper.ArticleMapper;
import com.houge.blog.service.ArticleService;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;import java.time.LocalDateTime;@Service
@RequiredArgsConstructor
public class ArticleServiceImpl implements ArticleService {private final ArticleMapper articleMapper;@Override@Transactionalpublic Article publishArticle(String title, String content, Long authorId) {// 1. 业务校验：检查用户是否存在if (authorId == null) {throw new BizException(4001, "用户未登录或不存在");}// 2. 数据封装Article article = new Article();article.setTitle(title);article.setContent(content);article.setAuthorId(authorId);// 3. 持久化article = articleMapper.save(article);return article;}
}

避坑指南：注意 @Transactional 注解。如果 articleMapper.save 抛出异常，事务会回滚。但如果你在这里 try-catch 吞掉了异常，事务就不会回滚，导致数据不一致。所以，不要在 Service 层捕获非预期异常，让它抛出去，交给全局处理器。

BizException 是我们自定义的异常，携带业务错误码和消息。

package com.houge.blog.exception;import lombok.Getter;@Getter
public class BizException extends RuntimeException {private final int code;private final String message;public BizException(int code, String message) {super(message);this.code = code;this.message = message;}
}

3. 全局异常处理：让报错“说人话”

这是解决 StackTrace 恐惧症的核心。

package com.houge.blog.exception;import com.houge.blog.dto.Result;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;import java.util.stream.Collectors;@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {// 处理业务异常@ExceptionHandler(BizException.class)public Result<?> handleBizException(BizException e) {log.warn("业务异常: code={}, msg={}", e.getCode(), e.getMessage());return Result.error(e.getCode(), e.getMessage());}// 处理参数校验异常@ExceptionHandler(MethodArgumentNotValidException.class)public Result<?> handleValidException(MethodArgumentNotValidException e) {String msg = e.getBindingResult().getFieldErrors().stream().map(err -> err.getField() + ": " + err.getDefaultMessage()).collect(Collectors.joining("; "));log.warn("参数校验失败: {}", msg);return Result.error(400, msg);}// 兜底处理@ExceptionHandler(Exception.class)public Result<?> handleException(Exception e) {log.error("系统未知异常", e); // 这里打印完整 StackTrace，方便后端排查return Result.error(500, "系统繁忙，请稍后再试");}
}

图解原理时刻：请求进来 → Controller 接收 → Service 处理 → 如果抛 BizException → 被 handleBizException 捕获 → 返回友好 JSON。如果抛未知异常 → 被 handleException 捕获 → 日志打印完整堆栈（后端看日志，前端看友好提示）→ 返回 500 提示。

这样，前端永远看到的是 "msg": "标题不能为空"，而不是满屏的 NullPointerException。后端通过日志里的 log.error 定位问题。前后端解耦，各自安好。

4. Controller 层：简单直接

package com.houge.blog.controller;import com.houge.blog.dto.Result;
import com.houge.blog.entity.Article;
import com.houge.blog.service.ArticleService;
import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("/api/article")
@RequiredArgsConstructor
public class ArticleController {private final ArticleService articleService;@PostMapping("/publish")public Result<Article> publish(@RequestBody @Validated PublishDTO dto, @RequestHeader("Authorization") String token) {// 简化处理，实际应通过 Token 解析用户 IDLong userId = 1L; Article article = articleService.publishArticle(dto.getTitle(), dto.getContent(), userId);return Result.success(article);}
}

注意 @Validated 注解。它触发了前面提到的 Bean Validation。如果 DTO 里的字段为空，直接返回 400，不会进入 Service 层，性能更高，逻辑更清晰。

运行与测试：从黑盒到白盒

代码写完了，怎么验证？不要只依赖 Postman 点一下。

启动服务：运行 BlogApplication。看到 Started BlogApplication 日志，说明服务起来了。
构造测试数据：
- 用 Postman 发送 POST /api/article/publish。
- Body 填入 {"title": "测试", "content": "内容"}。
- Header 添加 Authorization: dummy-token。
观察结果：
- 正常情况：返回 {"code": 200, "data": {...}}。
- 故意报错：把 title 删掉。
- 观察响应：返回 {"code": 400, "msg": "title: 标题不能为空"}。
- 观察后端日志：你会看到 WARN 参数校验失败: title: 标题不能为空。

关键步骤：现在，故意在 Service 层抛一个 RuntimeException。

前端：收到 {"code": 500, "msg": "系统繁忙"}。
后端日志：打印出完整的 StackTrace，包含行号、调用栈。

这时候，你再去看 StackTrace，是不是清晰多了？你知道了异常发生在 ArticleServiceImpl.java:25，是 articleMapper.save 抛出的。你可以顺着这个线索，去查数据库连接、SQL 语句，而不是在代码里瞎猜。

可信来源：这种全局异常处理模式，在 Spring 官方文档的 Error Handling 章节中有详细说明。同时，参考 GitHub 开源仓库 spring-projects/spring-boot 中的 ErrorController 实现，可以发现 Spring 默认的错误处理也是基于这种“统一出口”的思路。我们的实现只是更贴合业务场景，将错误码和消息结构化。

优化扩展：从能用到好用

项目跑通了，别急着收工。还有几个进阶点，能大幅提升工程质量。

日志脱敏：在 GlobalExceptionHandler 中，打印 log.error 时，避免打印敏感信息（如密码、身份证）。可以使用 Lombok 的 @Slf4j 配合 MDC（Mapped Diagnostic Context），在日志中自动带上 TraceId，方便链路追踪。
接口幂等性：发布文章接口，如果用户网络抖动，点击了两次“发布”，会产生两篇重复文章。解决方案：在 Controller 层加一个 @Idempotent 注解，基于 Token 或请求 ID 做缓存判断，短时间内重复请求直接返回第一次的结果。
性能监控：引入 Micrometer + Prometheus。在 config 包下添加配置，监控接口的 QPS、RT（响应时间）。当某个接口 RT 突然飙升，你能在监控面板上看到，而不是等用户投诉。
代码规范：使用 Checkstyle 或 SpotBugs 在 CI/CD 流程中检查代码质量。避免 System.out.println、空 catch 块等坏味道。