JC-Club 项目开发调试笔记

简介: 本文档记录了在开发 jc-club (技术社群) 项目过程中遇到的环境配置、架构依赖、数据库连接以及代码报错等问题的解决方案。 日期: 2026-02-07

1. Maven 与环境基础

1.1 Maven 版本号规范

在 pom.xml 中，版本号后缀有特定含义：

  • SNAPSHOT: 快照版本（开发版）。表示代码处于不稳定、频繁迭代的状态。
    • 例如: 0.0.1-SNAPSHOT, 1.0-SNAPSHOT
  • RELEASE: 正式发布版本。表示代码已稳定。

1.2 解决端口占用

场景: 启动 Spring Boot 时报错 Port 3005 was already in use。

解决方案 (Windows CMD):

  1. 查找占用端口的进程:

    1
    netstat -ano | findstr :3005

    输出示例: TCP 0.0.0.0:3005 0.0.0.0:0 LISTENING 12345 (12345 是 PID)

  2. 强制终止进程:

    1
    taskkill /PID 12345 /F

2. 项目架构与模块依赖

2.1 模块分层结构

jc-club 采用多模块 Maven 架构，各层职责如下：

1
2
3
4
5
6
7
8
jc-club-subject (父工程)
├── jc-club-starter           [启动层] 聚合所有依赖，存放启动类
├── jc-club-application       [应用层] 业务逻辑编排 (Service 接口定义)
│   └── jc-club-application-controller  [接入层] Controller 接口暴露
├── jc-club-domain            [领域层] 核心业务实体、领域服务
├── jc-club-infra             [基础层] 数据库交互 (Mapper/DAO)、外部工具
├── jc-club-subject-api       [API层]  对外暴露的 Feign 接口/DTO
└── jc-club-common            [公共层] 全局工具类、常量、异常定义

2.2 Controller 访问原理 (关键)

问题: 为什么写了 Controller 代码，启动后却访问不到接口（404）？

原因:

  1. Spring Boot 启动类通常在 jc-club-starter 模块。
  2. Controller 类在 jc-club-application-controller 模块。
  3. 如果 starter 没有引入 controller 模块的依赖，Controller 类就不会被打包进 Classpath。
  4. @ComponentScan 扫描不到该类，就不会注册路由。

解决方法: 在 jc-club-starter/pom.xml 中显式添加依赖：

1
2
3
4
<dependency>
    <groupId>com.dafenqi</groupId>
    <artifactId>jc-club-application-controller</artifactId>
</dependency>

3. 数据库与连接池配置

3.1 MySQL 连接 URL 详解

配置文件 application.yml 中的 URL 参数极其重要：

1
url: jdbc:mysql://localhost:3306/jc_club?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai&useSSL=false
参数 作用
jdbc:mysql:// 协议头
localhost:3306 地址与端口
jc_club 数据库名称 (需与建库语句一致)
useUnicode=true 允许使用 Unicode 字符集
characterEncoding=utf-8 防止中文乱码
serverTimezone=Asia/Shanghai 时区设置 (防止存入时间差8小时)
useSSL=false 开发环境禁用 SSL 警告

3.2 Druid 连接池配置

配置连接池以优化数据库性能，并开启监控功能。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
spring:
  datasource:
    druid:
      initial-size: 20       # 初始化时建立物理连接的个数
      min-idle: 20           # 最小连接池数量
      max-active: 200        # 最大连接池数量
      max-wait: 60000        # 获取连接时最大等待时间(毫秒)
      # 开启监控页面
      stat-view-servlet:
        url-pattern: /druid/*
        login-username: admin
        login-password: 123456
      filter:
        stat:
          log-slow-sql: true # 记录慢 SQL
          slow-sql-millis: 2000
  • 访问监控台: http://localhost:3000/druid (根据 server.port 调整端口)
  • 账号/密码: admin / 123456

4. 常见报错与排查 (Troubleshooting)

🔴 错误 1: Unknown database ‘jc_club’

  • 现象: 启动报错，提示找不到数据库。

  • 原因: MySQL 中尚未创建对应的数据库，或者名字写错了（如写成 jc-club）。

  • 解决:

    1
    CREATE DATABASE jc_club DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

🔴 错误 2: HTTP 500 访问 /test 接口报错

  • 现象: 访问测试接口报错，控制台显示 Table 'jc_club.subject_category' doesn't exist。

  • 原因: 数据库已创建，但缺少对应的表结构。

  • 解决: 执行建表 SQL。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    CREATE TABLE subject_category (
        id INT PRIMARY KEY AUTO_INCREMENT,
        category_name VARCHAR(100) NOT NULL COMMENT '分类名称',
        category_type INT COMMENT '分类类型',
        image_url VARCHAR(500) COMMENT '图片链接',
        parent_id INT COMMENT '父ID',
        created_by VARCHAR(50),
        created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
        update_by VARCHAR(50),
        update_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
    );
    -- 插入测试数据
    INSERT INTO subject_category (category_name, category_type) VALUES ('后端开发', 1);

🔴 错误 3: 代码中包路径导入错误

  • 现象: 编译报错或找不到类。
  • 原因: IDE 自动导入了错误的包。
  • 典型案例:
    1. DAO 层: 应该用 mapper 包下的接口，而不是 dao 包（除非自定义了）。
      • ❌ import ...infra.basic.dao.SubjectCategoryDao;
      • ✅ import ...infra.basic.mapper.SubjectCategoryDao;
    2. 分页对象: 应该用 MyBatis Plus 的 Page，而不是 Spring Data JPA 的。
      • ❌ import org.springframework.data.domain.Page;
      • ✅ import com.baomidou.mybatisplus.extension.plugins.pagination.Page;

5. 开发常用命令速查

MySQL 命令行

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 登录数据库
mysql -u root -p

# 查看所有数据库
SHOW DATABASES;

# 切换数据库并查看表
USE jc_club;
SHOW TABLES;

# 查看表结构
DESC subject_category;

# 查询数据
SELECT * FROM subject_category \G;

Maven 命令

1
2
3
4
5
# 清理并安装（跳过测试）
mvn clean install -DskipTests

# 启动 Spring Boot 项目
mvn spring-boot:run

6. 完整调用链路图解

理解一个请求是如何从浏览器到达数据库的：

1
2
3
4
5
6
7
graph LR
    User(用户/浏览器) --> API[/接口: localhost:3005/test/]
    API --> Controller[Controller层: jc-club-application-controller]
    Controller --> Service[Service层: SubjectCategoryService]
    Service --> Infra[Infra层: SubjectCategoryServiceImpl]
    Infra --> Mapper[Mapper/DAO层: MyBatis Plus接口]
    Mapper --> DB[(MySQL数据库: jc_club)]