这是「从零手写一个博客系统」系列的第一篇。整个项目基于 Spring Boot 4.x + MyBatis-Plus + MySQL + JWT 完成,从后端骨架搭建,到登录认证,再到数据层踩坑与上线部署,我会分成三篇讲清楚。本文先讲最基础但也最容易忽略的部分:分层架构、统一响应格式、全局异常处理。
一、引言
很多初学 Spring Boot 的同学,跟着教程能跑通 demo,但一旦自己从零搭项目,就不知道"代码该放哪、接口该返回什么、报错了怎么办"。这个博客系统是我自己动手写出来的,踩了不少坑,也把这些"工程上的基本功"理清了。
博客系统最核心的功能就是:登录、发文章、看文章、改文章、删文章。麻雀虽小,五脏俱全------它涵盖了认证、数据库操作、统一响应、异常处理这些后端开发绕不开的环节。
先看最终效果:未登录的访客只能看文章列表和全文;登录后(管理员)才能发文章、编辑、删除。这一篇不涉及认证,先把"地基"打好。
二、技术栈
| 技术 | 版本 | 作用 |
|---|---|---|
| Spring Boot | 4.1.1 | 核心框架 |
| Java | 17 | 语言 |
| MyBatis-Plus | 3.5.x | ORM 框架,简化数据库操作 |
| MySQL | 8.0 | 数据库 |
| JJWT | 0.11.5 | JWT 令牌签发与校验 |
| Lombok | --- | 消除样板代码 |
| HikariCP | --- | 数据库连接池(Spring Boot 默认) |
三、数据库设计
这个系统就两张表:用户表 user_info 和博客表 blog_info。
sql
-- 用户表
CREATE TABLE user_info (
id INT NOT NULL AUTO_INCREMENT,
user_name VARCHAR(128) NOT NULL,
password VARCHAR(128) NOT NULL, -- 盐值 + MD5 加密后的密文
github_url VARCHAR(128) DEFAULT NULL,
delete_flag TINYINT DEFAULT '0', -- 逻辑删除标记
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (id),
UNIQUE KEY user_name_UNIQUE (user_name)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 博客表
CREATE TABLE blog_info (
id INT NOT NULL AUTO_INCREMENT,
title VARCHAR(200) DEFAULT NULL,
content TEXT, -- 正文(Markdown)
user_id INT DEFAULT NULL, -- 作者 id
delete_flag TINYINT DEFAULT '0',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
两个值得注意的设计点:
delete_flag逻辑删除字段 :删除文章不是真的 DELETE,而是把delete_flag置为 1,查询时过滤掉。这样数据可恢复、可追溯。create_time/update_time依赖数据库默认值 :DEFAULT CURRENT_TIMESTAMP和ON UPDATE CURRENT_TIMESTAMP,插入和更新时不用手动赋值,数据库自动搞定。
四、分层架构
项目采用经典的三层架构,外加 DTO/VO 隔离:
plaintext
Controller(接收请求、参数校验)
↓
Service(业务逻辑)
↓
Mapper(MyBatis-Plus 数据访问,继承 BaseMapper)
↓
数据库
同时,实体类不直接暴露给前端,而是做了三层拆分:
| 包 | 类 | 作用 |
|---|---|---|
| pojo.dataobject | BlogInfo、UserInfo | 实体,与表一一对应 |
| pojo.request | AddBlogRequest 等 | 入参 DTO |
| pojo.response | BlogInfoResponse 等 | 出参 VO |
为什么要拆?一个关键原因:UserInfo 实体里有 password 字段,而返回给前端的 UserInfoResponse 里没有 password。通过 VO 隔离,密码永远不会被序列化出去,这是数据安全的基本功。
五、统一响应格式(本项目的精华之一)
前后端分离开发,接口返回格式不统一是灾难。有的接口返回 true,有的返回对象,有的返回字符串,前端就得写一堆判断。
所以第一步:定义统一的响应体。
1. 响应体 Result
java
import lombok.Data;
@Data
public class Result {
private ResultCodeEnum code; // 业务状态码,注意不是 HTTP 状态码
private String errMsg; // 错误信息
private Object data; // 数据
// 成功
public static Result success(Object data) {
Result result = new Result();
result.setCode(ResultCodeEnum.SUCCESS);
result.setData(data);
return result;
}
// 失败
public static Result fail(String errMsg) {
Result result = new Result();
result.setCode(ResultCodeEnum.FAIL);
result.setErrMsg(errMsg);
return result;
}
}
2. 状态码枚举
java
public enum ResultCodeEnum {
SUCCESS(200),
FAIL(-1);
private final int code;
ResultCodeEnum(int code) {
this.code = code;
}
public int getCode() {
return code;
}
}
这里有个容易混淆的点:code 是业务状态码,不是 HTTP 状态码。比如"密码错误"这个业务失败,HTTP 层面可能还是 200,但业务 code 是 FAIL,靠 errMsg 告诉前端具体错误。
3. 统一包装 ResponseAdvice
定义了 Result,但不可能在每个 Controller 方法里手动包一遍 Result.success(...),太啰嗦。用 Spring 的 ResponseBodyAdvice 统一处理:
java
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;
@RestControllerAdvice
public class ResponseAdvice implements ResponseBodyAdvice<Object> {
@Autowired
private ObjectMapper objectMapper;
@Override
public boolean supports(MethodParameter returnType, Class converterType) {
return true; // 对所有接口生效
}
@Override
public Object beforeBodyWrite(Object body,
MethodParameter returnType,
MediaType selectedContentType,
Class selectedConverterType,
ServerHttpRequest request,
ServerHttpResponse response) {
// 关键:返回值是 String 时,要先转成 JSON 字符串,否则会类型转换报错
if (body instanceof String) {
try {
return objectMapper.writeValueAsString(Result.success(body));
} catch (JsonProcessingException e) {
throw new RuntimeException(e);
}
}
// 已经是 Result 就不重复包装
if (body instanceof Result) {
return body;
}
return Result.success(body);
}
}
核心机制:beforeBodyWrite 在 Controller 方法返回后、JSON 序列化之前执行,把返回值统一包成 Result.success(...)。
这样,Controller 里写业务代码时,直接返回对象就行,框架会自动包一层:
java
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
@RestController
@RequestMapping("/blog")
public class BlogController {
@RequestMapping("/getList")
public List<BlogInfoResponse> getList() {
return blogService.getList(); // 自动变成 {"code":"SUCCESS","data":[...]}
}
}
前端拿到的就是统一的 {code, errMsg, data} 结构。
六、全局异常处理
接口写好了,但运行时报错怎么办?如果每个方法都 try-catch,代码会爆炸。用 @RestControllerAdvice 集中处理。
1. 自定义业务异常
java
import lombok.Data;
import lombok.EqualsAndHashCode;
@Data
@EqualsAndHashCode(callSuper = true)
public class BlogException extends RuntimeException {
private int code;
private String errMsg;
public BlogException(String errMsg) {
super(errMsg); // 让异常的 message 也带上错误信息
this.errMsg = errMsg;
}
}
业务逻辑里,遇到"用户不存在""密码错误"这种,直接 throw new BlogException("用户不存在"),不用层层返回。
2. 全局异常处理器
java
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;
@Slf4j
@RestControllerAdvice
public class ExceptionAdvice {
// 业务异常
@ExceptionHandler(BlogException.class)
public Result handler(BlogException e) {
log.error("业务异常:", e);
return Result.fail(e.getMessage());
}
// 参数校验异常(@Validated 触发)
@ExceptionHandler(MethodArgumentNotValidException.class)
public Result handler(MethodArgumentNotValidException e) {
String msg = e.getBindingResult().getAllErrors().get(0).getDefaultMessage();
return Result.fail(msg);
}
// 兜底异常
@ExceptionHandler(Exception.class)
public Result handler(Exception e) {
log.error("系统异常:", e);
return Result.fail(e.getMessage());
}
}
这样,不管哪一层抛异常,都会被统一捕获,返回格式一致的 Result.fail(msg)。前端只认 errMsg 这一个字段。
七、参数校验
入参的合法性校验,交给 jakarta.validation 注解,而不是手写 if 判断:
java
import jakarta.validation.constraints.NotNull;
import lombok.Data;
@Data
public class AddBlogRequest {
@NotNull(message = "标题不可以是空的")
private String title;
@NotNull(message = "内容不可以是空的")
private String content;
@NotNull(message = "userId 不可以为空")
private Integer userId;
}
Controller 方法参数加 @Validated 触发校验,校验失败会抛 MethodArgumentNotValidException,被上面第六节的异常处理器统一接住,返回第一条错误信息:
java
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/blog")
public class BlogController {
@PostMapping("/add")
public Boolean add(@Validated @RequestBody AddBlogRequest request) {
blogService.add(request);
return true; // 会被 ResponseAdvice 自动包成 Result.success(true)
}
}
八、小结
这一篇把博客系统的"地基"打好了:
- 数据库设计:两张表 + 逻辑删除 + 时间自动填充
- 分层架构:Controller → Service → Mapper,加 DTO/VO 隔离(防止密码泄露)
- 统一响应 :Result + ResponseBodyAdvice 自动包装,前端只认
{code, errMsg, data} - 全局异常:@RestControllerAdvice 集中处理,业务异常 + 参数校验异常 + 兜底异常
- 参数校验:jakarta.validation 注解 + @Validated
这些都是后端开发的基本功,但很多教程一笔带过,实际自己搭项目时才会意识到它们的重要性。