Back to Details

fusion-backend-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fusion Backend Consumption

Fusion后端服务消费指南

When to use

适用场景

Use this skill when you need to understand how Fusion backend services work, what APIs are available, how to integrate with them, or understand the architectural patterns behind them.
Typical triggers:
  • "How do I call the People API?"
  • "Show me an example of how the authorization pattern works"
  • "What's the contract for the Org service?"
  • "How do services handle validation errors?"
  • "What async/messaging patterns does Fusion use?"
  • "Can I see a reference implementation of a CQRS handler?"
  • "How do services integrate with external APIs?"
  • "What authentication/authorization requirements do I need to know?"
  • "Show me how events flow through the system"
  • "What's the pattern for cross-service calls?"
  • "How should I structure my API client?"
  • "Where should I call the Context API?"
  • "What's the difference between a command and a query in Fusion?"
Implicit triggers:
  • User is building a frontend/client app and needs to understand backend contracts
  • User is integrating with Fusion APIs and needs patterns
  • User is designing an architecture and wants to understand backend best practices
  • User wants to learn from existing Fusion service implementations
当你需要了解Fusion后端服务的工作机制、可用API、集成方式，或是其背后的架构模式时，可使用本技能。
典型触发场景：
  • "如何调用People API？"
  • "展示授权模式的实现示例"
  • "Org服务的契约是什么？"
  • "服务如何处理验证错误？"
  • "Fusion采用了哪些异步/消息传递模式？"
  • "能否查看CQRS处理器的参考实现？"
  • "服务如何与外部API集成？"
  • "我需要了解哪些认证/授权要求？"
  • "展示系统中的事件流转流程"
  • "跨服务调用的模式是什么？"
  • "应如何构建API客户端？"
  • "应在何处调用Context API？"
  • "Fusion中命令与查询的区别是什么？"
隐含触发场景：
  • 用户正在构建前端/客户端应用，需要了解后端契约
  • 用户正在集成Fusion API，需要参考模式
  • 用户正在设计架构，希望了解后端最佳实践
  • 用户希望从现有Fusion服务实现中学习经验

When not to use

不适用场景

Do not use this skill for:
  • Creating or modifying backend services — those are backend service development tasks (use the service-specific repo skill, not this one)
  • Adding new endpoints or API operations — backend service development
  • Database schema changes or migrations — backend development
  • Authorization requirement definitions — backend development (this skill shows what exists, not defining new requirements)
  • Pure architecture discussions without code references — use fusion-research or ADR-focused skills instead
  • Selecting between Fusion Framework alternatives — use fusion-research or fusion-app-react-dev instead
本技能不适用于：
  • 创建或修改后端服务 —— 此类属于后端服务开发任务（请使用服务专属仓库技能，而非本技能）
  • 新增端点或API操作 —— 后端服务开发范畴
  • 数据库 schema 变更或迁移 —— 后端开发范畴
  • 定义授权要求 —— 后端开发范畴（本技能仅展示现有规则，不涉及新要求定义）
  • 无代码参考的纯架构讨论 —— 请改用fusion-research或聚焦ADR的技能
  • 在Fusion框架替代方案中做选择 —— 请改用fusion-research或fusion-app-react-dev技能

Required inputs

必要输入

Mandatory

必填项

  • What you're trying to do: clear description of the integration point, use case, or pattern you're exploring
  • Your role/context: Are you building a frontend app? Integrating externally? Designing architecture?
  • 你的需求: 清晰描述你正在探索的集成点、用例或模式
  • 你的角色/上下文: 你是在构建前端应用？进行外部集成？还是设计架构？

Conditional

条件项

  • When comparing patterns: which two options you're deciding between
  • When consuming an API: what operation/scenario (CRUD, async, real-time, etc.)
  • When integrating: external system name and direction of flow (calling out vs being called)
  • 对比模式时：你正在抉择的两个选项
  • 使用API时：具体操作/场景（CRUD、异步、实时等）
  • 进行集成时：外部系统名称及流向（调用外部系统或被外部系统调用）

Instructions

使用步骤

Step 1 — Clarify consumption context

步骤1 —— 明确使用上下文

Before searching for code, understand what you need:
  1. Integration point: Are you calling a backend API? Reading event messages? Implementing a webhook? Integrating with an external system?
  2. Your boundaries: Are you a frontend developer? Backend developer in another service? External integrator? Architect?
  3. Scope of understanding: Do you need a single API contract? A full pattern? A reference implementation? Architectural tradeoffs?
Use 
assets/follow-up-questions.md
if the user's intent is unclear.
在搜索代码前，先理清你的需求：
  1. 集成类型: 你是在调用后端API？读取事件消息？实现Webhook？还是与外部系统集成？
  2. 角色边界: 你是前端开发者？其他服务的后端开发者？外部集成人员？还是架构师？
  3. 理解范围: 你需要单个API契约？完整模式？参考实现？还是架构权衡？
若用户意图不明确，可使用
assets/follow-up-questions.md
中的问题进一步澄清。

Step 2 — Search for reference implementation

步骤2 —— 搜索参考实现

Use 
mcp_fusion_search_backend_code
to locate existing patterns:
  1. Call with high-level intent: "How People service exposes authorization" or "Cross-service API integration patterns"
  2. Start with 
    top: 3-5
    results
  3. Capture 
    metadata.repository
    , 
    metadata.service
    , 
    metadata.filePath
  4. Extract minimal code snippets that show the pattern (method signature, type contract, authorization check)
  5. If results are unclear, refine once:
    • Add specific service name or interface
    • Narrow to specific layer (controller, handler, client interface)
    • Try a different phrase focusing on the outcome rather than implementation details
使用
mcp_fusion_search_backend_code
定位现有模式：
  1. 以高-level意图发起调用：例如“People服务如何暴露授权机制”或“跨服务API集成模式”
  2. 初始返回结果设置为
    top: 3-5
  3. 记录
    metadata.repository
    、
    metadata.service
    、
    metadata.filePath
  4. 提取能展示模式的最小代码片段（方法签名、类型契约、授权检查逻辑等）
  5. 若结果不清晰，可优化搜索一次：
    • 添加特定服务名称或接口
    • 缩小到特定层级（控制器、处理器、客户端接口）
    • 改用聚焦结果而非实现细节的表述

Step 3 — Explain the pattern

步骤3 —— 解释模式

Use the evidence from Step 2 to build your answer:
  1. State the pattern clearly: What is the service doing? What contract does it expose?
  2. Show the reference code: Quote the relevant snippet with file path and line range
  3. Explain the constraints: What preconditions? Authorization? Error handling? Async behavior?
  4. Relate to your use case: How would you apply this pattern to your problem?
  5. Surface tradeoffs or alternatives if they exist:
    • "This service uses direct HttpClient; others use typed clients"
    • "Authorization is done via requirements; some services use policies"
    • "Events are published via Service Bus; check if your scenario needs async vs direct"
利用步骤2获取的信息构建答案：
  1. 清晰说明模式: 服务的作用是什么？它暴露了什么契约？
  2. 展示参考代码: 引用相关代码片段，并标注文件路径及行号范围
  3. 解释约束条件: 有哪些前置条件？授权规则？错误处理？异步行为？
  4. 关联你的用例: 如何将该模式应用到你的问题中？
  5. 若存在替代方案，需说明权衡:
    • “该服务使用直接HttpClient；其他服务使用类型化客户端”
    • “授权通过需求实现；部分服务使用策略模式”
    • “事件通过Service Bus发布；请根据你的场景判断是否需要异步或直接调用”

Step 4 — Verify completeness

步骤4 —— 验证完整性

Before ending the answer, check:
  • User understands the contract (inputs, outputs, errors)
  • User sees a real code reference (not invented)
  • User knows where the code lives (repository, service, file path)
  • User knows any prerequisites (authentication, configuration, dependencies)
  • User has enough context to implement or integrate
If uncertainty remains, flag it explicitly: "I found the authorization pattern but not the exact configuration for service-to-service calls; you may want to check the Startup.cs configuration directly."
在结束回答前，检查以下内容：
  • 用户理解契约（输入、输出、错误）
  • 用户看到真实代码参考（而非虚构示例）
  • 用户知道代码所在位置（仓库、服务、文件路径）
  • 用户了解所有前置条件（认证、配置、依赖）
  • 用户拥有足够上下文来实现或集成
若仍存在不确定性，需明确标注：“我找到了授权模式，但未找到服务间调用的具体配置；你可直接查看Startup.cs中的配置。”

Reference guides

参考指南

See 
references/
for deeper pattern documentation:
  • api-contracts.md
    — Fusion service API contracts and versioning
  • authorization-patterns.md
    — Authentication, authorization requirements, role-based access
  • validation-patterns.md
    — Input validation, error responses, business rules
  • async-patterns.md
    — Events, service bus, domain notifications, eventual consistency
  • integration-patterns.md
    — Cross-service calls, external APIs, webhook handling
  • cqrs-reference.md
    — CQRS handlers, commands, queries, notifications structure
如需更深入的模式文档，请查看
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

资源文件

  • assets/follow-up-questions.md
    — Clarifying questions for ambiguous requests
  • references/integration-patterns.md
    — Common integration scenarios and which patterns apply
  • assets/follow-up-questions.md
    —— 用于澄清模糊请求的问题列表
  • references/integration-patterns.md
    —— 常见集成场景及适用模式

Safety & constraints

安全与约束

Never:
  • Describe real backend API behavior or repository-specific implementation details as fact unless you can verify them in retrieved source code or clearly cited repository documentation
  • Claim a pattern exists in a repository when search returns no evidence
  • Present illustrative pseudo-code, C#, JSON, or payload examples as if they were retrieved source code
  • Suggest modifying a backend service — that's out of scope
Always:
  • Clearly label illustrative examples as examples/pseudo-code when they are explanatory rather than retrieved from source
  • Capture and cite repository, file path, and line references when showing real code or summarizing behavior evidenced by MCP search results
  • State explicitly which repository the pattern comes from
  • Note when a pattern exists in one service but not others (services have variation)
  • Offer to escalate to 
    fusion-services-develop
    skill (available in the fusion-core-services repo) if the user wants to implement changes
绝对禁止：
  • 除非能从检索到的源代码或明确引用的仓库文档中验证，否则不得将真实后端API行为或仓库专属实现细节作为事实描述
  • 当搜索无结果时，不得声称某模式存在于仓库中
  • 将说明性伪代码、C#、JSON或负载示例伪装成检索到的源代码
  • 建议修改后端服务 —— 此类操作超出本技能范围
必须遵守：
  • 当示例为解释性内容而非从仓库检索时，需明确标注为“示例/伪代码”
  • 展示真实代码或总结MCP搜索结果所体现的行为时，需记录并引用仓库、文件路径及行号
  • 明确说明模式来自哪个仓库
  • 若模式仅存在于部分服务中，需标注服务间的差异
  • 若用户希望实现变更，需建议转用
    fusion-services-develop
    技能（可在fusion-core-services仓库中获取）