从零手写博客系统:分层架构与统一响应(一)

这是「从零手写一个博客系统」系列的第一篇。整个项目基于 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;

两个值得注意的设计点:

  1. delete_flag 逻辑删除字段 :删除文章不是真的 DELETE,而是把 delete_flag 置为 1,查询时过滤掉。这样数据可恢复、可追溯。
  2. 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)
    }
}

八、小结

这一篇把博客系统的"地基"打好了:

  1. 数据库设计:两张表 + 逻辑删除 + 时间自动填充
  2. 分层架构:Controller → Service → Mapper,加 DTO/VO 隔离(防止密码泄露)
  3. 统一响应 :Result + ResponseBodyAdvice 自动包装,前端只认 {code, errMsg, data}
  4. 全局异常:@RestControllerAdvice 集中处理,业务异常 + 参数校验异常 + 兜底异常
  5. 参数校验:jakarta.validation 注解 + @Validated

这些都是后端开发的基本功,但很多教程一笔带过,实际自己搭项目时才会意识到它们的重要性。

相关推荐
练习两年半的攻城狮14 分钟前
企业级 AI Agent 架构知识点讲解(一):从知识型到业务型,从 LangGraph 到生产落地
人工智能·架构
the局外人15 分钟前
Python 实战检索优化:BM25、向量与重排
数据库·后端·python
得物技术38 分钟前
从研发经验到团队知识:Akashic知识工程实践|得物技术
数据库·程序员·架构
Cosolar1 小时前
拆开「研发数字人」:一个 Agent 系统真正的护城河,是被结构化的判断力
人工智能·后端·架构
ClouGence1 小时前
开源数据库管理工具 CloudDM 发布新版本,支持 GreptimeDB 数据源
数据库·kafka
Rain的Java大神之路1 小时前
LeetCode 40 组合总和 II:面试官想听的不是回溯,而是那行去重代码
java·leetcode·面试
wno7042 小时前
Centos下PostgreSQL安装部署详细步骤
java·数据库·spring boot
AAA修煤气灶刘哥2 小时前
一个人用 Agent 写代码,和整个团队一起用,差在哪?拆解腾讯 LoopForge
架构
文丑颜不良啊2 小时前
InnoDB 和 MyISAM
数据库