快速启动

只需 5 分钟，即可在本地运行 Personal Blog Backend 并完成第一次 API 调用。

---

📋 环境要求

必需

环境	版本	说明
☕ JDK	21+	下载 OpenJDK 21
📦 Maven	3.6+	下载 Maven
🗄️ MySQL	8.0+	需要运行中的数据库实例
🔧 Git	任意	用于克隆项目

可选

环境	版本	说明
🔴 Redis	6.0+	用于缓存，不安装则自动禁用缓存功能

验证环境

java -version    # 应显示 java 21.x.x
mvn -version     # 应显示 Apache Maven 3.6+
mysql --version  # 应显示 MySQL 8.0+

---

🚀 启动步骤

Step 1：克隆项目

git clone https://github.com/liusxml/personal-blog-backend.git
cd personal-blog-backend

Step 2：创建数据库

连接 MySQL 并执行：

CREATE DATABASE blog_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Flyway 自动迁移

应用启动时会通过 Flyway 自动执行 blog-application/src/main/resources/db/ 下的 SQL 脚本，创建所需的表结构。

Step 3：修改配置

编辑 blog-application/src/main/resources/application.yaml：

application.yaml (关键配置)

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/blog_db?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: your_username   # 👈 修改为你的 MySQL 用户名
    password: your_password   # 👈 修改为你的 MySQL 密码

  # Redis 配置（可选，无 Redis 可删除此段）
  data:
    redis:
      host: localhost
      port: 6379
      password:  # Redis 密码，无密码留空

安全提示

生产环境请使用环境变量注入敏感信息：

username: ${DB_USERNAME}
password: ${DB_PASSWORD}

Step 4：构建项目

mvn clean install -DskipTests

首次构建

首次构建需要下载依赖包，可能需要 2-3 分钟。如遇下载慢，可配置 阿里云 Maven 镜像。

Step 5：启动应用

Maven 插件（推荐）

mvn spring-boot:run -pl blog-application

适合开发调试，支持热加载。

JAR 包运行

java -jar blog-application/target/blog-application-*.jar

适合生产部署。

Step 6：验证启动

看到以下日志说明启动成功：

Started BlogApplication in X.XXX seconds

---

🎉 访问应用

服务	地址	说明
Swagger UI	http://localhost:8080/swagger-ui.html	交互式 API 文档
健康检查	http://localhost:8080/actuator/health	返回 {"status":"UP"}
API 基础路径	http://localhost:8080/api/v1/	所有业务 API 前缀

---

🧪 测试第一个 API

1. 用户注册

Swagger UI

1. 打开 http://localhost:8080/swagger-ui.html
2. 找到 认证管理 → POST /api/v1/auth/register
3. 点击 Try it out
4. 输入请求体并点击 Execute

curl

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "Password123!",
    "email": "test@example.com",
    "nickname": "Test User"
  }'

请求体：

{
  "username": "testuser",
  "password": "Password123!",
  "email": "test@example.com",
  "nickname": "Test User"
}

成功响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "nickname": "Test User",
    "roles": ["ROLE_USER"]
  }
}

2. 用户登录

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "Password123!"
  }'

成功响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "user": { ... }
  }
}

3. 访问受保护的 API

curl -X GET http://localhost:8080/api/v1/users/me \
  -H "Authorization: Bearer {your_token}"

---

🔍 常见问题

❌ 数据库连接失败

错误： CommunicationsException: Communications link failure

解决方案：

1. 确认 MySQL 正在运行
2. 检查用户名密码是否正确
3. 确认数据库 blog_db 已创建
4. 检查端口是否为 3306

❌ 端口 8080 被占用

解决方案： 修改 application.yaml

server:
  port: 8081

❌ 构建失败：依赖下载超时

解决方案： 配置阿里云 Maven 镜像

编辑 ~/.m2/settings.xml：

<mirrors>
  <mirror>
    <id>aliyun</id>
    <mirrorOf>central</mirrorOf>
    <url>https://maven.aliyun.com/repository/public</url>
  </mirror>
</mirrors>

❌ Redis 连接失败

解决方案： 如果没有安装 Redis，可以删除 application.yaml 中的 Redis 配置，应用会自动禁用缓存功能。

---

🎯 下一步

恭喜！🎉 你已经成功启动了应用。接下来可以：

• 📖 了解架构设计 — 理解系统架构
• 📚 API 参考文档 — 完整的 REST API 文档
• 🛠️ 学习开发规范 — 编码标准
• 🧪 编写测试 — 保证代码质量

---

有问题？欢迎在 GitHub Issues 提问！