Blog API

基于 Spring Boot 2 构建的博客后端 REST API，支持文章管理、分类标签、评论系统、JWT 认证等核心功能。

---

技术栈

类别	技术
核心框架	Spring Boot 2.7.6
语言	Java 8
构建工具	Maven
数据库	MySQL 8.x
ORM	MyBatis 2.2.2
缓存	Spring Data Redis
认证	JJWT (JWT HS256)
对象存储	七牛云 SDK 7.12.0
日志	Log4j2
其他	Lombok、Fastjson、Joda-Time、Snowflake ID

---

项目结构

blog-api/
├── src/main/java/org/akboom/blogapi/
│   ├── aop/                # 自定义 AOP 注解与切面（缓存 & 日志）
│   ├── config/             # Jackson / 线程池 / Web & CORS 配置
│   ├── controller/         # REST API 控制器（9 个）
│   ├── dao/
│   │   ├── mapper/         # MyBatis Mapper 接口（7 个）
│   │   └── pojo/           # 数据库实体类
│   ├── handler/            # 全局异常 / 登录拦截器 / 类型转换
│   ├── service/            # 业务逻辑层（接口 + 实现）
│   ├── util/               # JWT / 七牛云 / 雪花算法 / IP 工具类
│   └── vo/                 # 请求参数 VO / 统一响应 Result / 错误码
├── src/main/resources/
│   ├── application.yml           # 主配置（激活 prod 环境）
│   ├── application-dev.yml       # 开发环境
│   ├── application-prod.yml      # 生产环境
│   ├── log4j2.xml                # 日志配置
│   └── org/.../mapper/           # MyBatis XML（7 个）
├── blog-api.sql                  # 完整数据库初始化脚本
└── pom.xml

---

核心功能

认证体系（JWT + Redis）

• 登录/注册成功后签发 JWT Token（HS256，24 小时有效）
• Token 同时写入 Redis（TTL 1 天），支持服务端主动吊销
• LoginInterceptor 拦截受保护接口，校验通过后将用户存入 ThreadLocal

密码安全

• 注册时间的 MD5 值作为独立盐（salt）
• 密码存储：MD5(password + salt)，防止彩虹表攻击

AOP 缓存（@Cache）

• 基于 Redis 的方法级返回值缓存
• Key 策略：{name}::{类名}::{方法名}::{参数MD5}
• 支持自定义 TTL；分类/标签缓存 30 分钟，文章列表缓存 1 分钟

AOP 日志（@Logging）

• 记录模块名、操作名、请求参数、客户端真实 IP（支持 Nginx 代理）、接口耗时

分布式 ID（雪花算法）

• 完整实现 Twitter Snowflake（64 位 Long）
• Long/BigInteger 统一序列化为 String，避免前端精度丢失

异步浏览量更新

• 文章浏览量通过 @Async 线程池异步更新，不阻塞读取响应
• 使用乐观锁（WHERE view_counts = #{old}）保证并发安全

评论系统

• 支持二级嵌套评论（level=1 父评论，level=2 子回复）
• MyBatis 懒加载自动装配子评论、作者、被回复用户信息
• 发布评论时原子更新文章评论计数

文件上传

• 图片上传至七牛云华南区，返回 CDN 可访问 URL

---

数据库设计

article         # 文章主表（标题、摘要、浏览数、评论数、权重、作者、分类）
article_body    # 文章正文（Markdown 原文 + 渲染 HTML）
article_tag     # 文章-标签 多对多关联
category        # 文章分类
tag             # 标签
comments        # 评论（二级嵌套）
sys_user        # 系统用户（账号、密码+盐、昵称、头像）

完整 DDL 与示例数据见 blog-api.sql。

---

快速开始

环境要求

• JDK 8+
• Maven 3.6+
• MySQL 8.x
• Redis

1. 初始化数据库

mysql -u root -p < blog-api.sql

2. 修改配置

编辑 src/main/resources/application-dev.yml，填写本地数据库和 Redis 连接信息：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/blog?useUnicode=true&characterEncoding=UTF-8
    username: root
    password: yourpassword
  redis:
    host: localhost
    port: 6379

如需使用文件上传功能，在 application-dev.yml 中补充七牛云配置：

qiniu:
  accessKey: YOUR_ACCESS_KEY
  secretKey: YOUR_SECRET_KEY
  bucket: YOUR_BUCKET
  url: YOUR_CDN_URL

3. 切换到开发环境

编辑 src/main/resources/application.yml：

spring:
  profiles:
    active: dev   # 改为 dev

4. 启动项目

./mvnw spring-boot:run

服务默认运行在 http://localhost:8888。

---

API 文档

Base URL：http://localhost:8888/blogapi/v1

统一响应格式：

{
  "success": true,
  "code": 200,
  "message": "success",
  "data": {}
}

认证

方法	路径	说明
POST	/login	用户登录，返回 JWT Token
POST	/register	用户注册，返回 JWT Token
GET	/logout	登出（清除 Redis Token）

需要登录的接口在请求 Header 中携带：

Authorization: TOKEN {your_token}

文章

方法	路径	说明	需登录
POST	/articles	分页获取文章列表	否
POST	/articles/hot	最热文章（Top 6）	否
POST	/articles/new	最新文章（Top 6）	否
POST	/articles/listArchives	文章归档（年月统计）	否
POST	/articles/view/{id}	文章详情（自动增加浏览量）	否
POST	/articles/search	按标题关键词搜索	否
POST	/articles/publish	发布 / 编辑文章	是

分类

方法	路径	说明
GET	/categories	获取所有分类
GET	/categories/detail	获取所有分类详情
GET	/categories/detail/{id}	按 ID 获取分类详情

标签

方法	路径	说明
GET	/tags	获取所有标签
GET	/tags/hot	最热标签（Top 6）
GET	/tags/detail	获取所有标签详情
GET	/tags/detail/{id}	按 ID 获取标签详情

评论

方法	路径	说明	需登录
GET	/comments/article/{id}	获取文章所有评论	否
POST	/comments/create/change	发布评论	是

用户 / 文件

方法	路径	说明
GET	/users/currentUser	获取当前登录用户信息
POST	/upload	上传图片到七牛云

---

多环境配置

配置文件	用途
application.yml	入口，通过 spring.profiles.active 切换环境
application-dev.yml	本地开发，SQL 打印到控制台
application-prod.yml	生产环境，日志输出到文件

---

日志

日志通过 Log4j2 管理，按级别分文件输出：

文件	内容
控制台	INFO 及以上
info.log	INFO 日志，按天 + 10MB 切割，保留 15 份
warn.log	WARN 日志
error.log	ERROR 日志
sql.log	MyBatis SQL 语句（与业务日志隔离）

---

License

MIT