项目背景

本项目是企业知识库系统,前端共用一套 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 解析
Scopecompile/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 版也有等价物(MethodArgumentNotValidException handler),但 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),没有单独的前置网关层。

关键差异:

维度JavaPython
上下文载体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()
            # ... 构建 VO

Python 的 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 StreamPython 表达式 (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 = true

Python 项目配置了 mypy --strict,这是一种"渐进类型"策略:用 Pydantic 做运行时校验,用 mypy 做编译期类型检查,补上了动态语言在大型项目中的类型安全短板。


十四、关键数字对比

指标Java 版Python 版
入口类 / 文件10 个 *Application.java1 个 main.py
Maven 模块 / Python apps10 个模块9 个 app 包 + 1 个 common 包
配置文件每个模块 1 个 application.yml1 个 config.py + .env
数据库9 个独立 MySQL 库同样 9 个库(共享 MySQL 实例)
构建文件11 个 pom.xml1 个 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
WebSocketSpring 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 适合小项目"。

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