[!info] related notes

• 入口: 后端架构 MOC, AI Agent Application MOC
• 职责区别: API Gateway, 防腐层
• 流式交互: SSE Gateway
• 示例架构: Agentic Application Stack

Backend For Frontend

BFF（Backend For Frontend）是面向特定客户端或用户体验提供 API 适配的后端层。例如 Web 与移动端可能需要不同的数据聚合、分页或交互流程，可分别由对应 BFF 承担。

BFF 不是 Go 专属，也不由是否调用 LLM 决定。一个普通后端只有确实承担客户端适配职责时，才有必要称为 BFF。

解决的问题与成本

客户端直接调用多个服务时，可能需要重复聚合、处理内部协议并承担过多请求。BFF 可集中这些客户端相关逻辑，让领域服务保持稳定的业务能力。

这不代表直连 AI Service 必然缺少鉴权，也不代表没有 BFF 就无法审计或限流。若一个后端已能清楚服务单一客户端，新增 BFF 可能只有额外部署与维护成本。

职责怎么分

角色	关注点
API Gateway	通用流量入口、路由和策略
BFF	特定客户端需要的数据形状、服务聚合与交互编排
领域 / 应用服务	业务规则、资源授权、状态与事务所有权
AI Service	模型调用、检索与推理等能力，按项目实际边界划分

认证、限流或流式转发可以位于多个层次；要明确谁负责哪项检查，避免层层重复或相互假定“别人已检查”。工具执行也需要执行点权限控制，不能因为经过 BFF 就默认可信。

AI 聊天示例

以下是设计流程示意，不是当前项目实现，也不是可以直接复制的 Handler：

收到聊天请求
  → 校验请求大小、字段与身份
  → 校验会话归属和操作权限，检查配额
  → 按消息幂等标识保存用户消息
  → 由约定的所有者组装上下文并创建运行记录
  → 调用 AI Service，检查调用结果后开始流式响应
  → 按协议转发事件，记录必要的运行状态
  → 根据明确的完成 / 失败 / 取消事件持久化终态

• 每一步都可能失败，不能忽略解码、会话查询、持久化和上游调用错误后继续使用结果。
• 响应头发出后通常不能再把状态码改成普通 HTTP 错误；流内错误需有协议约定。
• 流关闭不等于任务成功。断开客户端连接是否取消后台任务，取决于明确的运行生命周期设计。
• 文本 delta 可按需要批量落盘，不要求每个 token 单独写数据库；完成记录与重连恢复需有一致的顺序和标识。
• 请求日志与审计应保存必要元数据，不无条件记录完整提示词、凭证或敏感消息。

原 Go BFF 草图中的 handler/、service/、ai_context/、proxy/、repository/ 是一种目录组织示例，不是 BFF 模式要求，也不能据此推断仓库现有实现。

何时拆分

当不同客户端需求明显分化、团队需要独立发布或聚合逻辑持续膨胀时，可以考虑独立 BFF。共享业务规则仍由合适的领域服务维护，避免复制到多个 BFF 后产生不同版本。

参考

• Sam Newman：Backends For Frontends