Architecture | 杨劲松 - Java后端 / AI应用开发工程师

FastAPI 项目架构：从路由到领域服务的分层设计

Fri, 21 Aug 2026 00:00:00 +0000

上图：FastAPI — FastAPI 项目架构。

FastAPI 很容易在一个文件里快速起步，也很容易因此变成不可维护的全局脚本。更稳妥的结构是让路由处理 HTTP，让 service 处理用例，让 repository 处理数据访问。

核心心智模型

推荐的调用方向是 router → service → repository/provider，依赖通过函数参数注入。领域服务不应依赖 Request 或 HTTP 状态码，这样可以在命令行、任务队列和测试中复用。

关键机制

配置用环境变量读取并在启动时校验；连接池在 lifespan 中创建和关闭；异常统一映射为稳定的错误 schema。

Python 示例

from fastapi import APIRouter, Depends
from pydantic import BaseModel

router = APIRouter(prefix="/v1/chat", tags=["chat"])

class ChatRequest(BaseModel):
 message: str

class ChatResponse(BaseModel):
 answer: str

@router.post("", response_model=ChatResponse)
async def chat(req: ChatRequest, service = Depends(get_chat_service)):
 return ChatResponse(answer=await service.answer(req.message))

课程定位

这篇文章把白板上的模块拆成可以落地的工程边界：先定义输入和输出，再决定状态、失败策略与可观测性。示例使用 Python，重点是设计原则而不是绑定某个供应商版本；上线前请以当前依赖的官方文档为准。

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

先实现白板中的最小闭环，再故意注入一个超时、一个空结果和一个格式错误，观察系统能否给出稳定且可诊断的结果。最后补一条指标，证明你的优化确实改善了质量或延迟。

动手练习

把一个包含模型调用的路由拆成 api、services、providers 和 schemas，为 service 注入 fake provider，并用 TestClient 验证错误映射。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

LangChain 核心架构：Runnable、模型与可组合链

Fri, 21 Aug 2026 00:00:00 +0000

上图：LangChain — LangChain 核心架构。

LangChain 的价值不只是把模型包起来，而是提供一套可组合的运行时接口。把 prompt、model、parser 看成同一条 Runnable 管道后，调用、批处理、流式输出和追踪都可以采用一致的方式。

核心心智模型

典型链路是输入字典 → ChatPromptTemplate → ChatModel → StrOutputParser。每个节点有自己的契约，链只负责连接它们；这让模型替换和局部测试变得简单。

关键机制

组合操作符表达数据流，invoke 适合单次请求，batch 适合批量任务，stream 适合低首字节延迟。生产代码应在边界处做类型检查和超时控制，而不是把异常吞掉。

Python 示例

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

prompt = ChatPromptTemplate.from_messages([
 ("system", "你是简洁的技术助手。"),
 ("human", "请用三点解释：{question}"),
])
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
chain = prompt | model | StrOutputParser()
answer = chain.invoke({"question": "什么是幂等性？"})

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

动手练习

把 chain 拆成 render_prompt、call_model 和 parse_output 三个可替换阶段，并为 parser 写一个不依赖网络的测试。若将来更换模型，测试应只关心最终契约，而不是供应商响应的内部字段。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

Spring Boot 应用架构：Controller 到 Database

Fri, 21 Aug 2026 00:00:00 +0000

上图：Spring Boot Application Architecture 白板图；重点不是罗列名词，而是把一次真实请求如何穿过系统、在哪些边界失败画清楚。

为什么要从场景理解这张图

这张图围绕“An order endpoint keeps HTTP, business rules, and SQL separate so each layer can be tested independently.”展开。学习 Spring Boot Application Architecture 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Client → Controller → Service → Repository → Database。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：BeanDefinition → BeanFactory → ApplicationContext；@Controller → transport boundary。这些机制决定延迟、吞吐和可测试性。
资源与状态：@Service → domain orchestration；@Repository → persistence boundary。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Auto Configuration + Starter；必要时再结合 Embedded Server + externalized config 做降级、重试或回滚。

一个可落地的最小实现

下面的片段只展示边界，不代表完整业务。它的价值在于把“可以替换、可以测试、可以观测”的位置固定下来。

@RestController
class OrderController {
 private final OrderService service;
 OrderController(OrderService service) { this.service = service; }
}

在真实项目中，应把外部依赖封装在 adapter 或 repository 中；业务层只依赖稳定接口。这样本地测试可以使用 fake，压测可以替换慢依赖，线上故障也更容易定位。

场景中的工程决策

以白板右侧的生产场景为例：

先保护依赖：连接池、线程池、并发信号量或缓存都要有上限，不能用无限队列掩盖下游过载。
再保证正确性：幂等键、事务边界、版本号、锁或 schema 校验至少要有一种明确机制，避免重试带来重复写入。
最后优化性能：先用 trace、慢查询、GC pause、队列长度、p99 延迟等数据定位，再选择索引、缓存、批处理或并发策略。
让故障可恢复：超时、重试、限流、熔断、回滚和告警必须能在演练中被验证，而不是只写在文档里。

常见误区

只画成功路径，没有画超时、空数据、拒绝、回滚或副本延迟。
把框架默认行为当成业务契约，升级依赖后才发现边界改变。
用“加机器”替代测量，忽略连接池、锁竞争、慢 SQL、对象分配或事件循环阻塞。
将日志当作唯一观测手段，缺少指标、trace、采样和敏感数据脱敏。

生产检查清单

输入、输出和错误响应有明确 schema
外部调用设置 timeout、retry 上限、rate limit 和 fallback
资源池有容量、排队和拒绝指标
关键状态有幂等、事务或恢复策略
日志、metrics、trace 可关联同一个 request id
用接近生产的数据做回归、压测和故障演练

总结

真正掌握这张白板图，不是能背出每个框的定义，而是能从一次具体请求出发，解释每个箭头的输入输出、每个风险的处置方式，以及上线后用什么信号判断系统需要改进。

生产级 RAG 架构：权限、版本与可观测性

Fri, 21 Aug 2026 00:00:00 +0000

上图：RAG — 生产级 RAG 架构。

从 demo 到生产的差距主要在边界条件：谁能看到文档、索引如何更新、答案如何引用、上游不可用时怎么办。

核心心智模型

把系统分成 ingestion、indexing、query serving 和 evaluation 四个平面；在线请求只读当前 active index，更新在后台构建并原子切换。

关键机制

权限过滤必须在检索阶段执行；缓存键包含 tenant、权限摘要、query 规范化版本和 index version；删除文档要能传播到所有副本。

Python 示例

from dataclasses import dataclass

@dataclass
class QueryContext:
 tenant_id: str
 allowed_collections: set[str]
 index_version: str

def cache_key(query: str, ctx: QueryContext) -> str:
 scopes = ",".join(sorted(ctx.allowed_collections))
 return f"rag:v2:{ctx.tenant_id}:{ctx.index_version}:{scopes}:{normalize(query)}"

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

动手练习

设计 active/candidate 两套索引，模拟一次失败发布和一次文档删除，检查流量是否仍读到旧权限数据，并为每次回答保存 evidence ids。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。