Java 转 Python（三）：生态与部署

系列第三篇。前两篇覆盖了语法、FastAPI、数据库；本篇聚焦 AI Agent、生态选型、分层架构、部署与工程文化。

1. AI Agent 对话

PydanticAI = Spring AI 的 Python 版。@agent.tool 注册函数，AI 自动决定何时调用。

# 1. 创建 Agent
agent = Agent(
    OpenAIModel("deepseek-v4-flash", provider=...),
    instructions="你是 PayReach BD 助手...",
)

# 2. 注册 Tool（AI 可调用的函数）
@agent.tool
async def query_exhibitions(ctx, keyword="", region=""):
    """查询展会库。按关键词搜索。"""
    repo = get_exhibition_repo()
    exhibitions, total = await repo.find_paginated(keyword=keyword)
    return json.dumps({"exhibitions": [...], "total": total})

# 3. 运行对话
result = await agent.run("帮我查上海的展会", message_history=history)
print(result.output)  # AI 的自然语言回复

用户: "帮我查上海的展会"
  ↓
Agent 分析意图 → 决定调用 query_exhibitions(keyword="上海")
  ↓
Tool 查数据库 → 返回展会列表 JSON
  ↓
Agent 组织自然语言 → "上海地区共有 5 个展会..."

2. Python 生态总览

Web 框架

ORM

Pydantic 生态

FastAPI 依赖 Pydantic，但作者是不同的人。

3. 核心代码分层架构

和 Spring Boot 一样：Route → Service → Repository → Model。

┌──────────────────────────────────────────────────┐
│  Route (Controller)                               │
│  routes/login.py, routes/companies.py ...         │
│  只做参数校验 + 调 Service + 返回响应              │
├──────────────────────────────────────────────────┤
│  Service                                          │
│  services/auth.py, services/article_service.py    │
│  业务编排 + session_scope() 事务管理               │
├──────────────────────────────────────────────────┤
│  Repository (Mapper/DAO)                          │
│  repositories/user_repo.py ...                    │
│  继承 BaseRepository, _use_session 透传 session    │
├──────────────────────────────────────────────────┤
│  Model 层                                         │
│  models/user.py (DTO) ←→ db/tables/user.py (Entity) │
├──────────────────────────────────────────────────┤
│  db/engine.py                                     │
│  AsyncEngine + session_scope + init_db            │
└──────────────────────────────────────────────────┘

4. Session 透传机制

= Java 的 @Transactional 事务传播。Service 创建 session，传给多个 Repository，实现多表原子操作。

# Python — 手动传 session
async with session_scope() as session:
    await article_repo.save_analysis(data, session=session)
    await exhibition_repo.upsert(exhibition, session=session)
    # 两个写操作在同一个事务中，要么都成功，要么都回滚

// Java — 声明式传播
@Transactional
public void analyze(int articleId) {
    articleMapper.saveAnalysis(data);        // 自动在同一事务
    exhibitionMapper.upsert(exhibition);     // 自动在同一事务
}

# BaseRepository — 有外部 session 就共享，没有就独立事务
class BaseRepository:
    @asynccontextmanager
    async def _use_session(self, session=None):
        if session is not None:
            yield session            # 有外部 session → 共享事务
        else:
            async with session_scope() as s:
                yield s              # 无外部 session → 独立事务

Java @Transactional 是声明式（框架自动管理），Python 显式传 session 参数（手动但透明）。

5. 部署：Uvicorn & Gunicorn

= Java 的 Tomcat。Uvicorn 干活，Gunicorn 管进程。

# 开发环境 — 单进程 + 热重载
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

# 生产环境方式1 — Uvicorn 多进程（简单够用）
uvicorn app.main:app --host 0.0.0.0 --port 8001 --workers 4

# 生产环境方式2 — Gunicorn + Uvicorn（更成熟）
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8001

                    ┌─ Worker 1 (PID 1001) ─ 自己的 GIL ─ 处理请求
                    │
Gunicorn (Master) ──┼─ Worker 2 (PID 1002) ─ 自己的 GIL ─ 处理请求
                    │
                    ├─ Worker 3 (PID 1003) ─ 自己的 GIL ─ 处理请求
                    │
                    └─ Worker 4 (PID 1004) ─ 自己的 GIL ─ 处理请求

多进程时连接池翻倍：4 进程 × pool_size=10 = 40 个连接。Worker 数通常设为 CPU 核心数 × 2 + 1。

6. 注释文化 & 生态读音

注释差异

# ❌ 坏注释（解释做什么 — Python 社区不推荐）
user = await repo.find_by_email(email)  # 查找用户

# ✅ 好注释（解释为什么 — Python 推荐）
# bcrypt 在事务外执行，避免 DB 连接长时间占用
new_hash = hash_password(new_password)

生态读音

Python Web 服务器爱用独角兽命名（Gunicorn、Uvicorn），就像 Java 生态爱用动物（Tomcat、Kafka、Camel）。

命名规范速记

转换记忆法：驼峰大写字母 → _小写 → findByEmail → find_by_email

系列总结

三篇下来，Java 开发者应该能读懂 PayReach 这类 Python 后端项目，并独立完成 API 开发与部署。