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:

Integration point: Are you calling a backend API? Reading event messages? Implementing a webhook? Integrating with an external system?
Your boundaries: Are you a frontend developer? Backend developer in another service? External integrator? Architect?
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.

在搜索代码前，先理清你的需求：

集成类型: 你是在调用后端API？读取事件消息？实现Webhook？还是与外部系统集成？
角色边界: 你是前端开发者？其他服务的后端开发者？外部集成人员？还是架构师？
理解范围: 你需要单个API契约？完整模式？参考实现？还是架构权衡？

若用户意图不明确，可使用

assets/follow-up-questions.md

中的问题进一步澄清。

Step 2 — Search for reference implementation

步骤2 —— 搜索参考实现

Use

mcp_fusion_search_backend_code

to locate existing patterns:

Call with high-level intent: "How People service exposes authorization" or "Cross-service API integration patterns"
Start with
```
top: 3-5
```
results

Capture

metadata.repository

metadata.service

metadata.filePath

Extract minimal code snippets that show the pattern (method signature, type contract, authorization check)
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

定位现有模式：

以高-level意图发起调用：例如“People服务如何暴露授权机制”或“跨服务API集成模式”
初始返回结果设置为
```
top: 3-5
```

记录

metadata.repository

、

metadata.service

、

metadata.filePath

提取能展示模式的最小代码片段（方法签名、类型契约、授权检查逻辑等）
若结果不清晰，可优化搜索一次：
- 添加特定服务名称或接口
- 缩小到特定层级（控制器、处理器、客户端接口）
- 改用聚焦结果而非实现细节的表述

Step 3 — Explain the pattern

步骤3 —— 解释模式

Use the evidence from Step 2 to build your answer:

State the pattern clearly: What is the service doing? What contract does it expose?
Show the reference code: Quote the relevant snippet with file path and line range
Explain the constraints: What preconditions? Authorization? Error handling? Async behavior?
Relate to your use case: How would you apply this pattern to your problem?
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获取的信息构建答案：

清晰说明模式: 服务的作用是什么？它暴露了什么契约？
展示参考代码: 引用相关代码片段，并标注文件路径及行号范围
解释约束条件: 有哪些前置条件？授权规则？错误处理？异步行为？
关联你的用例: 如何将该模式应用到你的问题中？
若存在替代方案，需说明权衡:
- “该服务使用直接HttpClient；其他服务使用类型化客户端”
- “授权通过需求实现；部分服务使用策略模式”
- “事件通过Service Bus发布；请根据你的场景判断是否需要异步或直接调用”

Step 4 — Verify completeness

步骤4 —— 验证完整性

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仓库中获取）