一、项目概述

本文将带你搭建一个企业级知识库管理系统的后端项目骨架。

本项目采用 Spring Boot 3.2 + MyBatis Plus + MySQL 技术栈,使用 Maven 多模块 架构,遵循微服务设计理念。

1.1 技术选型

技术版本说明
JDK21使用最新长期支持版本
Spring Boot3.2.0核心框架
Spring Cloud2023.0.0微服务基础设施
MyBatis Plus3.5.8ORM框架,简化数据库操作
MySQL8.0+关系型数据库
Redis7.2+缓存中间件
Knife4j4.3.0API文档工具
Hutool5.8.24Java工具类库
JWT0.12.3Token认证

1.2 模块设计

项目采用多模块架构,共包含10个子模块:

knowledge-base-backend/
├── kb-common/           # 公共模块
├── kb-gateway/          # API网关
├── kb-user-auth/        # 用户权限服务
├── kb-document/         # 文档服务
├── kb-search/           # 搜索服务
├── kb-file/            # 文件服务
├── kb-ai/              # AI服务
├── kb-graph/           # 知识图谱服务
├── kb-statistics/      # 统计服务
└── kb-foundation/      # 基础服务

二、环境准备

2.1 基础软件安装

确保你的开发环境已安装以下软件:

# 检查Java版本
java -version  # 应该显示 21 或更高版本

# 检查Maven版本
mvn -v         # 应该显示 3.8+ 版本

# 检查MySQL版本
mysql --version # 应该显示 8.0+ 版本

2.2 开发工具推荐

  • IDE: IntelliJ IDEA 2023.2+
  • 数据库工具: Navicat / DBeaver
  • API测试: Postman / Apifox
  • Redis工具: RedisInsight

三、创建父项目

3.1 创建Maven父项目

首先,创建一个Maven父项目来管理所有子模块:

# 创建项目根目录
mkdir knowledge-base-backend
cd knowledge-base-backend

3.2 配置父 pom.xml

在根目录创建 pom.xml 文件:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
        <relativePath/>
    </parent>
    <groupId>com.knowledge.base</groupId>
    <artifactId>knowledge-base-backend</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <name>Knowledge Base Backend</name>
    <description>Enterprise Knowledge Base System Backend</description>
    <properties>
        <java.version>21</java.version>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <!-- 依赖版本管理 -->
        <spring-cloud.version>2023.0.0</spring-cloud.version>
        <mybatis-plus.version>3.5.8</mybatis-plus.version>
        <druid.version>1.2.20</druid.version>
        <hutool.version>5.8.24</hutool.version>
        <jwt.version>0.12.3</jwt.version>
        <knife4j.version>4.3.0</knife4j.version>
        <commons-lang3.version>3.14.0</commons-lang3.version>
        <commons-collections4.version>4.4</commons-collections4.version>
        <fastjson2.version>2.0.43</fastjson2.version>
    </properties>
    <modules>
        <module>kb-common</module>
        <module>kb-gateway</module>
        <module>kb-user-auth</module>
        <module>kb-document</module>
        <module>kb-search</module>
        <module>kb-file</module>
        <module>kb-ai</module>
        <module>kb-graph</module>
        <module>kb-statistics</module>
        <module>kb-foundation</module>
    </modules>
    <dependencyManagement>
        <dependencies>
            <!-- Spring Cloud 依赖 -->
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <!-- MyBatis Plus -->
            <dependency>
                <groupId>com.baomidou</groupId>
                <artifactId>mybatis-plus-boot-starter</artifactId>
                <version>${mybatis-plus.version}</version>
            </dependency>
            <!-- Druid 数据源 -->
            <dependency>
                <groupId>com.alibaba</groupId>
                <artifactId>druid-spring-boot-3-starter</artifactId>
                <version>${druid.version}</version>
            </dependency>
            <!-- Hutool 工具类 -->
            <dependency>
                <groupId>cn.hutool</groupId>
                <artifactId>hutool-all</artifactId>
                <version>${hutool.version}</version>
            </dependency>
            <!-- JWT -->
            <dependency>
                <groupId>io.jsonwebtoken</groupId>
                <artifactId>jjwt-api</artifactId>
                <version>${jwt.version}</version>
            </dependency>
            <dependency>
                <groupId>io.jsonwebtoken</groupId>
                <artifactId>jjwt-impl</artifactId>
                <version>${jwt.version}</version>
            </dependency>
            <dependency>
                <groupId>io.jsonwebtoken</groupId>
                <artifactId>jjwt-jackson</artifactId>
                <version>${jwt.version}</version>
            </dependency>
            <!-- Knife4j API文档 -->
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
                <version>${knife4j.version}</version>
            </dependency>
            <!-- Apache Commons -->
            <dependency>
                <groupId>org.apache.commons</groupId>
                <artifactId>commons-lang3</artifactId>
                <version>${commons-lang3.version}</version>
            </dependency>
            <dependency>
                <groupId>org.apache.commons</groupId>
                <artifactId>commons-collections4</artifactId>
                <version>${commons-collections4.version}</version>
            </dependency>
            <!-- FastJSON2 -->
            <dependency>
                <groupId>com.alibaba.fastjson2</groupId>
                <artifactId>fastjson2</artifactId>
                <version>${fastjson2.version}</version>
            </dependency>
            <!-- 内部模块依赖 -->
            <dependency>
                <groupId>com.knowledge.base</groupId>
                <artifactId>kb-common</artifactId>
                <version>${project.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                    <configuration>
                        <excludes>
                            <exclude>
                                <groupId>org.projectlombok</groupId>
                                <artifactId>lombok</artifactId>
                            </exclude>
                        </excludes>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
    <repositories>
        <repository>
            <id>aliyun</id>
            <url>https://maven.aliyun.com/repository/public</url>
        </repository>
    </repositories>
</project>

3.3 配置 .gitignore

创建 .gitignore 文件:

# Maven
target/
!.mvn/wrapper/maven-wrapper.jar
!**/src/main/**/target/
!**/src/test/**/target/

# IntelliJ IDEA
.idea/
*.iws
*.iml
*.ipr
out/

# Mac
.DS_Store

# Log files
*.log
logs/

# Application
application-local.yml
application-dev.yml
application-prod.yml

# Upload files
uploads/
data/

四、创建公共模块

公共模块包含所有子模块共用的代码,如工具类、配置类、异常处理等。

4.1 创建模块目录

mkdir -p kb-common/src/main/java/com/knowledge/base/common
mkdir -p kb-common/src/main/resources

4.2 创建 kb-common/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.knowledge.base</groupId>
        <artifactId>knowledge-base-backend</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    <artifactId>kb-common</artifactId>
    <packaging>jar</packaging>
    <name>Knowledge Base Common Module</name>
    <description>公共模块</description>
    <dependencies>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Spring Boot Validation -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <!-- Spring Boot Security -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
        <!-- Spring Boot AOP -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aop</artifactId>
        </dependency>
        <!-- MyBatis Plus -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
        </dependency>
        <!-- Knife4j API文档 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
        </dependency>
        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <!-- Hutool -->
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
        </dependency>
        <!-- JWT -->
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-api</artifactId>
        </dependency>
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-impl</artifactId>
        </dependency>
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-jackson</artifactId>
        </dependency>
        <!-- Apache Commons -->
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-collections4</artifactId>
        </dependency>
        <!-- FastJSON2 -->
        <dependency>
            <groupId>com.alibaba.fastjson2</groupId>
            <artifactId>fastjson2</artifactId>
        </dependency>
    </dependencies>
</project>

4.3 创建统一响应结构

创建 kb-common/src/main/java/com/knowledge/base/common/result/Result.java:

package com.knowledge.base.common.result;

import lombok.Data;
import java.io.Serializable;

/**
 * 统一响应结果封装类
 *
 * @param <T> 数据类型
 */
@Data
public class Result<T> implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 响应码
     */
    private Integer code;

    /**
     * 响应消息
     */
    private String message;

    /**
     * 响应数据
     */
    private T data;

    /**
     * 时间戳
     */
    private Long timestamp;

    public Result() {
        this.timestamp = System.currentTimeMillis();
    }

    public Result(Integer code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
        this.timestamp = System.currentTimeMillis();
    }

    /**
     * 成功响应(无数据)
     */
    public static <T> Result<T> success() {
        return new Result<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), null);
    }

    /**
     * 成功响应(有数据)
     */
    public static <T> Result<T> success(T data) {
        return new Result<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), data);
    }

    /**
     * 成功响应(自定义消息)
     */
    public static <T> Result<T> success(String message, T data) {
        return new Result<>(ResultCode.SUCCESS.getCode(), message, data);
    }

    /**
     * 失败响应(错误码)
     */
    public static <T> Result<T> error(ErrorCode errorCode) {
        return new Result<>(errorCode.getCode(), errorCode.getMessage(), null);
    }

    /**
     * 失败响应(自定义消息)
     */
    public static <T> Result<T> error(String message) {
        return new Result<>(ResultCode.ERROR.getCode(), message, null);
    }

    /**
     * 失败响应(自定义码和消息)
     */
    public static <T> Result<T> error(Integer code, String message) {
        return new Result<>(code, message, null);
    }
}

创建 kb-common/src/main/java/com/knowledge/base/common/result/ResultCode.java:

package com.knowledge.base.common.result;

import lombok.Getter;

/**
 * 响应码枚举
 */
@Getter
public enum ResultCode {

    SUCCESS(200, "操作成功"),
    ERROR(500, "操作失败"),
    PARAM_ERROR(400, "参数错误"),
    UNAUTHORIZED(401, "未授权"),
    FORBIDDEN(403, "禁止访问"),
    NOT_FOUND(404, "资源不存在"),
    METHOD_NOT_ALLOWED(405, "请求方法不支持");

    private final Integer code;
    private final String message;

    ResultCode(Integer code, String message) {
        this.code = code;
        this.message = message;
    }
}

创建 kb-common/src/main/java/com/knowledge/base/common/result/ErrorCode.java:

package com.knowledge.base.common.result;

import lombok.Getter;

/**
 * 业务错误码枚举
 */
@Getter
public enum ErrorCode {

    // 通用错误码 1000-1999
    SYSTEM_ERROR(1000, "系统错误"),
    PARAM_ERROR(1001, "参数错误"),
    DATA_NOT_FOUND(1002, "数据不存在"),
    DATA_ALREADY_EXISTS(1003, "数据已存在"),
    OPERATION_FAILED(1004, "操作失败"),

    // 用户错误码 2000-2999
    USER_NOT_EXIST(2000, "用户不存在"),
    USER_ALREADY_EXISTS(2001, "用户已存在"),
    USER_PASSWORD_ERROR(2002, "密码错误"),
    USER_ACCOUNT_DISABLED(2003, "账户已被禁用"),
    USER_TOKEN_EXPIRED(2004, "Token已过期"),
    USER_TOKEN_INVALID(2005, "Token无效"),

    // 文档错误码 3000-3999
    DOC_NOT_FOUND(3000, "文档不存在"),
    DOC_ALREADY_EXISTS(3001, "文档已存在"),
    DOC_TITLE_EMPTY(3002, "文档标题不能为空"),
    DOC_CONTENT_EMPTY(3003, "文档内容不能为空"),

    // 权限错误码 4000-4999
    PERMISSION_DENIED(4000, "权限不足"),
    ROLE_NOT_EXIST(4001, "角色不存在"),
    ROLE_ALREADY_EXISTS(4002, "角色已存在");

    private final Integer code;
    private final String message;

    ErrorCode(Integer code, String message) {
        this.code = code;
        this.message = message;
    }
}

4.4 创建基础实体类

创建 kb-common/src/main/java/com/knowledge/base/common/config/BaseEntity.java:

package com.knowledge.base.common.config;

import com.baomidou.mybatisplus.annotation.FieldFill;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableLogic;
import lombok.Data;
import java.io.Serializable;
import java.time.LocalDateTime;

/**
 * 基础实体类,包含通用字段
 */
@Data
public abstract class BaseEntity implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 主键ID
     */
    private Long id;

    /**
     * 创建时间
     */
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    /**
     * 更新时间
     */
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;

    /**
     * 创建人ID
     */
    @TableField(fill = FieldFill.INSERT)
    private Long createBy;

    /**
     * 更新人ID
     */
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Long updateBy;

    /**
     * 逻辑删除标记(0-未删除,1-已删除)
     */
    @TableLogic
    private Integer deleted;
}

4.5 创建自定义异常

创建 kb-common/src/main/java/com/knowledge/base/common/exception/BusinessException.java:

package com.knowledge.base.common.exception;

import com.knowledge.base.common.result.ErrorCode;
import lombok.Getter;

/**
 * 业务异常
 */
@Getter
public class BusinessException extends RuntimeException {

    private final Integer code;

    public BusinessException(ErrorCode errorCode) {
        super(errorCode.getMessage());
        this.code = errorCode.getCode();
    }

    public BusinessException(Integer code, String message) {
        super(message);
        this.code = code;
    }

    public BusinessException(String message) {
        super(message);
        this.code = 500;
    }
}

创建 kb-common/src/main/java/com/knowledge/base/common/exception/GlobalExceptionHandler.java:

package com.knowledge.base.common.exception;

import com.knowledge.base.common.result.Result;
import com.knowledge.base.common.result.ResultCode;
import lombok.extern.slf4j.Slf4j;
import org.springframework.validation.BindException;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

/**
 * 全局异常处理器
 */
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 业务异常处理
     */
    @ExceptionHandler(BusinessException.class)
    public Result<Void> handleBusinessException(BusinessException e) {
        log.error("业务异常:{}", e.getMessage(), e);
        return Result.error(e.getCode(), e.getMessage());
    }

    /**
     * 参数校验异常处理
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleValidException(MethodArgumentNotValidException e) {
        FieldError fieldError = e.getBindingResult().getFieldError();
        String message = fieldError != null ? fieldError.getDefaultMessage() : "参数校验失败";
        log.error("参数校验异常:{}", message);
        return Result.error(ResultCode.PARAM_ERROR.getCode(), message);
    }

    /**
     * 系统异常处理
     */
    @ExceptionHandler(Exception.class)
    public Result<Void> handleException(Exception e) {
        log.error("系统异常:{}", e.getMessage(), e);
        return Result.error(ResultCode.ERROR.getCode(), "系统错误,请联系管理员");
    }
}

4.6 创建MyBatis Plus字段自动填充

创建 kb-common/src/main/java/com/knowledge/base/common/handler/MyMetaObjectHandler.java:

package com.knowledge.base.common.handler;

import com.baomidou.mybatisplus.core.handlers.MetaObjectHandler;
import com.knowledge.base.common.utils.UserContextUtil;
import lombok.extern.slf4j.Slf4j;
import org.apache.ibatis.reflection.MetaObject;
import org.springframework.stereotype.Component;

import java.time.LocalDateTime;

/**
 * MyBatis Plus字段自动填充处理器
 */
@Slf4j
@Component
public class MyMetaObjectHandler implements MetaObjectHandler {

    @Override
    public void insertFill(MetaObject metaObject) {
        log.debug("开始插入填充...");
        this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());
        this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());

        // 获取当前用户ID
        Long userId = UserContextUtil.getCurrentUserId();
        if (userId != null) {
            this.strictInsertFill(metaObject, "createBy", Long.class, userId);
            this.strictInsertFill(metaObject, "updateBy", Long.class, userId);
        }
    }

    @Override
    public void updateFill(MetaObject metaObject) {
        log.debug("开始更新填充...");
        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());

        // 获取当前用户ID
        Long userId = UserContextUtil.getCurrentUserId();
        if (userId != null) {
            this.strictUpdateFill(metaObject, "updateBy", Long.class, userId);
        }
    }
}

创建kb-common/src/main/java/com/knowledge/base/common/utils/UserContextUtil.java:

package com.knowledge.base.common.utils;

import jakarta.servlet.http.HttpServletRequest;

/**
 * 用户上下文工具类
 *
 * <p>提供用户上下文获取和设置功能</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
public class UserContextUtil {

    private static final ThreadLocal<Long> USER_ID_HOLDER = new ThreadLocal<>();
    private static final ThreadLocal<String> USERNAME_HOLDER = new ThreadLocal<>();
    private static final ThreadLocal<String> TOKEN_HOLDER = new ThreadLocal<>();

    /**
     * 设置当前用户ID
     *
     * @param userId 用户ID
     */
    public static void setUserId(Long userId) {
        USER_ID_HOLDER.set(userId);
    }

    /**
     * 获取当前用户ID
     *
     * @return 用户ID
     */
    public static Long getUserId() {
        return USER_ID_HOLDER.get();
    }

    /**
     * 设置当前用户名
     *
     * @param username 用户名
     */
    public static void setUsername(String username) {
        USERNAME_HOLDER.set(username);
    }

    /**
     * 获取当前用户名
     *
     * @return 用户名
     */
    public static String getUsername() {
        return USERNAME_HOLDER.get();
    }

    /**
     * 设置Token
     *
     * @param token Token
     */
    public static void setToken(String token) {
        TOKEN_HOLDER.set(token);
    }

    /**
     * 获取Token
     *
     * @return Token
     */
    public static String getToken() {
        return TOKEN_HOLDER.get();
    }

    /**
     * 从请求中获取用户ID
     *
     * @param request HttpServletRequest
     * @return 用户ID
     */
    public static Long getUserIdFromRequest(HttpServletRequest request) {
        String token = extractTokenFromRequest(request);
        if (token == null) {
            return null;
        }

        try {
            // 使用JwtTokenUtil解析token
            JwtTokenUtil jwtTokenUtil = SpringContextUtil.getBean(JwtTokenUtil.class);
            return jwtTokenUtil.getUserIdFromToken(token);
        } catch (Exception e) {
            return null;
        }
    }

    /**
     * 从请求中提取Token
     *
     * @param request HttpServletRequest
     * @return Token
     */
    public static String extractTokenFromRequest(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");
        if (bearerToken != null && bearerToken.startsWith("Bearer ")) {
            return bearerToken.substring(7);
        }
        return null;
    }

    /**
     * 清除当前用户上下文
     */
    public static void clear() {
        USER_ID_HOLDER.remove();
        USERNAME_HOLDER.remove();
        TOKEN_HOLDER.remove();
    }

    /**
     * 检查用户是否已登录
     *
     * @return 是否已登录
     */
    public static boolean isLoggedIn() {
        return getUserId() != null;
    }
}

创建kb-common/src/main/java/com/knowledge/base/common/utils/SpringContextUtil.java:

package com.knowledge.base.common.utils;

import org.springframework.beans.BeansException;
import org.springframework.context.ApplicationContext;
import org.springframework.context.ApplicationContextAware;
import org.springframework.stereotype.Component;

/**
 * Spring上下文工具类
 *
 * <p>用于获取Spring容器中的Bean</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Component
public class SpringContextUtil implements ApplicationContextAware {

    private static ApplicationContext applicationContext;

    @Override
    public void setApplicationContext(ApplicationContext context) throws BeansException {
        applicationContext = context;
    }

    /**
     * 获取ApplicationContext
     *
     * @return ApplicationContext
     */
    public static ApplicationContext getApplicationContext() {
        return applicationContext;
    }

    /**
     * 根据类型获取Bean
     *
     * @param clazz Bean的类型
     * @param <T>   泛型
     * @return Bean实例
     */
    public static <T> T getBean(Class<T> clazz) {
        return applicationContext.getBean(clazz);
    }

    /**
     * 根据名称获取Bean
     *
     * @param name Bean的名称
     * @return Bean实例
     */
    public static Object getBean(String name) {
        return applicationContext.getBean(name);
    }

    /**
     * 根据名称和类型获取Bean
     *
     * @param name  Bean的名称
     * @param clazz Bean的类型
     * @param <T>   泛型
     * @return Bean实例
     */
    public static <T> T getBean(String name, Class<T> clazz) {
        return applicationContext.getBean(name, clazz);
    }
}

创建kb-common/src/main/java/com/knowledge/base/common/utils/JwtTokenUtil.java:

package com.knowledge.base.common.utils;

import com.knowledge.base.common.config.JwtConfig;
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.security.Keys;
import jakarta.annotation.Resource;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

import javax.crypto.SecretKey;
import java.nio.charset.StandardCharsets;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

/**
 * JWT工具类
 *
 * <p>提供JWT Token的生成、解析和验证功能</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@Component
public class JwtTokenUtil {

    @Resource
    private JwtConfig jwtConfig;

    /**
     * 生成访问Token
     *
     * @param userId 用户ID
     * @return Token
     */
    public String generateAccessToken(Long userId) {
        return generateToken(userId, jwtConfig.getExpiration() * 1000);
    }

    /**
     * 生成刷新Token
     *
     * @param userId 用户ID
     * @return Token
     */
    public String generateRefreshToken(Long userId) {
        return generateToken(userId, jwtConfig.getRefreshExpiration() * 1000);
    }

    /**
     * 生成Token
     *
     * @param userId 用户ID
     * @param expiration 过期时间(毫秒)
     * @return Token
     */
    private String generateToken(Long userId, Long expiration) {
        Date now = new Date();
        Date expiryDate = new Date(now.getTime() + expiration);

        Map<String, Object> claims = new HashMap<>();
        claims.put("userId", userId);
        claims.put("type", "access");

        return Jwts.builder()
                .claims(claims)
                .subject(String.valueOf(userId))
                .issuer(jwtConfig.getIssuer())
                .issuedAt(now)
                .expiration(expiryDate)
                .signWith(jwtConfig.secretKey())
                .compact();
    }

    /**
     * 解析Token
     *
     * @param token Token
     * @return Claims
     */
    public Claims parseToken(String token) {
        try {
            return Jwts.parser()
                    .verifyWith(jwtConfig.secretKey())
                    .build()
                    .parseSignedClaims(token)
                    .getPayload();
        } catch (Exception e) {
            log.error("解析Token失败:{}", e.getMessage());
            return null;
        }
    }

    /**
     * 从Token中获取用户ID
     *
     * @param token Token
     * @return 用户ID
     */
    public Long getUserIdFromToken(String token) {
        Claims claims = parseToken(token);
        if (claims == null) {
            return null;
        }
        return Long.parseLong(claims.getSubject());
    }

    /**
     * 验证Token是否有效
     *
     * @param token Token
     * @return 是否有效
     */
    public boolean validateToken(String token) {
        try {
            Claims claims = parseToken(token);
            if (claims == null) {
                return false;
            }
            Date expiration = claims.getExpiration();
            return expiration.after(new Date());
        } catch (Exception e) {
            log.error("验证Token失败:{}", e.getMessage());
            return false;
        }
    }

    /**
     * 检查Token是否即将过期
     *
     * @param token Token
     * @param thresholdSeconds 阈值(秒)
     * @return 是否即将过期
     */
    public boolean isTokenExpiringSoon(String token, int thresholdSeconds) {
        try {
            Claims claims = parseToken(token);
            if (claims == null) {
                return true;
            }
            Date expiration = claims.getExpiration();
            long timeToExpiry = expiration.getTime() - System.currentTimeMillis();
            return timeToExpiry < thresholdSeconds * 1000;
        } catch (Exception e) {
            return true;
        }
    }

    /**
     * 刷新Token
     *
     * @param refreshToken 刷新Token
     * @return 新的访问Token
     */
    public String refreshToken(String refreshToken) {
        Claims claims = parseToken(refreshToken);
        if (claims == null) {
            throw new RuntimeException("刷新Token无效");
        }

        Long userId = Long.parseLong(claims.getSubject());
        return generateAccessToken(userId);
    }
}

创建kb-common/src/main/java/com/knowledge/base/common/config/JwtConfig.java:

package com.knowledge.base.common.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

import javax.crypto.SecretKey;
import java.nio.charset.StandardCharsets;

import io.jsonwebtoken.security.Keys;

/**
 * JWT配置类
 *
 * <p>提供JWT Token的配置属性,包括密钥、过期时间和发行者信息</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Component
@ConfigurationProperties(prefix = "jwt")
public class JwtConfig {

    /**
     * JWT密钥
     */
    private String secret = "knowledge-base-secret-key-for-jwt-token-generation-must-be-long-enough";

    /**
     * 访问令牌过期时间(秒)
     */
    private Long expiration = 7200L;

    /**
     * 刷新令牌过期时间(秒)
     */
    private Long refreshExpiration = 604800L;

    /**
     * 发行者
     */
    private String issuer = "knowledge-base";

    /**
     * 获取密钥对象
     *
     * @return 密钥对象
     */
    public SecretKey secretKey() {
        return Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));
    }
}

五、创建用户权限服务模块

用户权限服务负责用户认证、授权、角色权限管理等功能。

5.1 创建模块目录

mkdir -p kb-user-auth/src/main/java/com/knowledge/base/userauth
mkdir -p kb-user-auth/src/main/resources

5.2 创建 kb-user-auth/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.knowledge.base</groupId>
        <artifactId>knowledge-base-backend</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    <artifactId>kb-user-auth</artifactId>
    <packaging>jar</packaging>
    <name>Knowledge Base User Auth Service</name>
    <description>用户权限服务</description>
    <dependencies>
        <!-- 公共模块 -->
        <dependency>
            <groupId>com.knowledge.base</groupId>
            <artifactId>kb-common</artifactId>
        </dependency>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Spring Boot Security -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
        <!-- Spring Boot Validation -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <!-- MyBatis Plus -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
        </dependency>
        <!-- MySQL Driver -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>
        <!-- Druid -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-3-starter</artifactId>
        </dependency>
        <!-- Knife4j -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
        </dependency>
        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <!-- Spring Boot Test -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

5.3 创建应用启动类

创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/UserAuthApplication.java:

package com.knowledge.base.userauth;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * 用户权限服务启动类
 */
@SpringBootApplication(scanBasePackages = "com.knowledge.base")
public class UserAuthApplication {

    public static void main(String[] args) {
        SpringApplication.run(UserAuthApplication.class, args);
        System.out.println("用户权限服务启动成功!");
    }
}

5.4 创建配置文件

创建 kb-user-auth/src/main/resources/application.yml:

server:
  port: 8081
  servlet:
    context-path: /api/auth

spring:
  application:
    name: kb-user-auth
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/kb_user?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: 123456
    druid:
      initial-size: 10
      max-active: 100
      min-idle: 10
      max-wait: 60000
      pool-prepared-statements: true
      max-pool-prepared-statement-per-connection-size: 20
      time-between-eviction-runs-millis: 60000
      min-evictable-idle-time-millis: 300000
      validation-query: SELECT 1 FROM DUAL
      test-while-idle: true
      test-on-borrow: false
      test-on-return: false

# MyBatis Plus配置
mybatis-plus:
  mapper-locations: classpath*:/mapper/**/*.xml
  type-aliases-package: com.knowledge.base.*.entity
  configuration:
    map-underscore-to-camel-case: true
    cache-enabled: false
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      id-type: ASSIGN_ID
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0

# Knife4j配置
knife4j:
  enable: true
  setting:
    language: zh_cn
  production: false

5.5 创建实体类

创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/entity/User.java:

package com.knowledge.base.userauth.entity;

import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableName;
import com.knowledge.base.common.config.BaseEntity;
import lombok.Data;
import lombok.EqualsAndHashCode;

/**
 * 用户实体类
 */
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("sys_user")
public class User extends BaseEntity {

    /**
     * 用户名
     */
    private String username;

    /**
     * 密码
     */
    private String password;

    /**
     * 昵称
     */
    private String nickname;

    /**
     * 邮箱
     */
    private String email;

    /**
     * 手机号
     */
    private String phone;

    /**
     * 头像
     */
    private String avatar;

    /**
     * 用户状态(0-正常,1-禁用)
     */
    private Integer status;

    /**
     * 用户类型(0-普通用户,1-管理员)
     */
    private Integer userType;

    /**
     * 备注
     */
    private String remark;
}

创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/entity/Role.java:

package com.knowledge.base.userauth.entity;

import com.baomidou.mybatisplus.annotation.TableName;
import com.knowledge.base.common.config.BaseEntity;
import lombok.Data;
import lombok.EqualsAndHashCode;

/**
 * 角色实体类
 */
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("sys_role")
public class Role extends BaseEntity {

    /**
     * 角色名称
     */
    private String roleName;

    /**
     * 角色编码
     */
    private String roleCode;

    /**
     * 排序
     */
    private Integer sort;

    /**
     * 角色状态(0-正常,1-禁用)
     */
    private Integer status;

    /**
     * 备注
     */
    private String remark;
}

创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/entity/Permission.java:

package com.knowledge.base.userauth.entity;

import com.baomidou.mybatisplus.annotation.TableName;
import com.knowledge.base.common.config.BaseEntity;
import lombok.Data;
import lombok.EqualsAndHashCode;

/**
 * 权限实体类
 */
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("sys_permission")
public class Permission extends BaseEntity {

    /**
     * 父权限ID
     */
    private Long parentId;

    /**
     * 权限名称
     */
    private String permissionName;

    /**
     * 权限编码
     */
    private String permissionCode;

    /**
     * 权限类型(0-目录,1-菜单,2-按钮)
     */
    private Integer permissionType;

    /**
     * 路由地址
     */
    private String path;

    /**
     * 组件路径
     */
    private String component;

    /**
     * 图标
     */
    private String icon;

    /**
     * 排序
     */
    private Integer sort;

    /**
     * 权限状态(0-正常,1-禁用)
     */
    private Integer status;

    /**
     * 备注
     */
    private String remark;
}

5.6 创建Mapper接口

创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/mapper/UserMapper.java:

package com.knowledge.base.userauth.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.knowledge.base.userauth.entity.User;
import org.apache.ibatis.annotations.Mapper;

/**
 * 用户Mapper接口
 */
@Mapper
public interface UserMapper extends BaseMapper<User> {
}

创建对应的XML映射文件 kb-user-auth/src/main/resources/mapper/UserMapper.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.knowledge.base.userauth.mapper.UserMapper">

</mapper>

5.7 创建Service层

创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/service/UserService.java:

package com.knowledge.base.userauth.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.knowledge.base.userauth.entity.User;

/**
 * 用户服务接口
 */
public interface UserService extends IService<User> {

    /**
     * 根据用户名查询用户
     *
     * @param username 用户名
     * @return 用户信息
     */
    User getByUsername(String username);
}

创建实现类 kb-user-auth/src/main/java/com/knowledge/base/userauth/service/impl/UserServiceImpl.java:

package com.knowledge.base.userauth.service.impl;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.knowledge.base.userauth.entity.User;
import com.knowledge.base.userauth.mapper.UserMapper;
import com.knowledge.base.userauth.service.UserService;
import org.springframework.stereotype.Service;

/**
 * 用户服务实现类
 */
@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {

    @Override
    public User getByUsername(String username) {
        LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
        wrapper.eq(User::getUsername, username);
        return this.getOne(wrapper);
    }
}

5.8 创建Controller层

创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/controller/UserController.java:

package com.knowledge.base.userauth.controller;

import com.knowledge.base.common.result.Result;
import com.knowledge.base.userauth.entity.User;
import com.knowledge.base.userauth.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

/**
 * 用户控制器
 */
@Tag(name = "用户管理")
@RestController
@RequestMapping("/user")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    /**
     * 根据ID查询用户
     */
    @Operation(summary = "查询用户详情")
    @GetMapping("/{id}")
    public Result<User> getById(@PathVariable Long id) {
        User user = userService.getById(id);
        return Result.success(user);
    }

    /**
     * 新增用户
     */
    @Operation(summary = "新增用户")
    @PostMapping
    public Result<Void> save(@RequestBody User user) {
        userService.save(user);
        return Result.success();
    }

    /**
     * 更新用户
     */
    @Operation(summary = "更新用户")
    @PutMapping
    public Result<Void> update(@RequestBody User user) {
        userService.updateById(user);
        return Result.success();
    }

    /**
     * 删除用户
     */
    @Operation(summary = "删除用户")
    @DeleteMapping("/{id}")
    public Result<Void> delete(@PathVariable Long id) {
        userService.removeById(id);
        return Result.success();
    }
}

六、创建其他服务模块

按照上述用户权限服务模块的创建方式,你可以继续创建其他服务模块。以下是各个服务的基本结构:

6.1 文档服务 (kb-document)

mkdir -p kb-document/src/main/java/com/knowledge/base/document
mkdir -p kb-document/src/main/resources

核心功能:

  • 文档管理(CRUD)
  • 文档分类
  • 文档标签
  • 文档评论
  • 文档版本管理

6.2 搜索服务 (kb-search)

mkdir -p kb-search/src/main/java/com/knowledge/base/search
mkdir -p kb-search/src/main/resources

核心功能:

  • 文档全文搜索
  • 搜索建议
  • 搜索历史记录

6.3 文件服务 (kb-file)

mkdir -p kb-file/src/main/java/com/knowledge/base/file
mkdir -p kb-file/src/main/resources

核心功能:

  • 文件上传/下载
  • 文件存储管理
  • 支持多种存储方式(本地、OSS、S3等)

6.4 AI服务 (kb-ai)

mkdir -p kb-ai/src/main/java/com/knowledge/base/ai
mkdir -p kb-ai/src/main/resources

核心功能:

  • AI对话
  • 文档智能处理
  • AI反馈管理

6.5 知识图谱服务 (kb-graph)

mkdir -p kb-graph/src/main/java/com/knowledge/base/graph
mkdir -p kb-graph/src/main/resources

核心功能:

  • 知识图谱构建
  • 图谱关系查询
  • 社区发现算法

6.6 统计服务 (kb-statistics)

mkdir -p kb-statistics/src/main/java/com/knowledge/base/statistics
mkdir -p kb-statistics/src/main/resources

核心功能:

  • 用户行为统计
  • 文档访问统计
  • 数据趋势分析

6.7 基础服务 (kb-foundation)

mkdir -p kb-foundation/src/main/java/com/knowledge/base/foundation
mkdir -p kb-foundation/src/main/resources

核心功能:

  • 数据字典管理
  • 系统配置管理
  • 操作日志记录
  • 通知管理

6.8 API网关 (kb-gateway)

mkdir -p kb-gateway/src/main/java/com/knowledge/base/gateway
mkdir -p kb-gateway/src/main/resources

核心功能:

  • 路由转发
  • 统一鉴权
  • 限流熔断
  • 日志记录

七、数据库设计

7.1 创建数据库初始化脚本

在项目根目录创建 sql 文件夹,并添加初始化脚本。

创建用户权限数据库脚本 sql/init_kb_user.sql:

-- 创建数据库
CREATE DATABASE IF NOT EXISTS kb_user DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

USE kb_user;

-- 用户表
CREATE TABLE IF NOT EXISTS sys_user (
    id BIGINT NOT NULL COMMENT '用户ID',
    username VARCHAR(50) NOT NULL COMMENT '用户名',
    password VARCHAR(100) NOT NULL COMMENT '密码',
    nickname VARCHAR(50) COMMENT '昵称',
    email VARCHAR(100) COMMENT '邮箱',
    phone VARCHAR(20) COMMENT '手机号',
    avatar VARCHAR(255) COMMENT '头像',
    status TINYINT DEFAULT 0 COMMENT '状态(0-正常,1-禁用)',
    user_type TINYINT DEFAULT 0 COMMENT '用户类型(0-普通用户,1-管理员)',
    remark VARCHAR(500) COMMENT '备注',
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    create_by BIGINT COMMENT '创建人ID',
    update_by BIGINT COMMENT '更新人ID',
    deleted TINYINT DEFAULT 0 COMMENT '删除标记(0-未删除,1-已删除)',
    PRIMARY KEY (id),
    UNIQUE KEY uk_username (username)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

-- 角色表
CREATE TABLE IF NOT EXISTS sys_role (
    id BIGINT NOT NULL COMMENT '角色ID',
    role_name VARCHAR(50) NOT NULL COMMENT '角色名称',
    role_code VARCHAR(50) NOT NULL COMMENT '角色编码',
    sort INT DEFAULT 0 COMMENT '排序',
    status TINYINT DEFAULT 0 COMMENT '状态(0-正常,1-禁用)',
    remark VARCHAR(500) COMMENT '备注',
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    create_by BIGINT COMMENT '创建人ID',
    update_by BIGINT COMMENT '更新人ID',
    deleted TINYINT DEFAULT 0 COMMENT '删除标记(0-未删除,1-已删除)',
    PRIMARY KEY (id),
    UNIQUE KEY uk_role_code (role_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色表';

-- 权限表
CREATE TABLE IF NOT EXISTS sys_permission (
    id BIGINT NOT NULL COMMENT '权限ID',
    parent_id BIGINT DEFAULT 0 COMMENT '父权限ID',
    permission_name VARCHAR(50) NOT NULL COMMENT '权限名称',
    permission_code VARCHAR(100) NOT NULL COMMENT '权限编码',
    permission_type TINYINT DEFAULT 1 COMMENT '权限类型(0-目录,1-菜单,2-按钮)',
    path VARCHAR(200) COMMENT '路由地址',
    component VARCHAR(200) COMMENT '组件路径',
    icon VARCHAR(100) COMMENT '图标',
    sort INT DEFAULT 0 COMMENT '排序',
    status TINYINT DEFAULT 0 COMMENT '状态(0-正常,1-禁用)',
    remark VARCHAR(500) COMMENT '备注',
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    create_by BIGINT COMMENT '创建人ID',
    update_by BIGINT COMMENT '更新人ID',
    deleted TINYINT DEFAULT 0 COMMENT '删除标记(0-未删除,1-已删除)',
    PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='权限表';

-- 用户角色关联表
CREATE TABLE IF NOT EXISTS sys_user_role (
    id BIGINT NOT NULL COMMENT '主键ID',
    user_id BIGINT NOT NULL COMMENT '用户ID',
    role_id BIGINT NOT NULL COMMENT '角色ID',
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    PRIMARY KEY (id),
    KEY idx_user_id (user_id),
    KEY idx_role_id (role_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户角色关联表';

-- 角色权限关联表
CREATE TABLE IF NOT EXISTS sys_role_permission (
    id BIGINT NOT NULL COMMENT '主键ID',
    role_id BIGINT NOT NULL COMMENT '角色ID',
    permission_id BIGINT NOT NULL COMMENT '权限ID',
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    PRIMARY KEY (id),
    KEY idx_role_id (role_id),
    KEY idx_permission_id (permission_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色权限关联表';

7.2 执行初始化脚本

mysql -u root -p < sql/init_kb_user.sql

八、测试验证

8.1 编译项目

# 在项目根目录执行
mvn clean compile

8.2 启动服务

# 启动用户权限服务
cd kb-user-auth
mvn spring-boot:run

8.3 访问API文档

启动成功后,访问 Knife4j 文档:

http://localhost:8081/api/auth/doc.html

8.4 测试接口

使用 Postman 或 Apifox 测试用户接口:

新增用户:

POST http://localhost:8081/api/auth/user
Content-Type: application/json

{
  "username": "testuser",
  "password": "123456",
  "nickname": "测试用户",
  "email": "test@example.com"
}

查询用户:

GET http://localhost:8081/api/auth/user/1

九、项目规范

9.1 命名规范

类型规范示例
类名大驼峰UserService
方法名小驼峰getUserById
变量名小驼峰userName
常量名全大写+下划线MAX\_SIZE
包名全小写com.knowledge.base.service

9.2 代码结构规范

每个服务模块遵循以下结构:

kb-xxx/
├── src/main/java/com/knowledge/base/xxx/
│   ├── controller/      # 控制器层
│   ├── service/         # 服务接口层
│   │   └── impl/        # 服务实现层
│   ├── mapper/          # 数据访问层
│   ├── entity/          # 实体类
│   ├── dto/             # 数据传输对象
│   ├── vo/              # 视图对象
│   ├── config/          # 配置类
│   └── utils/           # 工具类
└── src/main/resources/
    ├── application.yml  # 配置文件
    └── mapper/          # MyBatis映射文件

9.3 注释规范

所有类必须添加JavaDoc注释:

/**
 * 用户服务实现类
 *
 * @author 张三
 * @since 2026-05-11
 */
public class UserServiceImpl implements UserService {
    /**
     * 根据用户名查询用户
     *
     * @param username 用户名
     * @return 用户信息
     */
    public User getByUsername(String username) {
        // ...
    }
}

十、常见问题

10.1 Maven依赖下载失败

解决方案:

  1. 检查网络连接
  2. 配置阿里云Maven镜像(已在pom.xml中配置)
  3. 清除本地仓库缓存:rm -rf ~/.m2/repository

10.2 数据库连接失败

解决方案:

  1. 检查MySQL服务是否启动
  2. 检查用户名密码是否正确
  3. 检查数据库是否已创建
  4. 检查端口是否正确(默认3306)

10.3 端口被占用

解决方案:

  1. 查找占用端口的进程:lsof -i :8081
  2. 杀死进程或修改配置文件中的端口

10.4 MyBatis Plus找不到Mapper

解决方案:

  1. 检查@Mapper注解是否添加
  2. 检查mapper-locations配置是否正确
  3. 检查XML文件的namespace是否正确

总结

本文带你搭建了一个企业级知识库管理系统的后端项目骨架。

通过本文的学习,你应该掌握了:

  1. Spring Boot 3.x多模块项目的搭建方法
  2. MyBatis Plus的集成和配置
  3. 统一响应结构和异常处理的设计
  4. 微服务架构的模块划分方法
  5. RESTful API的设计规范

希望这篇教程对你有所帮助,祝你在项目开发中一切顺利!

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏