fusion-backend-dev

Fusion 后端使用

使用场景

当需要了解 Fusion 后端服务、可用 API、集成模式或架构决策时使用。

典型触发场景：

• “如何调用 People API？”
• “展示授权模式的示例”
• “Org 服务的契约是什么？”
• “服务如何处理验证错误？”
• “Fusion 使用哪些异步／消息传递模式？”
• “可以查看 CQRS 处理器的参考实现吗？”
• “服务如何与外部 API 集成？”
• “我需要了解哪些身份验证／授权要求？”
• “展示事件在系统中的流转方式”
• “跨服务调用采用什么模式？”
• “我应该如何构建 API 客户端？”
• “我应该在哪里调用 Context API？”
• “Fusion 中命令和查询有什么区别？”

隐式触发场景：

• 构建前端／客户端应用，需要了解后端契约
• 与 Fusion API 集成，需要了解相关模式
• 设计架构，需要了解后端最佳实践
• 通过现有 Fusion 服务实现进行学习

不适用场景

• 创建或修改后端服务——使用特定服务仓库的技能
• 添加新端点或 API 操作——后端开发
• 更改数据库架构或执行迁移——后端开发
• 定义授权要求——后端开发（此技能展示已有内容，不定义新要求）
• 不涉及代码参考的纯架构讨论——使用 fusion-research 或以 ADR 为重点的技能
• 在 Fusion Framework 的替代方案之间进行选择——使用 fusion-research 或 fusion-app-react-dev

必需输入

必填

• 你要做什么：清晰说明集成点、用例或模式
• 你的角色／上下文：构建前端应用？从外部进行集成？设计架构？

条件必填

• 比较模式时：你正在考虑的两个选项
• 使用 API 时：操作／场景（CRUD、异步、实时等）
• 进行集成时：外部系统名称及数据流向（主动调用还是被调用）

说明

步骤 1 — 明确使用上下文

搜索代码前，先了解你的需求：

1. 集成点：调用后端 API？读取事件消息？实现 webhook？与外部系统集成？
2. 你的职责边界：前端开发者？其他服务的后端开发者？外部集成方？架构师？
3. 范围：单个 API 契约？完整模式？参考实现？架构权衡？

如果用户意图不明确，请使用 assets/follow-up-questions.md。

步骤 2 — 搜索参考实现

使用 mcp_fusion_search_backend_code 查找现有模式：

1. 使用高层级意图进行调用：“People 服务如何公开授权”或“跨服务 API 集成模式”
2. 从 top: 3-5 条结果开始
3. 记录 metadata.repository、metadata.service、metadata.filePath
4. 提取展示该模式所需的最少代码片段（方法签名、类型契约、授权检查）
5. 如果结果不明确，再优化一次：
   • 添加具体的服务名称或接口
   • 缩小到具体层级（控制器、处理器、客户端接口）
   • 换用侧重结果而非实现细节的表述

步骤 3 — 说明模式

使用步骤 2 中的证据：

1. 清晰说明模式：服务做什么？它公开什么契约？
2. 展示参考代码：引用相关代码片段，并注明文件路径和行范围
3. 解释约束条件：前置条件？授权？错误处理？异步行为？
4. 关联你的用例：如何应用此模式？
5. 如果存在，指出权衡或替代方案

第 4 步 — 验证完整性

结束前，请检查：

• 用户了解契约（输入、输出、错误）
• 用户看到了真实的代码参考（而非虚构内容）
• 用户知道代码所在位置（仓库、服务、文件路径）
• 用户了解前置条件（身份验证、配置、依赖项）
• 用户拥有足够的上下文来实现或集成

如果仍有不确定之处，请明确指出。

参考指南

如需了解更深入的模式文档，请参阅 references/：

• api-contracts.md — Fusion 服务 API 契约与版本控制
• authorization-patterns.md — 身份验证、授权要求、基于角色的访问
• validation-patterns.md — 输入验证、错误响应、业务规则
• async-patterns.md — 事件、服务总线、领域通知、最终一致性
• integration-patterns.md — 跨服务调用、外部 API、webhook 处理
• cqrs-reference.md — CQRS 处理程序、命令、查询、通知结构

资源

• assets/follow-up-questions.md — 针对模糊请求的澄清问题
• references/integration-patterns.md — 常见集成场景及适用模式

安全与约束

切勿：

• 将真实后端 API 的行为描述为事实，除非检索到的源代码或引用的仓库文档可以证实
• 在搜索结果没有证据时声称某种模式存在
• 将说明性伪代码描述为检索到的源代码
• 建议修改后端服务——这超出范围

务必：

• 对用于说明而非检索所得的示例标注为示例/伪代码
• 记录并引用真实代码所在的仓库、文件路径和行号
• 说明模式来自哪个仓库
• 指出某个模式是否只存在于一个服务中，而非其他服务中
• 如果用户想要实现更改，主动提出转交给 fusion-services-developer Agent
• 对于设置或部署新的独立后端 API（应用注册、Roles V2、数据库、Radix/Kubernetes 部署、可观测性），请引导用户参阅 fusion-docs 上的 新建后端服务检查清单，而不是自行臆测步骤