项目背景
本项目是企业知识库系统,前端共用一套 React + TypeScript 代码(knowledge-base-frontend),后端实现了结构完全对应的 **Java Spring Boot** 版本和 **Python FastAPI** 版本,提供完全相同的 API 接口。
通过分析两个仓库的实际代码,以下是真实存在的差异 —— 不是什么、什么特性比较,而是这个项目中你打开 Java 代码和 Python 代码时看到的东西。
一、架构拓扑:微服务 vs 单体
Java:Maven 多模块微服务
knowledge-base-backend/ (pom.xml, packaging=pom)
├── kb-common/ → 公共库(不独立部署)
├── kb-gateway/ → API 网关(Spring Cloud Gateway, 端口 8080)
├── kb-user-auth/ → 用户认证服务(端口 8081)
├── kb-document/ → 文档管理服务(端口 8082)
├── kb-search/ → 搜索服务
├── kb-file/ → 文件服务
├── kb-ai/ → AI 服务
├── kb-graph/ → 知识图谱服务
├── kb-statistics/ → 统计服务
└── kb-foundation/ → 基础服务每个模块有独立的 pom.xml、独立的 Application.java 入口、独立的 application.yml、独立的数据库(kb_user / kb_document / kb_search 等 9 个库)。服务之间通过 **Nacos** 做服务发现、**OpenFeign** 做远程调用。
Python:单体 FastAPI 应用
knowledge-base-python/
├── main.py → 唯一入口,uvicorn 启动
├── config.py → 全局配置(pydantic-settings)
├── apps/
│ ├── gateway/ → 网关中间件(替代 Spring Cloud Gateway)
│ ├── user_auth/ → 认证模块(router + service)
│ ├── document/ → 文档模块
│ ├── search/ → 搜索模块
│ ├── file/ → 文件模块
│ ├── ai/ → AI 模块(含 RAG / KAG 子模块)
│ ├── graph/ → 知识图谱模块
│ ├── statistics/ → 统计模块
│ └── foundation/ → 基础服务(WebSocket / MQ)
├── common/ → 公共库(database, security, deps...)
└── alembic/ → 数据库迁移所有模块共享同一个 Python 进程。模块之间通过直接 import 调用,没有 RPC/Feign,没有服务发现。但 9 个数据库的连接仍然独立管理(每个模块有独立的 SQLAlchemy engine)。
关键差异:Java 版每个服务可以独立扩缩容、独立滚动更新、独立故障隔离;Python 版一个进程崩了全部模块都挂。
但在开发和中小规模部署时,Python 要维护的东西少得多。
二、构建与依赖管理的本质差异
Java 版(Maven)
<!-- root pom.xml -- BOM 模式管理所有依赖版本 -->
<properties>
<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>
</properties>
<dependencyManagement>
<!-- Spring Cloud BOM -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>${spring-cloud.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- Spring Cloud Alibaba BOM -->
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-alibaba-dependencies</artifactId>
<version>${spring-cloud-alibaba.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- 内部模块 -->
<dependency>
<groupId>com.knowledge.base</groupId>
<artifactId>kb-common</artifactId>
<version>${project.version}</version>
</dependency>
</dependencyManagement>Maven 的 <dependencyManagement> 是中心化的版本仲裁机制:父 POM 声明所有版本,子模块只需写 groupId:artifactId,版本自动继承。
多模块项目编译时可以一次性 mvn install -pl kb-common,kb-document -am,Maven 自动处理模块间拓扑顺序。
Python 版(pyproject.toml + uv)
[project]
name = "knowledge-base"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
"fastapi>=0.115.0",
"sqlalchemy[asyncio]>=2.0.36",
"pydantic>=2.0",
"pydantic-settings>=2.0",
"langchain>=0.3.0",
"langchain-text-splitters>=0.3.0",
"langchain-openai>=0.3.0",
"aio-pika>=9.4.0",
"motor>=3.6.0",
"python-jose>=3.3.0",
"bcrypt>=4.0.0",
...
]
[tool.uv]
dev-dependencies = [
"pytest>=8.0",
"ruff>=0.8.0",
"mypy>=1.13.0",
]Python 依赖管理扁平化 —— 没有层级关系,所有依赖平铺在一个列表中。
版本锁定靠 uv.lock 文件实现确定性构建。
关键差异:
| 维度 | Java (Maven) | Python (uv/poetry) |
|---|---|---|
| 版本仲裁 | 父 POM BOM 统一管理 | 无层级,靠 lock 文件 |
| 多模块 | Maven modules,树形拓扑编译 | 无内置 monorepo 支持 |
| 传递冲突 | 自动最近版本策略 | poetry/uv 提供 Solver 解析 |
| Scope | compile/provided/runtime/test | 仅 dependencies/optional/dev |
| 打包产物 | JAR(字节码,不可读) | wheel(源码 + metadata,可直接阅读) |
三、配置管理的两种哲学
Java 版
// kb-common/src/main/java/.../config/JwtConfig.java
@Data
@Component
@ConfigurationProperties(prefix = "jwt")
public class JwtConfig {
private String secret = "knowledge-base...";
private Long expiration = 7200L;
private Long refreshExpiration = 604800L;
private String issuer = "knowledge-base";
public SecretKey secretKey() {
return Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));
}
}# application.yml
jwt:
secret: ${JWT_SECRET:knowledge-base-secret-key...}
expiration: 7200
spring:
redis:
host: ${REDIS_HOST:localhost}
port: ${REDIS_PORT:6379}Java 的配置链路是 yaml → @ConfigurationProperties → Java Bean。编译期类型安全,IDE 有完整的自动补全和跳转。环境变量通过 ${ENV_VAR:default} SpEL 语法注入。
Python 版
# config.py
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
# JWT
jwt_secret: str = "knowledge-base-secret-key..."
jwt_expiration: int = 7200
jwt_refresh_expiration: int = 604800
jwt_issuer: str = "knowledge-base"
# MySQL — 9 数据库
mysql_host: str = "127.0.0.1"
mysql_port: int = 3306
mysql_db_user: str = "kb_user" # 对映 Java 的 datasource
mysql_db_document: str = "kb_document"
# 属性方法:构建连接 URL
@property
def mysql_url_template(self) -> str:
return f"mysql+asyncmy://{self.mysql_user}:{self.mysql_password}@..."
# 启动校验
def validate_on_startup(self) -> None:
if self.app_env == "production":
if "knowledge-base-secret-key" in self.jwt_secret:
errors.append("JWT_SECRET 在生产环境不能使用默认值")
if errors:
raise RuntimeError("配置校验失败")
settings = Settings() # 模块级单例Python 的 pydantic-settings 路径是 .env / 环境变量 → Pydantic Model → 模块级单例。也是类型安全的(Pydantic v2 类型推断),但类型检查在导入时完成而非编译期。Python 的 @property 允许动态构建 URL 字符串,避免了 yaml 中的字符串拼接 or 占位符替换。
关键差异:
- Java 的配置绑定通过 Spring 容器完成,启动时自动注入;Python 通过模块级单例直接
from config import settings - Java 的 yaml 可以分层嵌套(
spring.redis.host);Python 用下划线扁平键名(redis_host) - Python 有
validate_on_startup()做启动时配置校验(主动防御);Java 靠@Validated和 actuator health check - Python 用
SecretStr自动在日志中脱敏;Java 没有内置等价物
四、统一响应与异常处理
Java 版
// Result.java — 泛型响应体
@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
public class Result<T> implements Serializable {
private Integer code;
private String message;
private T data;
private Long timestamp;
private Result() { this.timestamp = System.currentTimeMillis(); }
public static <T> Result<T> success(T data) {
return new Result<>(ResultCode.SUCCESS.getCode(),
ResultCode.SUCCESS.getMessage(), data);
}
public static <T> Result<T> error(Integer code, String message) {
return new Result<>(code, message, null);
}
}// GlobalExceptionHandler.java
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(Throwable.class)
public Object handleException(Throwable e) {
// 区分内部调用(Feign,返回 ResponseEnity + HTTP 状态码)
// 和外部调用(浏览器,返回 Result + HTTP 200)
if (Objects.nonNull(requestAttributes)) {
if (StringUtils.isNotEmpty(request.getHeader("INNER-REQUEST"))) {
return handleInternalException(e, requestInfo);
}
}
return handleExternalException(e, requestInfo);
}
private Object handleExternalException(Throwable e, String requestInfo) {
if (e instanceof BusinessException) { ... }
else if (e instanceof AccessDeniedException) { ... }
else if (e instanceof MethodArgumentNotValidException) { ... }
else if (e instanceof IllegalArgumentException) { ... }
// 兜底
return Result.error(ResultCode.ERROR);
}
}Python 版
# common/result.py — Pydantic Model 响应体
class Result(BaseModel):
code: int = ResultCode.SUCCESS
message: str = "操作成功"
data: Any = None
@classmethod
def success(cls, *, data: Any = None, message: str = "操作成功") -> "Result":
return cls(code=ResultCode.SUCCESS, message=message, data=data)
@classmethod
def error(cls, *, code: int = ResultCode.ERROR,
message: str = "操作失败", data: Any = None) -> "Result":
return cls(code=code, message=message, data=data)
def model_dump(self, **kwargs) -> dict:
"""输出 dict 供 JSONResponse 序列化"""
return super().model_dump(**kwargs)# common/exceptions.py — 三层异常处理
class BusinessException(Exception):
def __init__(self, code=ResultCode.ERROR, message="业务异常"):
self.code = code
self.message = message
class UnauthorizedException(BusinessException):
def __init__(self, message="未授权"):
super().__init__(code=ResultCode.UNAUTHORIZED, message=message)
class TokenExpiredException(BusinessException):
def __init__(self, message="Token已过期"):
super().__init__(code=ResultCode.TOKEN_EXPIRED, message=message)
# 全局处理器
async def business_exception_handler(request, exc):
# UnauthorizedException → HTTP 401
# ForbiddenException → HTTP 403
# 其他 → HTTP 200
if isinstance(exc, UnauthorizedException):
http_status = 401
elif isinstance(exc, ForbiddenException):
http_status = 403
else:
http_status = 200
return JSONResponse(
status_code=http_status,
content=Result.error(code=exc.code, message=exc.message).model_dump(),
)
async def validation_exception_handler(request, exc):
# Pydantic RequestValidationError → 友好的中文错误
errors = exc.errors()
messages = [f"{'.'.join(str(l) for l in e['loc'])}: {e['msg']}" for e in errors]
return JSONResponse(
status_code=200,
content=Result.error(code=400, message="; ".join(messages)).model_dump(),
)
async def global_exception_handler(request, exc):
"""兜底 —— 所有未被捕获的异常统一返回 '系统内部错误'"""
return JSONResponse(
status_code=200,
content=Result.error(code=500, message="系统内部错误").model_dump(),
)关键差异:
- Java 的
@RestControllerAdvice是声明式 AOP(注解驱动);Python 用app.add_exception_handler()显式注册 - Java 区分了 内部 Feign 调用(保留 HTTP 状态码)和 外部 API 调用(统一回 HTTP 200)两套处理策略;Python 因为单体架构不存在这个概念
- Python 的
validation_exception_handler把 Pydantic 校验错误转成了中文提示 —— Java 版也有等价物(MethodArgumentNotValidExceptionhandler),但 Python 借助 Pydantic 的类型信息能给出更精确的错误定位 - Java 的 Result 携带
timestamp字段,Python 的没有(Pydantic 序列化会自动加 JSON 默认值) - 两者异常层次结构几乎完全对应:
BusinessException→UnauthorizedException/ForbiddenException/TokenExpiredException
五、认证与用户上下文:ThreadLocal vs Depends 注入
Java 版
// ① 网关层解析 Token → X-User-Id 请求头
// kb-gateway/filter/AuthGlobalFilter.java
@Component
public class AuthGlobalFilter implements GlobalFilter, Ordered {
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
String token = extractToken(request);
Long userId = jwtTokenUtil.getUserIdFromToken(token);
ServerHttpRequest modified = request.mutate()
.header("X-User-Id", String.valueOf(userId))
.build();
return chain.filter(exchange.mutate().request(modified).build());
}
}
// ② 后端服务使用 ThreadLocal 存取
// kb-common/utils/UserContextUtil.java
public class UserContextUtil {
private static final ThreadLocal<Long> USER_ID_HOLDER = new ThreadLocal<>();
private static final ThreadLocal<String> USERNAME_HOLDER = new ThreadLocal<>();
public static void setUserId(Long userId) { USER_ID_HOLDER.set(userId); }
public static Long getUserId() { return USER_ID_HOLDER.get(); }
public static void clear() {
USER_ID_HOLDER.remove();
USERNAME_HOLDER.remove();
}
}
// ③ 在 Controller 中直接调用静态方法
@GetMapping("/me/stats")
public Result<UserStatisticsVO> getMyStatistics() {
Long userId = UserContextUtil.getUserId();
// ...
}Java 的用户上下文靠 ThreadLocal —— 每个请求线程绑定一份用户数据。网关(kb-gateway)在请求到达后端服务前先解析出 userId 写入 X-User-Id 请求头,下游服务从请求头或 ThreadLocal 读取。
Python 版
# ① 定义 dataclass 用户上下文
@dataclass
class UserContext:
user_id: int
username: Optional[str] = None
avatar: Optional[str] = None
permissions: List[str] = field(default_factory=list)
@property
def is_authenticated(self) -> bool:
return self.user_id > 0
# ② FastAPI Depends 依赖注入
async def get_current_user(
authorization: Optional[HTTPAuthorizationCredentials] = Depends(bearer_scheme),
token: Optional[str] = Query(None),
x_user_id: Optional[str] = Header(None, alias="X-User-Id"),
request: Request = None,
) -> UserContext:
# 优先级: X-User-Id > Bearer Token > Query Token > Cookie
if x_user_id:
return UserContext(user_id=int(x_user_id), username=x_username)
claims = JWTHandler.decode_token(token_str)
if claims is None:
raise UnauthorizedException("请先登录")
return UserContext(
user_id=int(claims.get("userId")),
username=claims.get("username"),
avatar=claims.get("avatar"),
)
# ③ 在路由函数签名中声明依赖
@router.get("/documents/{id}")
async def get_document(
id: int,
user: UserContext = Depends(get_current_user),
) -> Result:
logger.info(f"文档详情请求: doc_id={id}, user_id={user.user_id}")Python 的认证链路更纯粹:通过 FastAPI 的 依赖注入系统将用户上下文作为参数注入。X-User-Id 请求头的优先级同样是最高的(对接 Java 网关或 Nginx),但 Python 版本自身也内置了完整的 JWT 解析逻辑(JWTHandler),没有单独的前置网关层。
关键差异:
| 维度 | Java | Python |
|---|---|---|
| 上下文载体 | ThreadLocal 静态方法 | Depends 依赖注入 |
| 认证位置 | 网关独立服务 + 各模块 Filter | 中间件统一处理 |
| 可测试性 | 需要 mock ThreadLocal 或 Spring Context | 直接传 UserContext dataclass |
| 线程安全 | 天然线程安全(每个线程一份) | async 下依赖注入也安全 |
| 代码侵入性 | Controller 中静默调用静态方法 | 显式声明在函数签名 |
六、数据库访问:MyBatis-Plus vs SQLAlchemy Async
Java 版
// entity
@Data
public class User extends BaseEntity {
private String username;
private String password;
private String email;
private String realName;
}
// mapper (MyBatis-Plus, 无需写 SQL)
public interface UserMapper extends BaseMapper<User> {
@Select("SELECT * FROM kb_user WHERE username = #{username} AND deleted = 0")
User selectByUsername(@Param("username") String username);
}
// service 接口
public interface UserService extends IService<User> {
LoginVO login(String username, String password);
Long createUser(UserDTO userDTO);
IPage<UserVO> pageUsers(Long current, Long size, ...);
}
// service 实现
@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User>
implements UserService {
@Resource
private UserMapper userMapper;
@Override
public User getByUsername(String username) {
return userMapper.selectByUsername(username);
}
@Override
public IPage<UserVO> pageUsers(...) {
LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
if (StringUtils.hasText(keyword)) {
wrapper.like(User::getUsername, keyword)
.or().like(User::getRealName, keyword);
}
Page<User> page = new Page<>(current, size);
return userMapper.selectPage(page, wrapper)
.convert(user -> buildUserVO(user, false));
}
}Java 的 MyBatis-Plus 特征是 接口 + Lambda 表达式构建查询条件。LambdaQueryWrapper 通过 User::getUsername 这种字节码引用推断字段名,避免了字符串硬编码。CRUD 由 BaseMapper 自动提供,复杂查询在 mapper 接口的 @Select 注解中写 SQL。
Python 版
# model
class User(Base):
__tablename__ = "kb_user"
id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=False)
username: Mapped[str] = mapped_column(String(64), unique=True, nullable=False)
password_hash: Mapped[str] = mapped_column("password", String(255))
email: Mapped[Optional[str]] = mapped_column(String(128))
real_name: Mapped[Optional[str]] = mapped_column(String(64))
# user_service.py
class UserService:
@staticmethod
async def get_user_by_id(user_id: int):
async with db_manager.get_session("user") as session:
stmt = select(User).where(
User.id == user_id,
User.deleted == 0
)
result = await session.execute(stmt)
return result.scalar_one_or_none()
@staticmethod
async def page_users(dto: UserPageQueryDTO):
async with db_manager.get_session("user") as session:
conditions = [User.deleted == 0]
if dto.keyword:
pattern = f"%{dto.keyword}%"
conditions.append(
or_(User.username.like(pattern),
User.real_name.like(pattern))
)
stmt = (select(User).where(and_(*conditions))
.order_by(User.created_at.desc())
.offset((dto.current - 1) * dto.size).limit(dto.size))
result = await session.execute(stmt)
users = result.scalars().all()
# ... 构建 VOPython 的 SQLAlchemy 2.0 特征是 类型标注的 ORM + 链式构建查询。查询是 Python 表达式而非字符串 SQL(虽然也可以写 raw SQL),User.deleted == 0 和 User.username.like(pattern) 都是 Python 对象。
关键差异:
| 维度 | Java (MyBatis-Plus) | Python (SQLAlchemy 2.0) |
|---|---|---|
| ORM 模型 | POJO + @TableName 注解 | DeclarativeBase + Mapped 类型注解 |
| 查询风格 | Lambda 引用 (User::getUsername) + Java Stream | Python 表达式 (User.username == "foo") |
| SQL 混编 | Mapper 接口 @Select 注解混编 | text("SELECT ...") 或纯 ORM |
| 分页 | IPage<T> 内置分页对象 | offset() / .limit() 手动计算 |
| Session 管理 | Spring @Transactional 声明式事务 | async with db_manager.get_session() 上下文管理器 |
| 连接池 | Druid(Alibaba 定制,带监控) | SQLAlchemy 内置 QueuePool |
| 乐观锁 | @Version 注解,拦截器自动处理 | 手动 version 字段比较 |
七、API 路由定义方式
Java 版
// kb-document/controller/DocumentController.java
@Slf4j
@RestController
@RequestMapping("/documents")
@Tag(name = "文档管理", description = "文档信息管理接口")
public class DocumentController {
@Resource
private DocumentService documentService;
@GetMapping("/page")
@Operation(summary = "分页查询文档")
public Result<IPage<DocumentVO>> pageDocuments(
@RequestParam(defaultValue = "1") Long current,
@RequestParam(defaultValue = "10") Long size,
@RequestParam(required = false) String keyword,
@RequestParam(required = false) Long categoryId,
) {
return Result.success(documentService.pageDocuments(current, size, ...));
}
@PostMapping
@Operation(summary = "创建文档")
public Result<Long> createDocument(
@Valid @RequestBody DocumentDTO dto
) {
return Result.success("创建成功",
documentService.createDocument(dto));
}
}路由通过注解定义:@RestController + @RequestMapping + @GetMapping/@PostMapping。参数通过 @RequestParam / @PathVariable / @RequestBody 绑定。@Valid 触发 Jakarta Bean Validation。@Operation 注解生成 Knife4j 文档。
Python 版
# apps/document/routers/document_router.py
router = APIRouter()
@router.get("/documents/page")
async def page_documents_v2(
current: int = Query(default=1, description="页码"),
size: int = Query(default=10, description="每页条数"),
keyword: str = Query(default=None, max_length=200),
categoryId: Optional[int] = Query(default=None, alias="categoryId"),
sortBy: Optional[str] = Query(default=None, alias="sortBy"),
sortOrder: Optional[str] = Query(default=None, alias="sortOrder"),
) -> Result:
"""分页查询文档列表 - 对应 Java DocumentController.pageDocuments()"""
query = DocumentQueryDTO(
current=current, size=size, keyword=keyword,
category_id=categoryId, sort_field=sortBy or "updated_at",
sort_order=sortOrder or "desc",
)
result = await DocumentService.page_documents(query)
return Result.success(data=result).model_dump()
@router.put("/documents/{id}")
async def update_document(
id: int,
dto: DocumentUpdateDTO,
user: UserContext = Depends(get_current_user),
) -> Result:
"""更新文档"""
result = await DocumentService.update_document(
doc_id=id, dto=dto, user_id=user.user_id
)
return Result.success(message="文档更新成功",
data=model_to_dict(result)).model_dump()Python 的路由通过 APIRouter + 装饰器定义。参数类型通过 Query() / Path() / Body() 的 Pydantic Field 系统声明,接受 alias 做 camelCase ↔ snake\_case 映射。Pydantic model(DocumentUpdateDTO)自动校验请求体。用户注入靠 Depends(get_current_user)。
关键差异:
- Java 注解驱动的路由在编译期就确定了 API 契约;Python 路由是运行时注册(
app.include_router(router, prefix=...)) - Python 的路由函数签名更"自文档化" ——
Query(default=1, description="页码")直接出现在函数参数中 - Python 需要在多个前缀下重复 include\_router(如
/api/auth和/api/auth/users都挂同一个 router),因为 Java 网关做了StripPrefix路由重写 —— Python 单体架构需要兼容易前端所有调用方式
八、JWT 令牌管理
Java 版
// kb-common/utils/JwtTokenUtil.java (省略完整代码)
@Component
public class JwtTokenUtil {
@Resource
private JwtConfig jwtConfig;
public String generateAccessToken(Long userId, String username,
String avatar, long expiration) {
return Jwts.builder()
.claim("userId", userId)
.claim("username", username)
.claim("avatar", avatar)
.subject(String.valueOf(userId))
.issuer(jwtConfig.getIssuer())
.issuedAt(new Date())
.expiration(new Date(System.currentTimeMillis() + expiration * 1000))
.signWith(jwtConfig.secretKey())
.compact();
}
public Long getUserIdFromToken(String token) {
Claims claims = parseToken(token);
return claims != null ? Long.parseLong(claims.getSubject()) : null;
}
}Java 使用 jjwt (io.jsonwebtoken) 库,通过 builder 模式构建 JWT。密钥通过 @ConfigurationProperties 配置,运行时才注入。
Python 版
# common/security.py
class JWTHandler:
SECRET = settings.jwt_secret # 模块级常量(类变量)
ALGORITHM = "HS256"
ACCESS_EXPIRATION = settings.jwt_expiration
@classmethod
def create_access_token(cls, user_id, username=None, avatar=None):
return cls._generate_token(
user_id=user_id, username=username, avatar=avatar,
token_type="access",
expires_delta=cls.ACCESS_EXPIRATION,
)
@classmethod
def _generate_token(cls, user_id, token_type, expires_delta, **kwargs):
now = datetime.now(timezone.utc)
claims = {
"userId": user_id,
"type": token_type,
"sub": str(user_id),
"iss": cls.ISSUER,
"iat": now,
"exp": now + timedelta(seconds=expires_delta),
}
if username := kwargs.get("username"):
claims["username"] = username
return jwt.encode(claims, cls.SECRET, algorithm=cls.ALGORITHM)
@classmethod
def decode_token(cls, token):
try:
return jwt.decode(token, cls.SECRET, algorithms=[cls.ALGORITHM])
except JWTError:
return None
@classmethod
def refresh_token(cls, refresh_token):
claims = cls.decode_token(refresh_token)
if claims is None or claims.get("type") != "refresh":
return None
return cls.create_access_token(int(claims["userId"]),
claims.get("username"),
claims.get("avatar"))Python 使用 python-jose 库,所有方法都是 @classmethod(无实例化)。还额外提供了一个 is_token_expiring_soon(threshold_seconds=1800) 方法,供前端主动续期判断。
两者在 payload 结构、签名算法(HS256)、type 字段区分 access/refresh 的策略上完全一致,确保了 Java 生成的 Token 可以被 Python 验证,反之亦然。
九、ID 生成策略
Java 版
// kb-common/utils/SnowflakeIdGenerator.java
@Component
public class SnowflakeIdGenerator {
// Twitter Snowflake 完整实现:41位时间戳 + 10位机器ID + 12位序列号
// 时钟回拨保护:偏差≤5ms 时自旋等待,>5ms 时抛异常
// 单例:双重检查锁
private static volatile SnowflakeIdGenerator instance;
public synchronized long nextId() {
long timestamp = getCurrentTimestamp();
// 时钟回拨检测与自旋补偿
if (timestamp < lastTimestamp) {
long offset = lastTimestamp - timestamp;
if (offset <= 5) {
Thread.sleep(offset << 1);
// 补偿后仍然回拨则抛异常
} else {
throw new RuntimeException("Clock moved backwards...");
}
}
// ... 位运算生成 ID
}
}Python 版
# common/id_generator.py(省略完整代码)
class SnowflakeIdGenerator:
# 同样实现 Twitter Snowflake 算法
# 与 Java 共享相同的时间起点 (START_TIMESTAMP)、机器位宽、序列位宽
# 确保两个后端生成的 ID 格式完全兼容两边的雪花算法实现使用相同的时间起点和位分配,保证 Java 和 Python 生成的主键可以互操作(例如 Python 后端创建的文档记录 ID 能被 Java 后端正确读取)。
十、依赖注入模式
Java:@Resource 字段注入
@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User>
implements UserService {
@Resource
private UserMapper userMapper;
@Resource
private JwtTokenUtil jwtTokenUtil;
@Resource
private SecurityConfigService securityConfigService;
@Resource
private StringRedisTemplate stringRedisTemplate;
}Spring 的 @Resource(byName)或 @Autowired(byType)注入到字段。Service 被 Spring 容器管理,默认单例。
Python:函数参数注入 + 模块级单例
# 依赖注入方式 1: FastAPI Depends
@router.get("/documents/{id}")
async def get_document(
id: int,
user: UserContext = Depends(get_current_user) # ← 注入
) -> Result: ...
# 依赖注入方式 2: 模块级 import 单例
from common.database import db_manager # 全局 DatabaseManager
from common.redis import RedisManager # 类级单例
from common.mongo import MongoManager # 类级单例
from common.rabbitmq import rabbitmq_manager # 实例级单例
from config import settings # pydantic-settings 单例Python 中没有统一的 IoC 容器。基础设施组件(DB、Redis、MongoDB)通过 模块级单例 模式管理;请求级上下文(User)通过 Depends 注入。@staticmethod / @classmethod 广泛用于 Service 方法,Service 本身通常是一个纯静态函数的集合类而非实例对象。
十一、中间件与请求处理管道
Java:Spring Cloud Gateway 过滤器链
请求到达网关(kb-gateway:8080)
→ SecurityWebFilterChain (CSRF/CORS 放行)
→ -200: AuthGlobalFilter (解析 JWT → X-User-Id 请求头)
→ -100: GlobalLogFilter (记录请求日志)
→ -2: UnifiedResponseFilter (统一包装响应 JSON)
→ 路由转发到具体微服务 (kb-user-auth / kb-document ...)
→ CorsFilter
→ JwtAuthenticationFilter
→ Controller
→ GlobalExceptionHandler (AOP 拦截)Java 的请求处理链是分层的:网关层做认证和日志,具体服务层再做 CORS 和安全检查。多个全局过滤器通过 @Order 控制执行顺序。
Python:FastAPI 中间件
# apps/gateway/middleware.py
class AuthMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request, call_next):
# ① 白名单路径直接放行
if is_whitelisted(request.url.path):
return await call_next(request)
# ② 解析 Token → 注入 X-User-Id
token = extract_token(request)
if token:
user_id = JWTHandler.get_user_id_from_token(token)
request.headers.__dict__["_list"].append(
("x-user-id".encode(), str(user_id).encode())
)
# ③ 调用下一层
response = await call_next(request)
return response
class LoggingMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request, call_next):
start = time.time()
response = await call_next(request)
elapsed = time.time() - start
logger.info(f"[{request.method}] {request.url.path} → "
f"{response.status_code} ({elapsed:.3f}s)")
return response
# main.py 中注册
def setup_gateway(app):
app.add_middleware(CORSMiddleware, ...)
app.add_middleware(GatewayResponseMiddleware) # 统一响应格式
app.add_middleware(LoggingMiddleware) # 日志
app.add_middleware(AuthMiddleware) # 认证(最后添加 = 最先执行)Python 版本的中间件全部在一个进程中执行。GatewayResponseMiddleware 承担了类似 Java UnifiedResponseFilter 的功能(将非标准格式响应包装为 {code, message, data});AuthMiddleware 承担了 AuthGlobalFilter 的角色。没有独立的网关进程。
十二、基础设施连接管理
Java 版:Spring Boot AutoConfiguration
// Redis: Spring Boot 自动配置,仅需 yaml
spring:
data:
redis:
host: ${REDIS_HOST:localhost}
port: 6379
lettuce:
pool:
max-active: 50
// Elasticsearch: 同样自动配置
spring:
elasticsearch:
uris: ${ES_HOST:localhost}:9200
// MongoDB, Neo4j, RabbitMQ: 各模块独立的 Config 类Java 通过 Spring Boot 的 AutoConfiguration 机制减少了大量样板代码。像 Redis、Elasticsearch 这类常见组件只需配置 yaml 即可,连接池由框架管理。
Python 版:手动管理单例 + 生命周期
# common/redis.py
class RedisManager:
"""单例模式,延迟初始化"""
_redis: Optional[AsyncRedis] = None
_pool: Optional[ConnectionPool] = None
@classmethod
async def get_client(cls):
if cls._redis is None:
cls._pool = ConnectionPool.from_url(
settings.redis_url,
max_connections=50,
socket_keepalive=True,
socket_connect_timeout=3,
retry_on_timeout=True,
health_check_interval=30,
)
cls._redis = AsyncRedis(connection_pool=cls._pool,
decode_responses=True)
return cls._redis
@classmethod
async def close(cls):
if cls._redis:
await cls._redis.aclose()
if cls._pool:
await cls._pool.disconnect()
# common/mongo.py — 同样模式
class MongoManager:
_client: Optional[AsyncIOMotorClient] = None
_collections: Dict[str, AsyncIOMotorCollection] = {}
# main.py — 生命周期管理
@asynccontextmanager
async def lifespan(app):
# 启动
await rabbitmq_manager.connect()
# ...
yield
# 关闭
await rabbitmq_manager.close()
await db_manager.close_all()
await RedisManager.close()
await MongoManager.close()Python 版本的每个基础设施组件都是一个独立的类级单例,需要手动管理生命周期。main.py 的 lifespan 通过 asynccontextmanager 统一管理启动/关闭。与 Java 的自动配置不同,Python 每个连接管理器都有显式的 close() 方法调用。
十三、测试与代码质量
Java 版
- 测试框架: JUnit 5
- Mock: Mockito
- 断言:
assertEquals(expected, actual) - 测试组织:
src/test/java/下的测试类对应 src 结构 - 这个项目中未发现
src/test/下有大量测试代码
Python 版
- 测试框架: pytest(配置在
pyproject.toml [tool.pytest.ini_options]) - mock: unittest.mock
- 断言: 原生
assert - 测试组织:
tests/目录 - 代码检查: Ruff(替代 Flake8 + isort),配置在
[tool.ruff] - 类型检查: mypy(严格模式
strict = true),配置在[tool.mypy]
# pyproject.toml
[tool.ruff]
line-length = 120
select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]
[tool.mypy]
python_version = "3.12"
strict = truePython 项目配置了 mypy --strict,这是一种"渐进类型"策略:用 Pydantic 做运行时校验,用 mypy 做编译期类型检查,补上了动态语言在大型项目中的类型安全短板。
十四、关键数字对比
| 指标 | Java 版 | Python 版 |
|---|---|---|
| 入口类 / 文件 | 10 个 *Application.java | 1 个 main.py |
| Maven 模块 / Python apps | 10 个模块 | 9 个 app 包 + 1 个 common 包 |
| 配置文件 | 每个模块 1 个 application.yml | 1 个 config.py + .env |
| 数据库 | 9 个独立 MySQL 库 | 同样 9 个库(共享 MySQL 实例) |
| 构建文件 | 11 个 pom.xml | 1 个 pyproject.toml + uv.lock |
| Controller / Router | 每个模块多个 Controller 类 | 每个模块 1~N 个 *_router.py |
| Service 层 | 接口 + impl 分离(interface/impl 目录) | 无接口/实现分离,直接 *_service.py |
| 服务通信 | OpenFeign + Nacos | 直接 import |
| API 文档 | Knife4j (Swagger) | FastAPI 内置 OpenAPI + /doc.html |
| WebSocket | Spring STOMP + SockJS | 自实现 SockJS 协议兼容层 |
| 网关 | 独立 Spring Cloud Gateway 进程 | 内嵌 HTTP 中间件 |
| 任务队列 | 无(依赖 Spring @Scheduled) | Celery + Redis |
| 数据库迁移 | sql/ 目录存放 .sql 脚本 | Alembic(alembic/versions/) |
| 容器编排 | 无 docker-compose(仅基础设施外置) | docker-compose.yml(MySQL/ES/Redis 等 7 个服务) |
十五、总结
这个项目中 Java 和 Python 版本的代码不是"谁好谁坏"的关系,而是工程化严谨度与开发效率的不同取舍:
Java 版本显示出典型的企业级 Java 工程特征:
- 接口与实现分离(17 个
DocumentService.java+ 17 个ServiceImpl.java) - 分层架构严格(controller → service interface → service impl → mapper → entity)
- 关注点分离到极致(CORS 去重过滤器、统一响应过滤器、日志过滤器各司其职)
- DDD 级别的命名(
LambdaQueryWrapper、@RestControllerAdvice、TransactionSynchronizationManager) - Alibaba 生态深度绑定(Druid、Nacos、FastJSON2、Hutool)
Python 版本显示出对 Java 原版的精确移植 + Pythonic 简化:
- 每个
*_router.py文件开头都标注了对应的 Java Controller 和端点映射 - Service 不放接口/实现分离,直接用
@staticmethod/@classmethod方法(因为 Python 不需要 IoC 容器管理依赖) - 中间件用原生
BaseHTTPMiddleware实现,不需要引入 Spring Cloud Gateway 级别的复杂度 - Pydantic v2 + mypy strict 补上了动态语言的类型缺口
- 用
APIRouter的多 prefix 注册来兼容 Java 网关的 StripPrefix 行为 - 完整的
docker-compose.yml提供了即开即用的开发环境
底层共通之处:
- 9 个数据库的拆分策略完全一致(每个业务领域独立 database)
- JWT payload 结构(
userId,type,sub,iss)完全一致,可互操作 - 统一的
{code, message, data}响应格式 - 相同的异常层次(BusinessException → Unauthorized/Forbidden)
- 相同的 BCrypt 密码哈希(Java 的
BCrypt.hashpw和 Python 的bcrypt.hashpw完全兼容) - 相同的雪花算法实现(时间起点和位分配一致)
这两个版本的存在本身就是一种决策实践:用 Java 构建服务网格保障高可用和独立伸缩能力,再用 Python 快速移植验证 API 一致性和提供轻量级部署选项。
在实际选型中,真正重要的是理解这些具体代码差异背后的取舍,而不是笼统地说"Java 适合大项目,Python 适合小项目"。