前言

这篇文章专门跟大家一起聊聊"工程与代码结构",用尽可能专业、可复用的方式,带你快速读懂本项目的组织方式与关键模块边界。

一、工程入口:多模块 Maven 项目如何启动与自动装配如何收敛

项目是一个 Maven 多模块工程,父 POM 定义了统一的 Spring Boot 3.2.0 和 Spring Cloud 2023.0.0 依赖版本。

共 10 个子模块:9 个可独立部署的微服务 + 1 个共享库(kb-common)。

每个微服务都有独立的 *Application.java 启动类,但启动模式遵循统一规范:

// kb-document 的启动类 — 典型模式代表
@SpringBootApplication
@ComponentScan(basePackages = {"com.knowledge.base.document", "com.knowledge.base.common"})
@MapperScan("com.knowledge.base.document.mapper")
@EnableFeignClients(basePackages = {"com.knowledge.base.document.feign", "com.knowledge.base.common.feign"})
@EnableScheduling
public class DocumentApplication {
    public static void main(String[] args) {
        SpringApplication.run(DocumentApplication.class, args);
    }
}

启动类的几个关键约定:

  • 双包扫描:每个服务同时扫描自己的业务包和 com.knowledge.base.common,确保共享库的 Bean(BaseEntity、Result、MybatisPlusConfig、全局异常处理等)自动生效
  • 排除模式:Gateway 排除了 DataSourceAutoConfiguration(无数据库),Graph 同样排除(主存储为 Neo4j)
  • Feign 收敛:@EnableFeignClients 精确指定包路径,避免扫描到不相关模块的 Feign 接口
  • 统一注解组合:@MapperScan + @EnableFeignClients + @EnableScheduling,按需装配

这种设计意味着:每个服务可以独立启动调试,同时共享 kb-common 的全部基础设施能力(ID 生成、统一响应、全局异常、JWT 工具等)。

源码参考:

  • kb-document/src/main/java/com/knowledge/base/document/DocumentApplication.java
  • kb-gateway/src/main/java/com/knowledge/base/gateway/GatewayApplication.java
  • kb-ai/src/main/java/com/knowledge/base/ai/AiApplication.java

二、顶层包结构:按业务领域拆分,共享库集中收敛通用能力

com.knowledge.base 的顶层组织方式分为两条线:

  1. 共享库:kb-common(打包为 JAR),收敛所有跨模块复用的基础设施
  2. 业务服务:kb-{gateway,user-auth,document,search,file,ai,graph,statistics,foundation},每个是独立的 Spring Boot 应用,拥有独立数据库

这是一个典型的"数据库隔离、服务自治"微服务代码形态:每个服务可以独立开发、测试、部署,但共享库确保通用能力的一致性。

共享库 kb-common 包结构

com.knowledge.base.common
├── annotation/      # @OperationLog, @RequirePermission 等自定义注解
├── aspect/          # OperationLogAspect 切面
├── config/          # BaseEntity, MybatisPlusConfig, CorsConfig, SystemConfigCache
├── constants/       # 跨模块共享常量
├── enums/           # OperationType, UserStatus, DocumentStatus 等枚举
├── event/           # 事件 DTO(ReviewEventDTO, StatisticsEventDTO)
├── exception/       # BusinessException, GlobalExceptionHandler
├── feign/           # FeignInterceptorConfig(INNER-REQUEST 头注入)
├── handler/         # MyMetaObjectHandler(审计字段自动填充)
├── result/          # Result<T>, PageResult<T>, ResultCode
└── utils/           # SnowflakeIdGenerator, JwtUtil, UserContextUtil, SecurityUtil

业务服务统一包结构(以 kb-document 为例)

com.knowledge.base.document
├── DocumentApplication.java       # 启动类
├── config/                        # 模块专属配置(SecurityConfig 等)
├── controller/                    # REST 入口(薄层,仅协议转换)
├── dto/                           # 请求入参对象
├── entity/                        # MySQL 实体(@TableName)
│   └── mongodb/                   # MongoDB 实体(文档内容)
├── event/                         # RabbitMQ 事件发布器
├── feign/                         # 调用其他服务的 Feign 接口
├── filter/                        # Servlet 过滤器
├── mapper/                        # MyBatis-Plus Mapper 接口
├── service/                       # 业务接口
│   └── impl/                      # 业务实现
├── task/                          # 定时任务(分类文档数同步)
├── vo/                            # 响应出参对象
└── constants/                     # 模块常量

这种统一的包结构意味着:任何一个开发者切换到不同服务时,都能立刻知道在哪里找到 Controller、Service、Mapper、Entity。

源码参考(目录):

  • kb-common/src/main/java/com/knowledge/base/common/
  • kb-document/src/main/java/com/knowledge/base/document/
  • kb-ai/src/main/java/com/knowledge/base/ai/

三、Controller:入口不做"业务",只做"协议转换与编排调用"

所有 Controller 遵循一个核心原则:薄层。Controller 的方法只做三件事:

  1. 参数校验(@Valid + Spring Validation)
  2. DTO → Service 入参转换
  3. 调用 Service → 包装 Result 返回
// DocumentController — 典型薄Controller模式
@GetMapping("/{documentId}")
@Operation(summary = "获取文档详情")
@PreAuthorize("hasAnyAuthority(T(...DocumentPermissionConstants).DOCUMENT_EDIT, ...)")
public Result<DocumentVO> getDocument(@PathVariable Long documentId) {
    DocumentVO documentVO = documentService.getDocumentById(documentId);
    return Result.success(documentVO);
}

绝不出现于 Controller 中的东西:数据库查询代码、复杂的 if-else 业务判断、直接 new 业务对象。

从文件列表可见入口覆盖面:

  • 业务:DocumentController、CommentController、CategoryController、TagController、ShareController
  • 审核:DocumentReviewController(提交/审批/驳回/批量审核)
  • 搜索:SearchController(全文检索/混合检索)
  • AI:AiChatController、RagChatController、RagSearchController、KAGChatController
  • 通用:UserController、NotificationController、StatisticsController

这类入口层满足三个工程约束:

  • DTO 明确:请求/响应结构通过 @Schema 注解标注,Knife4j 自动生成 API 文档
  • 权限一致:统一的 @PreAuthorize + 方法级权限检查,Gateway 层已注入 userId
  • 异常统一:GlobalExceptionHandler 区分内部调用(Feign)和外部调用(前端),返回不同格式

源码参考:

  • kb-document/src/main/java/com/knowledge/base/document/controller/DocumentController.java
  • kb-document/src/main/java/com/knowledge/base/document/controller/DocumentReviewController.java
  • kb-common/src/main/java/com/knowledge/base/common/exception/GlobalExceptionHandler.java

四、Service:核心业务编排集中在这里(并按能力子域拆分)

service/ 是每个模块的中心,它不是"扁平的大包",而是按能力边界清晰划分。

4.1 文档管理:DocumentServiceImpl 是 kb-document 的中枢

DocumentServiceImpl 体现了项目最核心的工程特征:

  • 多存储协调:MySQL(元数据) + MongoDB(富文本内容) + Elasticsearch(全文索引)
  • 异步事件驱动:创建/更新/删除文档后,通过 RabbitMQ 发布事件驱动统计服务更新、通知服务推送
  • AI 索引联动:文档发布后异步触发 RAG 分块索引、KAG 图谱构建、ES 搜索索引
  • 事务边界控制:核心 CRUD 在 MySQL 事务内完成,AI 索引构建在事务提交后异步执行

从实现中可以看到"事务内 + 事务后"的清晰分工:

@Override
@Transactional(rollbackFor = Exception.class)
public Long createDocument(DocumentDTO dto) {
    // 1. 事务内:保存 MySQL 元数据 + MongoDB 内容
    Document document = buildDocument(dto);
    documentMapper.insert(document);
    documentContentService.saveContent(document.getId(), dto.getContent());

    // 2. 发布后:异步触发 AI 索引(事务提交后才执行)
    CompletableFuture.runAsync(() -> {
        triggerRagReindex(document.getId());
        triggerKAGBuild(document.getId());
        triggerSearchIndex(document);
        triggerGraphBuild(document.getId());
    }, asyncTaskExecutor);

    return document.getId();
}

点赞功能则体现了"数据库唯一约束防竞态 + MyBatis-Plus 类型安全操作"的工程化做法:

// LikeServiceImpl — INSERT-first + DuplicateKeyException 防重复点赞
@Override
public void like(Long targetId, Long userId, Integer targetType) {
    Like like = new Like();
    like.setTargetId(targetId);
    like.setUserId(userId);
    like.setTargetType(targetType);
    try {
        likeMapper.insert(like);
    } catch (DuplicateKeyException e) {
        throw new BusinessException("已经点赞过了");
    }
}

tb_like 表上设置了 UNIQUE KEY uk_target_user_type (target_id, user_id, target_type),利用数据库唯一约束天然防并发重复插入。

源码参考:

  • kb-document/src/main/java/com/knowledge/base/document/service/impl/DocumentServiceImpl.java
  • kb-document/src/main/java/com/knowledge/base/document/service/impl/LikeServiceImpl.java

4.2 审核工作流:DocumentReviewServiceImpl 是状态机的执行引擎

审核服务承载了文档从"草稿"到"发布"的状态流转逻辑:

// approveReview — 审核通过的核心流转
@Override
@Transactional(rollbackFor = Exception.class)
public Boolean approveReview(DocumentReviewDTO dto) {
    // 1. 更新审核记录
    DocumentReview review = baseMapper.selectById(dto.getReviewId());
    review.setReviewResult(1);
    review.setReviewComment(dto.getReviewComment());
    review.setReviewerId(UserContext.getCurrentUserId());
    review.setReviewTime(LocalDateTime.now());
    baseMapper.updateById(review);

    // 2. 更新文档状态:pending_review → published
    Document document = documentMapper.selectById(review.getDocumentId());
    document.setStatus("published");
    documentMapper.updateById(document);

    // 3. 异步事件:触发 AI 索引 + 发送通知
    triggerIndexAndNotify(document);

    return true;
}

关键设计点:

  • 状态机集中:submitForReview / approveReview / rejectReview 各自封装完整的状态变更逻辑
  • 事件解耦:审核结果通过 RabbitMQ 事件传递给通知服务,不阻塞审核主流程
  • 下一轮审核:submitForReview 会计算 reviewRound + 1,支持审核-驳回-重提的循环

源码参考:

  • kb-document/src/main/java/com/knowledge/base/document/service/impl/DocumentReviewServiceImpl.java
  • kb-document/src/main/java/com/knowledge/base/document/entity/DocumentReview.java

4.3 AI 子系统:kb-ai 是一个"可插拔"的多模型适配层

AI 子系统的结构有明显的工程化设计痕迹:

  • ModelProvider 统一工厂:所有模型通过 ModelProvider 集中管理,使用 ConcurrentHashMap 懒加载实例
  • OpenAI 兼容接口:Qwen 和 DeepSeek 都通过 langchain4j 的 OpenAiChatModel 接入,因为它们都兼容 OpenAI API 格式
  • 模型可用性检查:@PostConstruct 阶段检查 API Key 配置,只注册已配置的模型
  • 默认模型降级:如果 defaultModel 不可用,自动 fallback 到第一个可用模型
// ModelProvider — 多模型统一管理
@Component
public class ModelProvider {
    @Value("${qwen.api-key}")    private String qwenApiKey;
    @Value("${deepseek.api-key}") private String deepseekApiKey;

    private final Map<String, ChatLanguageModel> instanceCache = new ConcurrentHashMap<>();
    private final Map<String, Boolean> modelAvailable = new LinkedHashMap<>();

    @PostConstruct
    public void init() {
        checkAndRegister("qwen", "通义千问", "...", qwenApiKey);
        checkAndRegister("deepseek", "DeepSeek", "...", deepseekApiKey);
    }

    public ChatLanguageModel getModel(String modelName) {
        if (!modelAvailable.containsKey(modelName)) {
            throw new BusinessException("模型未配置或不可用:" + modelName);
        }
        return instanceCache.computeIfAbsent(modelName, this::buildModel);
    }

    private ChatLanguageModel buildModel(String modelName) {
        switch (modelName) {
            case "qwen":
                return OpenAiChatModel.builder().baseUrl(qwenBaseUrl)
                        .apiKey(qwenApiKey).modelName(qwenModel)
                        .maxTokens(qwenMaxTokens).temperature(qwenTemperature).build();
            case "deepseek":
                return OpenAiChatModel.builder().baseUrl(deepseekBaseUrl)
                        .apiKey(deepseekApiKey).modelName(deepseekModel)
                        .maxTokens(deepseekMaxTokens).temperature(deepseekTemperature).build();
            default: throw new IllegalStateException("未知模型:" + modelName);
        }
    }
}

AiChatServiceImpl.chat() 中展示了"RAG 可选增强 + 优雅降级"的模式:

// RAG 作为可选增强,降级不影响主对话能力
if (enableRag && ragChatService != null) {
    try {
        return ragChatService.chatWithContext(requestDTO, userId);
    } catch (Exception e) {
        log.warn("RAG 检索失败,降级为普通对话", e);
    }
}
// 降级:纯 LLM 对话
ChatLanguageModel model = modelProvider.getModel(requestDTO.getModel());
Response<AiMessage> response = model.generate(messages);

这意味着:RAG 不可用时,用户仍然可以正常使用 AI 对话功能,只是没有知识库上下文增强。

源码参考:

  • kb-ai/src/main/java/com/knowledge/base/ai/config/ModelProvider.java
  • kb-ai/src/main/java/com/knowledge/base/ai/service/impl/AiChatServiceImpl.java

4.4 RAG 检索管道:RagRetrievalService 是知识增强的可选链路

从 AiChatServiceImpl 的实现可以明确看到:RAG 是一个可选增强能力,由前端参数 enableRag 决定是否执行检索。

RAG 的检索管道是一条完整的流水线:

用户问题 → Embedding 向量化 → 混合检索(BM25 + kNN)→ RRF 融合 → 可选重排序 → 构建增强 Prompt
// RagRetrievalServiceImpl — 核心检索管道
@Override
public List<RagSearchResultVO> retrieve(String query, int topK, boolean enableRerank) {
    // 1. 向量化
    float[] embedding = embeddingService.embed(query);

    // 2. 混合检索(BM25 + kNN + RRF 融合)
    List<RagSearchResultVO> results = vectorIndexService.searchHybrid(
        query, embedding, properties.getRetrieval().getHybridTopK());

    // 3. 可选:LLM 重排序
    if (enableRerank && results.size() > topK) {
        results = rerank(query, results);
    }

    return results.subList(0, Math.min(topK, results.size()));
}

检索实现各环节都有降级处理:

  • Embedding 失败 → fallback 到纯 BM25 关键词检索
  • 检索结果为空 → 在 Prompt 中明确告知 LLM "知识库中无相关信息"
  • RAG 整体异常 → 不阻塞对话,降级为纯 LLM 回答

RagChatServiceImpl.buildRagPrompt() 构建的结构化 Prompt 是 RAG 效果的关键:

你是一个企业知识库助手。请仅根据以下参考资料回答用户的问题。
如果参考资料中没有相关信息,请说明【根据现有知识库暂时无法回答此问题】。

参考资料:
[1] 来源文档:Spring Boot 3.x 快速入门指南 | 章节:自动配置原理
    Spring Boot 的自动配置通过 @EnableAutoConfiguration 注解触发...
[2] ...

=== 用户问题 ===
Spring Boot 自动配置的原理是什么?

源码参考:

  • kb-ai/src/main/java/com/knowledge/base/ai/rag/service/impl/RagRetrievalServiceImpl.java
  • kb-ai/src/main/java/com/knowledge/base/ai/rag/service/impl/RagChatServiceImpl.java
  • kb-ai/src/main/java/com/knowledge/base/ai/config/RagProperties.java

4.5 权限与认证:Gateway AuthGlobalFilter + Spring Security 双层配合

认证体系是两层结构:

第一层(Gateway):AuthGlobalFilter 解析 JWT,将 userId 注入 X-User-Id 请求头。

// AuthGlobalFilter — Gateway 层 JWT 解析 + Header 注入
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    String path = request.getURI().getPath();
    if (shouldSkip(path, method)) return chain.filter(exchange);  // 白名单放行

    String token = extractToken(request);  // Authorization header 或 cookie
    if (token == null) return chain.filter(exchange);

    try {
        Long userId = jwtTokenUtil.getUserIdFromToken(token);
        if (userId != null) {
            ServerHttpRequest modifiedRequest = request.mutate()
                    .header("X-User-Id", String.valueOf(userId))
                    .build();
            return chain.filter(exchange.mutate().request(modifiedRequest).build());
        }
    } catch (Exception e) { /* 解析失败:当做未登录 */ }
    return chain.filter(exchange);
}

@Override
public int getOrder() { return -200; }  // 早于所有其他过滤器执行

第二层(各业务服务):JwtAuthenticationFilter 读取 X-User-Id 头,验证 Token,设置 UserContextUtil 的 ThreadLocal。

// kb-user-auth SecurityConfig — 无状态 JWT 方案
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .csrf(AbstractHttpConfigurer::disable)
        .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS))  // 无状态
        .addFilterBefore(jwtAuthenticationFilter,
                UsernamePasswordAuthenticationFilter.class)
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/auth/login", "/auth/register", ...).permitAll()
            .requestMatchers("/auth/validate", "/auth/users/by-role").permitAll()  // Feign 内部
            .anyRequest().authenticated())
        .exceptionHandling(ex -> ex
            .authenticationEntryPoint(authEntryPoint)
            .accessDeniedHandler(accessDeniedHandler));
    return http.build();
}

设计要点:

  • 白名单包括公共 API(登录/注册)和 Feign 内部调用端点(/auth/validate、/auth/users/by-role)
  • 白名单中的路径只依赖 INNER-REQUEST 请求头进行身份校验,不强制要求 JWT
  • UserContextUtil 使用 ThreadLocal 存储用户上下文,请求结束自动清理

源码参考:

  • kb-gateway/src/main/java/com/knowledge/base/gateway/filter/AuthGlobalFilter.java
  • kb-user-auth/src/main/java/com/knowledge/base/userauth/config/SecurityConfig.java
  • kb-common/src/main/java/com/knowledge/base/common/utils/UserContextUtil.java

4.6 跨服务通信:Feign 同步 + RabbitMQ 异步 + WebSocket 实时推送

项目使用了三种跨服务通信方式,各有明确适用场景:

Feign(同步调用):用于请求-响应模式的同步查询。

// kb-document → kb-file 的文件上传调用
@FeignClient(name = "kb-file", path = "/files")
public interface FileServiceFeignClient {
    @PostMapping("/upload")
    Result<FileUploadVO> upload(@RequestBody MultipartFile file);
}

所有 Feign 调用通过 FeignInterceptorConfig 自动注入 INNER-REQUEST: true 头,下游服务的 GlobalExceptionHandler 根据此头判断异常返回格式。

RabbitMQ(异步事件):用于解耦的异步通知。

// kb-foundation 消费审核事件 → 推送 WebSocket 通知
@RabbitListener(queues = "kb.notification.review.queue")
public void handleReviewEvent(ReviewEventDTO event) {
    if ("SUBMITTED".equals(event.getEventType())) {
        // 查询所有审核员 → 持久化通知 → WebSocket 推送
        List<Long> reviewerIds = userAuthFeignClient.getReviewerIds();
        for (Long reviewerId : reviewerIds) {
            notificationService.sendNotification(buildNotification(event, reviewerId));
            messagingTemplate.convertAndSendToUser(
                String.valueOf(reviewerId), "/queue/notifications", payload);
        }
    }
}

WebSocket(实时推送):用于前端实时通知。

// WebSocket 配置 — STOMP 协议 + SockJS 降级
@Override
public void registerStompEndpoints(StompEndpointRegistry registry) {
    registry.addEndpoint("/ws/notification")
            .setAllowedOriginPatterns("*")
            .addInterceptors(webSocketHandshakeInterceptor)
            .withSockJS();  // 浏览器不支持 WebSocket 时降级为 HTTP 长轮询
}

三种通信方式的明确边界:

  • Feign:服务间数据查询(如审核时查询用户信息)
  • RabbitMQ:事件驱动解耦(审核结果通知、统计数据更新)
  • WebSocket:服务端主动推送到前端(实时通知弹窗)

源码参考:

  • kb-common/src/main/java/com/knowledge/base/common/feign/FeignInterceptorConfig.java
  • kb-foundation/src/main/java/com/knowledge/base/foundation/mq/ReviewNotificationListener.java
  • kb-foundation/src/main/java/com/knowledge/base/foundation/websocket/WebSocketConfig.java

五、Mapper + Entity:数据模型与访问边界清晰

项目使用 MyBatis-Plus 作为 ORM 框架:

  • entity/ 负责映射数据库表,所有实体继承 BaseEntity
  • mapper/ 负责数据访问,继承 BaseMapper<T> 获得 CRUD 能力

从实体设计可见典型的知识库领域建模:

  • 文档域:Document、DocumentVersion、DocumentReview、Category、Tag
  • 社交域:Comment、Like
  • AI 域:Conversation、Message、AiFeedback
  • 通知域:Notification、NotificationTemplate
  • RBAC 域:User、Role、Permission、UserRole、RolePermission

所有实体共享 BaseEntity 的标准字段:

@Data
public abstract class BaseEntity implements Serializable {
    @TableId(type = IdType.INPUT)
    private Long id;                    // Snowflake ID,INSERT 前通过 preInsert() 自动赋值

    @TableField(value = "created_at", fill = FieldFill.INSERT)
    private LocalDateTime createdAt;

    @TableField(value = "updated_at", fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updatedAt;

    @TableField(fill = FieldFill.INSERT)
    private Long createBy;

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Long updateBy;

    @TableLogic
    private Integer deleted;            // 0 = 正常, 1 = 已删除

    public void preInsert() {
        if (this.id == null) {
            this.id = SnowflakeIdGenerator.getInstance().nextId();
        }
    }
}

设计要点:

  • IdType.INPUT:不再依赖 MyBatis-Plus 默认的雪花 ID,改由 MyMetaObjectHandler 在 preInsert() 阶段统一生成,保证跨模块 ID 唯一
  • @TableLogic:所有删除操作自动转换为 UPDATE SET deleted = 1,数据不物理删除
  • FieldFill:created_at 在插入时自动填充,updated_at 在插入和更新时自动填充
  • MyMetaObjectHandler 负责自动填充审计字段,从 UserContextUtil 获取当前操作人

源码参考:

  • kb-common/src/main/java/com/knowledge/base/common/config/BaseEntity.java
  • kb-common/src/main/java/com/knowledge/base/common/handler/MyMetaObjectHandler.java
  • kb-document/src/main/java/com/knowledge/base/document/entity/

六、Config:外部依赖与开关都收敛到配置层

配置层的文件名已经能体现模块边界与依赖:

kb-common 通用配置:

  • MybatisPlusConfig:分页插件 + 乐观锁 + 防全表更新/删除 + 自定义 ID 生成器
  • CorsConfig:跨域配置
  • JacksonAutoConfiguration:Jackson 序列化规则(日期/枚举/Long 精度)
  • AsyncTaskConfig:异步任务线程池配置
  • SystemConfigCache:系统配置本地缓存

kb-ai AI 配置:

  • ModelProvider:多模型工厂(Qwen/DeepSeek 实例管理 + 健康检查)
  • RagProperties:RAG 分块/检索/重排全参数配置
  • RagAutoConfiguration:RAG 组件条件装配

kb-gateway 网关配置:

  • AuthGlobalFilter:JWT 解析 + Header 注入
  • UnifiedResponseFilter:响应格式统一
  • CorsResponseHeaderFilter:CORS 头处理

这种"配置收敛"让 Service 层更专注于业务编排,同时不同环境(dev/prod)的切换只需修改 application.yml 或 Nacos 配置中心的值。

源码参考:

  • kb-common/src/main/java/com/knowledge/base/common/config/MybatisPlusConfig.java
  • kb-ai/src/main/java/com/knowledge/base/ai/config/ModelProvider.java
  • kb-ai/src/main/java/com/knowledge/base/ai/config/RagProperties.java

七、前端:Zustand Store + Axios 拦截器链 + 权限守卫

7.1 前端源码目录结构

src/
├── components/           # 共享 UI 组件
│   ├── auth/             # 登录/注册
│   ├── layout/           # 应用布局(侧边栏/顶栏/内容区)
│   ├── document/         # 文档相关组件
│   ├── comment/          # 评论组件
│   └── common/           # 通用 UI 组件
├── pages/                # 页面组件
│   ├── DashboardPage     # 仪表盘
│   ├── DocumentDetailPage # 文档详情(点赞/评论/分享)
│   ├── CreateDocumentPage # 创建文档
│   ├── AIAssistantPage   # AI 对话助手
│   ├── KnowledgeGraphPage # 知识图谱可视化
│   └── admin/            # 管理后台子页面
├── stores/               # Zustand 状态管理(13 个 Store)
├── services/             # API 请求层(23 个 Service)
├── router/               # React Router 路由配置
├── types/                # TypeScript 类型定义
├── utils/                # 工具函数(Token 存储、权限检查)
└── hooks/                # 自定义 Hooks

7.2 Zustand Store 的"乐观更新 + 同步验证"模式

前端状态管理采用了 Zustand + Immer 的组合,以 document.store.ts 中的点赞功能为例:

likeDocument: async (id: string) => {
    const currentDoc = get().currentDocument;
    const isCurrentlyLiked = currentDoc?.isLiked ?? false;

    // Phase 1: 乐观 UI 更新(立即响应,不等待网络)
    if (isCurrentlyLiked) {
        await documentService.unlikeDocument(id);
    } else {
        await documentService.likeDocument(id);
    }
    set((state) => ({
        currentDocument: { ...state.currentDocument, isLiked: !isCurrentlyLiked }
    }));

    // Phase 2: 从后端重新拉取真实数据(消除乐观更新的偏差)
    try {
        const document = await documentService.getDocument(id);
        set((state) => ({
            currentDocument: {
                ...state.currentDocument,
                likeCount: document.likeCount,
                isLiked: document.isLiked,
            }
        }));
    } catch {
        // 保持乐观状态不变
    }
},

这个模式解决了两个问题:

  • 响应速度:用户点击后立即看到按钮状态变化
  • 数据正确性:后台请求完成后,用真实数据覆盖前端状态,消除并发/字符串拼接等偏差

7.3 Axios 拦截器链的双层错误处理

// 请求拦截器
request.interceptors.request.use((config) => {
    const token = getToken();
    if (token) config.headers.Authorization = `Bearer ${token}`;
    config.headers['X-Request-Id'] = generateRequestId();  // 链路追踪
    return config;
});

// 响应拦截器 — Token 刷新队列
request.interceptors.response.use(
    (response) => response.data,   // 解包统一 Result 响应体
    async (error) => {
        if (error.response?.status === 401) {
            // Token 过期:加入刷新队列,避免并发请求重复刷新
            return refreshTokenQueue.enqueue(error.config);
        }
        if (error.response?.status === 403) {
            message.error('权限不足,请联系管理员');
        }
        return Promise.reject(error);
    }
);

Token 刷新队列是这里的关键设计:当多个并发的 API 请求同时收到 401 时,只有第一个会实际触发 Token 刷新,后续请求排队等待,避免多次刷新导致 Token 冲突。

7.4 前端路由的权限守卫

// ProtectedRoute — 路由级权限检查
const ProtectedRoute: React.FC<Props> = ({ children, requiredPermissions }) => {
    const { user, isAuthenticated } = useAuthStore();

    if (!isAuthenticated) return <Navigate to="/login" />;
    if (requiredPermissions && !hasAnyPermission(user.permissions, requiredPermissions)) {
        return <Navigate to="/" />;
    }
    return <>{children}</>;
};

前端权限检查是 UI 层的"第一道防线"(后端 @PreAuthorize 是真正的安全边界):无权限的菜单项和页面不会渲染,但真正的安全控制在后端。

源码参考:

  • src/stores/document.store.ts
  • src/services/request.ts
  • src/utils/permission.ts

八、阅读路径建议(按"最短理解路径"组织)

如果你要在最短时间内理解"它是怎么跑起来并完成一次文档创建与审核的",建议按下面顺序阅读(每一步都能在源码中定位到真实逻辑):

  1. 入口与启动:kb-gateway/GatewayApplication → AuthGlobalFilter(网关如何解析 JWT)
  2. 文档创建主链路:DocumentController.createDocument() → DocumentServiceImpl.createDocument()(MySQL+MongoDB 双写 + 异步 AI 索引)
  3. 审核工作流:DocumentReviewController.submitForReview() → DocumentReviewServiceImpl.approveReview()
  4. AI 对话:AiChatController.chat() → AiChatServiceImpl.chat()(RAG 可选 → 模型调用 → 结果持久化)
  5. RAG 检索管道:RagRetrievalServiceImpl.retrieve()(Embedding → 混合检索 → RRF → 重排序)
  6. 多模型工厂:ModelProvider.init() → getModel() → buildModel()(Qwen/DeepSeek 统一接入)
  7. 事件通知闭环:ReviewNotificationListener(RabbitMQ 消费 → WebSocket 推送)
  8. 共享库基础设施:BaseEntity → Result/PageResult → MybatisPlusConfig → UserContextUtil
  9. 前端互动:document.store.ts → request.ts 拦截器链 → ProtectedRoute

九、总结

从现有代码事实出发,本项目代码结构具备以下明显的工程化特征:

  • 边界清晰:10 个微服务各司其职,kb-common 收敛共享能力,Document/AI/Review/Auth 是可独立理解与演进的服务
  • 主链路收敛:文档 CRUD 集中在 DocumentServiceImpl,审核状态机集中在 DocumentReviewServiceImpl,避免"到处都能触发文档变更"的耦合扩散
  • 可插拔能力:多模型 Provider(Qwen/DeepSeek)+ 可选 RAG + 可选 KAG + 可选重排序,组合式能力天然支持扩展
  • 工程鲁棒性:RAG 检索/Embedding/WebSocket 等外部依赖都有降级路径,避免把不可控因素放大为系统不可用
  • 事务与异步清晰:MySQL 事务内完成核心数据操作,AI 索引、ES 同步、消息推送放在事务提交后异步执行
  • 双层认证架构:Gateway 层 JWT 解析注入 Header,业务服务层读取 Header + 验证 Token + ThreadLocal 上下文
  • 数据库隔离:Database per Service,跨库查询通过视图(statistics)或 Feign(运行时查询),无分布式事务
  • 前端乐观更新:Zustand Store 的两阶段更新(乐观 UI + 后端同步验证),兼顾响应速度与数据正确性
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏