frontend-query-mutation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Query & Mutation

前端查询与Mutation

Intent

设计目标

Keep contract as the single source of truth in
```
web/contract/*
```
.
Prefer contract-shaped
```
queryOptions()
```
and
```
mutationOptions()
```
.
Keep invalidation and mutation flow knowledge in the service layer.
Keep abstractions minimal to preserve TypeScript inference.

将合约作为
```
web/contract/*
```
中的唯一可信数据源。
优先使用符合合约结构的
```
queryOptions()
```
和
```
mutationOptions()
```
。
将缓存失效与Mutation流程逻辑保留在服务层。
尽可能减少抽象，以保留TypeScript的类型推断能力。

Workflow

工作流程

Identify the change surface.
- Read
```
references/contract-patterns.md
```
  for contract files, router composition, client helpers, and query or mutation call-site shape.
- Read
```
references/runtime-rules.md
```
  for conditional queries, invalidation, error handling, and legacy migrations.
- Read both references when a task spans contract shape and runtime behavior.
Implement the smallest abstraction that fits the task.
- Default to direct
```
useQuery(...)
```
  or
```
useMutation(...)
```
  calls with oRPC helpers at the call site.
- Extract a small shared query helper only when multiple call sites share the same extra options.
- Create
```
web/service/use-{domain}.ts
```
  only for orchestration or shared domain behavior.
Preserve Dify conventions.
- Keep contract inputs in
```
{ params, query?, body? }
```
  shape.
- Bind invalidation in the service-layer mutation definition.
- Prefer
```
mutate(...)
```
  ; use
```
mutateAsync(...)
```
  only when Promise semantics are required.

确定修改范围。
- 如需了解合约文件、路由组合、客户端工具函数以及查询或Mutation调用点结构，请阅读
```
references/contract-patterns.md
```
  。
- 如需了解条件查询、缓存失效、错误处理和旧版代码迁移，请阅读
```
references/runtime-rules.md
```
  。
- 若任务同时涉及合约结构和运行时行为，请阅读上述两份参考文档。
实现满足任务需求的最小化抽象。
- 默认在调用点直接使用oRPC工具函数调用
```
useQuery(...)
```
  或
```
useMutation(...)
```
  。
- 仅当多个调用点共享相同的额外配置时，才提取一个小型共享查询工具函数。
- 仅为编排逻辑或共享领域行为创建
```
web/service/use-{domain}.ts
```
  文件。
遵循Dify约定。
- 合约输入保持
```
{ params, query?, body? }
```
  结构。
- 在服务层的Mutation定义中绑定缓存失效逻辑。
- 优先使用
```
mutate(...)
```
  ；仅当需要Promise语义时才使用
```
mutateAsync(...)
```
  。

Files Commonly Touched

常修改文件

```
web/contract/console/*.ts
```
```
web/contract/marketplace.ts
```
```
web/contract/router.ts
```
```
web/service/client.ts
```
```
web/service/use-*.ts
```
component and hook call sites using
```
consoleQuery
```
or
```
marketplaceQuery
```

```
web/contract/console/*.ts
```
```
web/contract/marketplace.ts
```
```
web/contract/router.ts
```
```
web/service/client.ts
```
```
web/service/use-*.ts
```
使用
```
consoleQuery
```
或
```
marketplaceQuery
```
的组件与钩子调用点

References

参考文档

Use
```
references/contract-patterns.md
```
for contract shape, router registration, query and mutation helpers, and anti-patterns that degrade inference.
Use
```
references/runtime-rules.md
```
for conditional queries, invalidation,
```
mutate
```
versus
```
mutateAsync
```
, and legacy migration rules.

Treat this skill as the single query and mutation entry point for Dify frontend work. Keep detailed rules in the reference files instead of duplicating them in project docs.

如需了解合约结构、路由注册、查询与Mutation工具函数以及会降低类型推断能力的反模式，请阅读
```
references/contract-patterns.md
```
。
如需了解条件查询、缓存失效、
```
mutate
```
与
```
mutateAsync
```
的对比以及旧版代码迁移规则，请阅读
```
references/runtime-rules.md
```
。

将本指南作为Dify前端查询与Mutation开发的唯一入口文档。详细规则请保留在参考文件中，请勿在项目文档中重复编写。