前言
这篇文章专门跟大家一起聊聊"工程与代码结构",用尽可能专业、可复用的方式,带你快速读懂本项目的组织方式与关键模块边界。
一、工程入口:多模块 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.javakb-gateway/src/main/java/com/knowledge/base/gateway/GatewayApplication.javakb-ai/src/main/java/com/knowledge/base/ai/AiApplication.java
二、顶层包结构:按业务领域拆分,共享库集中收敛通用能力
com.knowledge.base 的顶层组织方式分为两条线:
- 共享库:
kb-common(打包为 JAR),收敛所有跨模块复用的基础设施 - 业务服务:
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 的方法只做三件事:
- 参数校验(
@Valid+ Spring Validation) - DTO → Service 入参转换
- 调用 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.javakb-document/src/main/java/com/knowledge/base/document/controller/DocumentReviewController.javakb-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.javakb-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.javakb-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.javakb-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.javakb-ai/src/main/java/com/knowledge/base/ai/rag/service/impl/RagChatServiceImpl.javakb-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.javakb-user-auth/src/main/java/com/knowledge/base/userauth/config/SecurityConfig.javakb-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.javakb-foundation/src/main/java/com/knowledge/base/foundation/mq/ReviewNotificationListener.javakb-foundation/src/main/java/com/knowledge/base/foundation/websocket/WebSocketConfig.java
五、Mapper + Entity:数据模型与访问边界清晰
项目使用 MyBatis-Plus 作为 ORM 框架:
entity/负责映射数据库表,所有实体继承BaseEntitymapper/负责数据访问,继承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.javakb-common/src/main/java/com/knowledge/base/common/handler/MyMetaObjectHandler.javakb-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.javakb-ai/src/main/java/com/knowledge/base/ai/config/ModelProvider.javakb-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/ # 自定义 Hooks7.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.tssrc/services/request.tssrc/utils/permission.ts
八、阅读路径建议(按"最短理解路径"组织)
如果你要在最短时间内理解"它是怎么跑起来并完成一次文档创建与审核的",建议按下面顺序阅读(每一步都能在源码中定位到真实逻辑):
- 入口与启动:
kb-gateway/GatewayApplication→AuthGlobalFilter(网关如何解析 JWT) - 文档创建主链路:
DocumentController.createDocument()→DocumentServiceImpl.createDocument()(MySQL+MongoDB 双写 + 异步 AI 索引) - 审核工作流:
DocumentReviewController.submitForReview()→DocumentReviewServiceImpl.approveReview() - AI 对话:
AiChatController.chat()→AiChatServiceImpl.chat()(RAG 可选 → 模型调用 → 结果持久化) - RAG 检索管道:
RagRetrievalServiceImpl.retrieve()(Embedding → 混合检索 → RRF → 重排序) - 多模型工厂:
ModelProvider.init()→getModel()→buildModel()(Qwen/DeepSeek 统一接入) - 事件通知闭环:
ReviewNotificationListener(RabbitMQ 消费 → WebSocket 推送) - 共享库基础设施:
BaseEntity→Result/PageResult→MybatisPlusConfig→UserContextUtil - 前端互动:
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 + 后端同步验证),兼顾响应速度与数据正确性