How g-pegasus/zhiguang_be works
这是一个以 Spring Boot 为核心的后端“模块化单体”仓库,面向知识社区“知光平台”。整体不是按微服务独立仓库拆分,而是按业务域在同一应用中分包组织,并通过 MySQL、Redis、Kafka、Elasticsearch、OSS、Canal 等基础设施实现异步化、缓存化和搜索/AI 能力。
1. 总体架构形态
入口应用是 com.tongji.ZhiGuangApplication,所有业务模块都挂在同一个 Java 进程里运行。代码结构体现出清晰的分层:
• api:HTTP 接口层,负责接收请求和返回 DTO
• service / service.impl:业务编排层
• mapper:MyBatis 持久化访问层
• model / domain / entity:领域对象与数据行映射
• config:模块级或全局配置
• event / outbox / listener / processor:异步事件与最终一致性相关组件
• token / verification / audit:认证、验证码、审计子域
仓库里同时存在:
• db/schema.sql:数据库结构定义
• src/main/resources/mapper/*.xml:MyBatis SQL 映射
• src/main/resources/keys/*.pem:JWT 非对称签名密钥
• docs/:多个子系统的设计和接口文档
这说明后端是“以业务域为中心、以基础设施能力支撑”的架构,而不是简单 CRUD 项目。
2. 主要业务子系统
2.1 认证与安全子系统 auth
核心文件:
• auth/api/AuthController
• auth/service/AuthService
• auth/token/JwtService
• auth/token/RedisRefreshTokenStore
• auth/verification/VerificationService
• auth/audit/LoginLogService
• auth/config/SecurityConfig
职责:
• 登录、注册、登出、刷新令牌、密码重置
• 验证码发送与校验
• 登录审计记录
• JWT 双令牌体系:访问令牌 + 刷新令牌
• 使用 RS256 与 private.pem / public.pem 做非对称签名
• 刷新令牌白名单保存在 Redis,用于即时撤销
数据流大致是:
1. 客户端提交登录/注册请求到 AuthController
2. AuthService 校验身份信息、验证码等
3. 生成 JWT token pair
4. 刷新令牌写入 Redis
5. 登录行为写入 LoginLog 对应的 MyBatis 表
6. 认证由 Spring Security 统一拦截
这个子系统是全站权限边界的入口,其他模块的接口通常会依赖认证上下文。
2.2 用户资料子系统 profile 与用户基础域 user
核心文件:
• profile/api/ProfileController
• profile/service/ProfileService
• user/domain/User
• user/service/UserService
• user/mapper/UserMapper
职责:
• 用户基础资料与展示资料管理
• 用户信息的读取和局部修改
• 与认证身份和关系系统共享用户主数据
这里可以看出用户主数据与展示资料是分开的:user 更偏基础账户实体,profile 更偏业务展示与可修改字段。它们共同构成用户中心能力。
2.3 知识内容发布子系统 knowpost
核心文件:
• knowpost/api/KnowPostController
• knowpost/api/KnowPostAiController
• knowpost/api/KnowPostRagController
• knowpost/service/KnowPostService
• knowpost/service/KnowPostFeedService
• knowpost/mapper/KnowPostMapper
• knowpost/listener/FeedCacheInvalidationListener
• knowpost/id/SnowflakeIdGenerator
职责:
• 知识内容草稿、发布、编辑、置顶、可见性修改
• Feed 相关内容聚合和分页展示
• AI 辅助生成摘要/描述
• 与缓存、搜索、计数、关系系统联动
这里的一个关键特征是“发布链路”不只是写数据库:
• 内容主记录落库到 MySQL
• 发布后触发缓存失效
• 可能同步或异步推动搜索索引更新
• AI 能力通过 llm 模块参与摘要生成
• 生成内容 ID 使用雪花算法,便于分布式唯一性和时间排序
2.4 计数与互动子系统 counter
核心文件:
• counter/api/CounterController
• counter/api/ActionController
• counter/service/CounterService
• counter/service/UserCounterService
• counter/event/*
• counter/schema/*
职责:
• 笔记维度计数:点赞、收藏等
• 用户维度计数:关注、取关等
• 高并发下的幂等写入、异步聚合、重建修复
• Redis 作为主要计数存储,配合位图/分片 schema
• Kafka 驱动事件流转与异步消费
这是一个非常独立的子系统,和传统“数据库直接加减计数”不同,它更偏事件驱动与缓存友好:
• 写入通过事件生产者进入 Kafka
• 聚合消费者消费后更新 Redis 中的计数结构
• 重建消费者用于数据恢复或修正
• schema 包中定义了计数键、位图分片和键命名规则
• 该模块的设计目标是高并发、幂等和可重建
如果要画架构图,这一块应单独标出“写入事件流 → Kafka → 聚合处理 → Redis 计数存储 → 查询接口”的链路。
2.5 用户关系子系统 relation
核心文件:
• relation/api/RelationController
• relation/service/RelationService
• relation/processor/RelationEventProcessor
• relation/outbox/*
• relation/mapper/RelationMapper
• relation/event/RelationEvent
职责:
• 关注 / 取关关系管理
• 粉丝、关注列表的同步与查询
• 通过 Outbox 模式保证主数据和事件的一致性
• 通过 Canal 监听数据库变更,再转发到 Kafka
这是仓库里最典型的“事务内写主表 + Outbox 表”的最终一致性设计:
1. 关注操作在本地事务内同时写入关系表和 outbox 表
2. Canal 订阅 outbox 表 binlog
3. CanalKafkaBridge / CanalOutboxConsumer 将变更转成 Kafka 事件
4. RelationEventProcessor 消费事件,异步更新从数据源
5. 从数据源可能包括计数系统、缓存、列表视图等
README 里提到“粉丝表、计数系统、列表缓存都作为关注表的伪从”,这说明关系主表是权威来源,其他视图都是派生副本。
2.6 搜索子系统 search
核心文件:
• search/api/SearchController
• search/service/SearchService
• search/index/SearchIndexService
• search/index/SearchIndexInitializer
• search/outbox/CanalOutboxConsumerSearch
职责:
• 内容搜索
• 前缀联想
• 搜索索引初始化
• 从数据库变更事件同步到 Elasticsearch
这里的关键边界是:搜索不是直接查业务库,而是查 ES 索引。索引更新依赖 outbox/canal 事件管道,保证内容发布/修改后搜索侧最终一致。
README 提到的能力包括:
• 关键词检索
• 标签过滤
• search_after 深分页
• function_score 混合 BM25 与业务权重
• completion suggester 联想
因此这块应画成“业务库 → 变更事件 → 索引服务 → Elasticsearch → 查询 API”的独立搜索链路。
2.7 存储子系统 storage
核心文件:
• storage/OssStorageService
• storage/api/StorageController
• storage/config/OssProperties
职责:
• OSS 对象存储直传的预签名能力
• 文件/图片/视频等资源上传前的签名授权
• 减少后端中转流量
数据流:
1. 客户端向 StorageController 请求预签名
2. 后端生成 OSS 直传所需签名参数
3. 客户端直接上传到阿里云 OSS
4. 内容发布时只保存资源地址/元数据
这意味着媒体流量不经过应用服务器,是发布系统的重要边界。
2.8 AI / RAG 子系统 llm
核心文件:
• llm/LlmConfig
• llm/service/KnowPostDescriptionService
• llm/service/impl/KnowPostDescriptionServiceImpl
• llm/rag/RagIndexService
• llm/rag/RagQueryService
职责:
• 文章描述/摘要生成
• 基于知识库的问答
• RAG 索引构建和检索
README 说明了典型流程:
• 用户发起问答
• 检查索引
• 向量/语义检索
• Prompt 构造
• 大模型流式生成
这表明 llm 模块不是泛化的大模型网关,而是围绕“单篇知文/知识内容”的场景做的专用增强能力。它和 knowpost 绑定最紧密。
3. 基础设施与跨切关注点
3.1 全局配置与平台支撑
核心文件:
• config/RedissonConfig
• config/ThreadPoolConfig
• config/ElasticsearchConfig
• config/EsProperties
这些配置类说明系统对 Redis、ES、线程池做了统一管理。Redis 既用于刷新令牌、验证码、计数,也用于缓存和热点防护;ES 用于搜索;线程池用于异步任务和事件处理。
3.2 缓存体系 cache
核心文件:
• cache/config/CacheConfig
• cache/hotkey/HotKeyDetector
职责:
• 热点识别
• 缓存策略配置
README 中提到 Feed 使用三级缓存:
• 本地 Caffeine
• Redis 页面缓存
• Redis 片段缓存
再加上热点探测和随机抖动,说明缓存层是全局性能边界的一部分,不只是单个模块内部优化。
3.3 通用异常与工具
核心文件:
• common/exception/BusinessException
• common/exception/ErrorCode
• common/web/GlobalExceptionHandler
• common/util/OutboxMessageUtil
这是一层跨模块公共能力:
• 统一业务异常模型
• 统一 API 错误映射
• outbox 消息封装工具
它让各业务模块的错误处理和事件构造保持一致。
4. 关键数据流和边界
如果从架构图角度看,这个仓库最重要的几条主链路是:
A. 身份认证链路
客户端 → Auth API → Spring Security / JWT → Redis 刷新令牌 → 受保护业务接口
边界:认证是全局入口,决定其他模块是否可访问。
B. 内容发布链路
客户端 → KnowPost API → MySQL 主库 → 缓存失效 / 搜索索引更新 / AI 摘要 / 计数与关系联动
边界:内容主数据在 MySQL,其他系统是派生视图或增强能力。
C. 关注关系链路
客户端 → Relation API → 事务写关系表 + Outbox → Canal → Kafka → 关系从表/缓存/计数系统
边界:主写入在关系表,异步消费者负责副本同步。
D. 互动计数链路
客户端行为 → Counter API → Kafka 事件 → Redis 位图/分片计数 → 查询接口返回聚合结果
边界:Redis 是高并发计数工作区,不是唯一事实源,允许重建。
E. 搜索链路
内容变更 → Outbox/Canal → Search index service → Elasticsearch → Search API
边界:ES 是读模型,来源于业务库事件流。
F. AI 问答链路
用户提问 → RAG 查询服务 → 索引检索 → Prompt 构造 → LLM 输出
边界:LLM 模块只消费内容索引与知识片段,不直接成为业务事实源。
5. 外部依赖与它们的角色
这些外部系统对架构有直接影响:
• MySQL:主业务数据存储,尤其是用户、关系、内容、审计、outbox 等
• Redis:验证码、刷新令牌、计数、缓存、热点控制
• Kafka:异步事件总线,承载计数、关系、搜索等最终一致性流程
• Canal:监听 MySQL binlog,将 outbox 或变更事件送入 Kafka
• Elasticsearch:内容搜索与联想建议
• 阿里云 OSS:媒体/附件对象存储直传
• Spring Security / JWT:统一认证授权
• Spring AI / LLM:摘要和问答能力
6. 架构图上建议如何分区
如果要画成一张准确的系统架构图,建议按以下边界分区:
1. 接入层
- 各 Controller
- 统一异常处理
- Security 拦截链
2. 业务域层
- auth
- user / profile
- knowpost
- relation
- counter
- search
- storage
- llm
3. 异步与一致性层
- outbox
- canal bridge/consumer
- Kafka consumers/producers
- counter aggregation / rebuild
- feed cache invalidation
4. 基础设施层
- MySQL
- Redis / Redisson
- Kafka
- Elasticsearch
- OSS
- LLM/AI 服务
5. 横切能力
- 缓存配置
- 线程池
- 全局异常
- 通用错误码
- 日志审计
7. 总结
这个仓库的本质是一个“知识社区后端平台”的模块化单体架构,核心特征不是接口数量,而是多个子系统围绕同一份业务主数据构建出了不同的读写模型:
• MySQL 负责权威写入
• Redis 负责认证、缓存、计数和高频读
• Kafka/Canal 负责异步一致性
• Elasticsearch 负责搜索读模型
• OSS 负责静态资源
• LLM/RAG 负责内容智能化增强
从系统设计上看,最重要的架构关键词是:
“分域、事件驱动、读写分离、最终一致性、缓存多级化、搜索索引化、AI 增强化”。
Main entry points: ZhiGuangApplication.java ZhiGuang · KnowPostController.java KnowPost · AuthService.java Auth service · CounterEventProducer.java Kafka
Components 22
Application
Spring Boot entrypoint and shared web/runtime concerns
- ZhiGuang · Main application entrypoint
src/main/java/com/tongji/ZhiGuangApplication.java - Errors · Global exception mapping and business error model
src/main/java/com/tongji/common/web/GlobalExceptionHandler.java - Common util · Shared exception codes and outbox message utilities
src/main/java/com/tongji/common
Business domains
Core modular-monolith subdomains
- Auth API · Login, registration, token refresh, logout, password reset
src/main/java/com/tongji/auth/api/AuthController.java - Auth service · Authentication orchestration and security configuration
src/main/java/com/tongji/auth/service/AuthService.java - JWT store · JWT creation plus refresh-token storage in Redis
src/main/java/com/tongji/auth/token/JwtService.java - Verification · Verification code send/check flow backed by Redis
src/main/java/com/tongji/auth/verification/VerificationService.java - Profile · User profile read and patch operations
src/main/java/com/tongji/profile/api/ProfileController.java - User model · User master data and persistence layer
src/main/java/com/tongji/user/domain/User.java - KnowPost · Knowledge post draft, publish, visibility, feed, and AI-assisted content APIs
src/main/java/com/tongji/knowpost/api/KnowPostController.java - Post AI · Description generation and RAG entrypoints for posts
src/main/java/com/tongji/knowpost/api/KnowPostAiController.java - Counter · Like/favorite/follow counters and action ingestion
src/main/java/com/tongji/counter/api/CounterController.java - Relation · Follow/unfollow relations with outbox-based consistency
src/main/java/com/tongji/relation/api/RelationController.java - Search · Search and suggest APIs backed by Elasticsearch
src/main/java/com/tongji/search/api/SearchController.java - Storage · OSS presign and upload access control
src/main/java/com/tongji/storage/api/StorageController.java - LLM/RAG · Post summarization and retrieval-augmented generation services
src/main/java/com/tongji/llm/LlmConfig.java
Infrastructure
Datastores, search, messaging, object storage, and AI integration
- Redis · Shared Redis integration for tokens, cache, counters, and hot data
src/main/java/com/tongji/config/RedissonConfig.java - Kafka · Async event backbone for counter and outbox-driven flows
src/main/java/com/tongji/counter/event/CounterEventProducer.java - Elasticsearch · Content index and suggest backend
src/main/java/com/tongji/config/ElasticsearchConfig.java - OSS · Alibaba Cloud object storage for direct uploads
src/main/java/com/tongji/storage/config/OssProperties.java - MySQL · System of record for users, content, relations, logs, and outbox
db/schema.sql - Canal · Binlog-driven bridge from outbox changes to Kafka consumers
src/main/java/com/tongji/relation/outbox/CanalKafkaBridge.java
Connections 35
- ZhiGuang → Errors: handles errors · Application-wide request failure handling
- ZhiGuang → Auth API: exposes · Bootstraps the authentication endpoints
- ZhiGuang → Profile: exposes · Bootstraps the profile endpoints
- ZhiGuang → KnowPost: exposes · Bootstraps the content endpoints
- ZhiGuang → Counter: exposes · Bootstraps the interaction endpoints
- ZhiGuang → Relation: exposes · Bootstraps the relation endpoints
- ZhiGuang → Search: exposes · Bootstraps the search endpoints
- ZhiGuang → Storage: exposes · Bootstraps the storage endpoints
- ZhiGuang → LLM/RAG: loads · Initializes AI/RAG services
- Auth API → Auth service: calls · Controller delegates to authentication service
- Auth service → JWT store: issues tokens · Creates JWTs and persists refresh tokens
- Auth service → Verification: checks codes · Validates verification code flows
- Auth service → User model: reads users · Authenticates against user master data
- Profile → User model: updates profile · Reads and patches user data
- KnowPost → User model: uses author · Resolves post ownership and author data
- KnowPost → LLM/RAG: requests summary · Uses AI for description generation and RAG
- KnowPost → Redis: invalidates cache · Feed and content cache coordination
- Counter → Kafka: publishes events · Action events enter the async counter pipeline
- Relation → MySQL: writes main data · Transactional relation state and outbox records
- Relation → Canal: streams outbox · Binlog change capture for eventual consistency
- Canal → Kafka: forwards events · Outbox changes become Kafka messages
- Kafka → Counter: consumed by · Aggregation and rebuild consumers update derived counters
- Kafka → Relation: consumed by · Relation event processor updates derived views
- Search → Elasticsearch: queries index · Search and suggest read from Elasticsearch
- Search → Canal: consumes changes · Search index is synced from outbox-driven events
- KnowPost → MySQL: stores content · Knowledge posts are written to the system of record
- KnowPost → Canal: emits changes · Content changes flow into async sync pipelines
- Storage → OSS: presigns upload · Generates direct-upload authorization for OSS
- JWT store → Redis: stores refresh · Refresh-token whitelist and revocation state
- Verification → Redis: stores codes · Verification codes and expiry state
- Auth service → MySQL: audits login · Login logs and related auth records
- Common util → MySQL: shared persistence · Common outbox and error-related data helpers support database-backed flows
- Common util → Kafka: formats messages · Shared outbox message utilities support event publication
- Search → MySQL: rebuilds from source · Index initialization and backfill use business data as source
- LLM/RAG → Elasticsearch: retrieves context · RAG query service can use indexed knowledge as retrieval source