# z-blog

**Repository Path**: zhangjianyong12/z-blog

## Basic Information

- **Project Name**: z-blog
- **Description**: 个人博客项目
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-06-26
- **Last Updated**: 2025-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: blog

## README

# 个人博客系统

![Java](https://img.shields.io/badge/Java-17-orange)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.3.2-brightgreen)
![Vue](https://img.shields.io/badge/Vue-3.4.35-4FC08D)
![TypeScript](https://img.shields.io/badge/TypeScript-5.5.3-blue)
![Element Plus](https://img.shields.io/badge/Element%20Plus-2.7.8-409EFF)
![License](https://img.shields.io/badge/License-MIT-green)

一个基于 Spring Boot + Vue 3 的现代化个人博客系统，包含博客前台展示和管理后台两个部分。

## 📋 项目简介

本项目是一个全栈博客系统，采用前后端分离架构设计，具有完整的内容管理、用户权限、评论互动等功能。系统分为三个主要模块：

- **后端 API** (`blog-api`): 基于 Spring Boot 的 RESTful API 服务
- **博客前台** (`blog-web-portal`): 面向访客的博客展示界面
- **管理后台** (`blog-web-manage`): 面向博主的内容管理系统

## 🚀 主要特性

### 博客功能

- ✅ 文章发布、编辑、删除
- ✅ 分类和标签管理
- ✅ 文章置顶和状态管理
- ✅ Markdown 编辑器支持
- ✅ 代码高亮和数学公式渲染
- ✅ 响应式设计，适配移动端

### 交互功能

- ✅ 评论和回复系统
- ✅ 文章点赞和访问统计
- ✅ 时间线展示
- ✅ 微博动态功能
- ✅ 全站搜索

### 管理功能

- ✅ 用户权限管理
- ✅ 角色分配
- ✅ 文件上传管理
- ✅ 数据统计分析
- ✅ 系统日志记录

### 技术特性

- 🔧 模块化架构设计
- 🔧 统一异常处理
- 🔧 接口参数验证
- 🔧 SQL 防注入
- 🔧 跨域支持
- 🔧 全局状态管理
- 🔧 雪花算法 ID 生成
- 🔧 分布式唯一 ID 保证

## 🛠️ 技术栈

### 后端技术

- **核心框架**: Spring Boot 3.3.2
- **数据库**: MySQL 9.0.0
- **ORM 框架**: MyBatis Plus 3.5.7
- **连接池**: Druid 1.2.23
- **安全加密**: BCrypt 0.4
- **JSON 处理**: FastJSON2 2.0.51
- **工具库**: Hutool 5.8.28
- **邮件服务**: Jakarta Mail 2.1.3
- **运行环境**: Java 17

### 前端技术

- **核心框架**: Vue 3.4.35
- **开发语言**: TypeScript 5.5.3
- **构建工具**: Vite 6.3.2
- **UI 框架**: Element Plus 2.7.8
- **状态管理**: Pinia 2.2.2
- **路由管理**: Vue Router 4.0.13
- **HTTP 客户端**: Axios 1.7.2
- **Markdown 编辑器**: MD Editor V3 5.5.0
- **图表库**: ECharts 5.5.1
- **CSS 预处理器**: Sass 1.77.8

## 📁 项目结构

```
blog/
├── blog-api/                    # 后端项目
│   ├── blog-ai/                # AI 模块
│   ├── blog-aop/               # AOP 切面模块
│   ├── blog-common/            # 通用工具和公共定义
│   ├── blog-config/            # 项目配置模块
│   ├── blog-dao/               # 数据访问层 - Mapper
│   ├── blog-main/              # Spring Boot 主启动模块
│   ├── blog-manage/            # 管理后台 API 接口
│   ├── blog-model/             # 数据模型、DTO、PO
│   ├── blog-portal/            # 博客前台 API 接口
│   ├── blog-service/           # 核心业务逻辑层
│   └── pom.xml                 # Maven 父项目配置
├── blog-web-manage/            # 后台管理前端
│   ├── src/
│   │   ├── api/                # API 请求封装
│   │   ├── components/         # 可复用组件
│   │   ├── views/              # 页面组件
│   │   ├── router/             # 路由配置
│   │   ├── store/              # 状态管理
│   │   └── utils/              # 工具函数
│   └── package.json
└── blog-web-portal/            # 博客前台前端
    ├── src/
    │   ├── api/                # API 请求封装
    │   ├── components/         # 可复用组件
    │   ├── views/              # 页面组件
    │   ├── stores/             # 状态管理
    │   └── composables/        # 组合式函数
    └── package.json
```

## 🔧 环境要求

### 开发环境

- **JDK**: 17+
- **Node.js**: 18+
- **MySQL**: 8.0+
- **Maven**: 3.6+
- **Git**: 2.0+

### 推荐 IDE

- **后端**: IntelliJ IDEA
- **前端**: VS Code + Prettier + ESLint 插件

## 📏 代码规范

### 前端代码规范

本项目已配置完整的前端代码格式化方案，确保两个前端项目代码风格统一。

#### 格式化规则

- **缩进**: 2 个空格
- **引号**: 单引号
- **分号**: 不使用分号
- **行宽**: 100 字符
- **Vue 组件**: PascalCase 命名

#### 开发命令

在前端项目目录下可执行：

```bash
npm run format        # 格式化代码
npm run format:check  # 检查格式
npm run lint:fix      # 修复ESLint错误
npm run lint:format   # 一键格式化和修复（推荐）
```

#### VSCode 配置

项目已配置保存时自动格式化，请安装推荐插件：

- **Prettier - Code formatter**
- **ESLint**
- **Volar** (Vue 语言支持)

### 数据库表设计规范

#### 必备字段要求

⚠️ **重要**：每个新创建的数据库表都必须包含以下 5 个标准字段：

```sql
-- 时间字段
create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',

-- 管理字段
create_user BIGINT NULL COMMENT '创建用户ID',
update_user BIGINT NULL COMMENT '更新用户ID',
is_del TINYINT DEFAULT 0 COMMENT '是否删除：0-否 1-是',
```

#### 实体类设计

- 继承 `BaseEntity` 抽象类自动获得标准字段
- 使用 `@TableLogic` 注解实现逻辑删除
- 使用 `@FieldFill` 注解自动填充时间和用户字段

```java
@TableName("table_name")
public class YourEntity extends BaseEntity {
    // 业务字段...
}
```

#### 索引设计原则

- 根据实际查询场景创建索引
- 避免为低选择性字段（如 `is_del`）创建单独索引
- 复合索引优先考虑高选择性字段
- 唯一约束需要考虑逻辑删除场景

## 📦 安装部署

### 1. 克隆项目

```bash
git clone <repository-url>
cd blog
```

### 2. 后端部署

#### 数据库准备

1. 创建 MySQL 数据库
2. 导入数据库脚本（如果有）
3. 修改数据库配置

#### 配置文件

编辑 `blog-api/blog-main/src/main/resources/application-local.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/blog?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: your_username
    password: your_password
```

#### 启动后端服务

```bash
cd blog-api
mvn clean install
mvn spring-boot:run -pl blog-main
```

后端服务将在 `http://localhost:8096` 启动

### 3. 前端部署

#### 博客前台

```bash
cd blog-web-portal
npm install
npm run dev
```

前台页面将在 `http://localhost:5173` 启动

#### 管理后台

```bash
cd blog-web-manage
npm install
npm run dev
```

管理后台将在 `http://localhost:5174` 启动

## 🔧 配置说明

### 后端配置

- **端口**: 8096
- **文件上传**: 最大 100MB
- **数据库**: 支持逻辑删除
- **ID 生成**: 雪花算法（支持分布式唯一 ID）
- **跨域**: 已配置 CORS 支持

#### ID 生成策略

项目使用雪花算法（Snowflake）生成分布式唯一 ID，具有以下特点：

- **唯一性**: 保证在分布式环境下 ID 的全局唯一性
- **有序性**: 生成的 ID 按时间递增，有利于数据库索引
- **高性能**: 本地生成，无需网络通信
- **可配置**: 支持配置机器 ID 和数据中心 ID

**配置示例**：

```yaml
blog:
  id-sequence:
    data-center-id: 1 # 数据中心ID (0-31)
    worker-id: 1 # 机器ID (0-31)
```

**开发使用**：

```java
@Autowired
private IdentifierGenerator identifierGenerator;

// 生成唯一ID
Long id = identifierGenerator.nextId(entity).longValue();
```

### 前端配置

- **API 代理**: 开发环境自动代理到后端
- **路由模式**: History 模式
- **状态持久化**: LocalStorage
- **主题**: 支持暗色模式切换

## 🎯 功能模块

### 博客前台

- 📖 文章列表和详情展示
- 🏷️ 分类和标签浏览
- 💬 评论和回复功能
- 👍 文章点赞和分享
- 📅 时间线展示
- 🔍 全站搜索
- 📱 响应式适配

### 管理后台

- 📝 文章编辑和发布
- 📊 数据统计面板
- 👥 用户权限管理
- 🗂️ 分类标签管理
- 💬 评论管理
- 📁 文件管理
- ⚙️ 系统设置

## 🔒 权限说明

### 角色权限

- **管理员**: 所有功能权限
- **编辑**: 内容编辑权限
- **访客**: 只读权限

### 接口保护

- 管理接口需要管理员权限
- 部分接口需要登录状态
- 访客操作需要 UUID 标识

## 📖 API 文档

详细的接口文档请参考项目中的 API 说明文档，包含：

- 接口地址和请求方式
- 参数说明和示例
- 响应格式和状态码
- 权限要求和异常处理

## 🤝 贡献指南

### 代码提交流程

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. **代码格式化检查** (`npm run lint:format`)
4. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
5. 推送到分支 (`git push origin feature/AmazingFeature`)
6. 开启 Pull Request

### 代码质量要求

- 遵循项目代码规范
- 通过 ESLint 检查
- 确保代码格式化一致
- 添加必要的注释和文档

## 📄 开源协议

本项目基于 MIT 协议开源，详情请参见 [LICENSE](LICENSE) 文件。

## 📞 联系方式

如有问题或建议，欢迎通过以下方式联系：

- 邮箱: your-email@example.com
- 博客: your-blog-url
- GitHub: your-github-username

## 🙏 致谢

感谢所有开源项目的贡献者，特别是：

- Spring Boot 团队
- Vue.js 团队
- Element Plus 团队
- MyBatis Plus 团队

---

⭐ 如果这个项目对您有帮助，请给它一个星标！