---
docStatus: current
---

# 方法行为与重试契约

在现有方法描述中声明副作用、幂等和未知结果处理，避免把签名兼容误当作安全重试。

方法的参数和返回类型描述数据形状；调用安全还依赖副作用、身份和失败行为。开发者应在方法源码的
`description` 中写明以下内容，并随 Module 版本一起发布。调用方回读目标 Runtime 的方法定义时读取该说明；
信息缺失或含糊时，先补齐契约，不据方法名或 HTTP 动词猜测。

## 声明内容

| 内容     | 需要回答的问题                             |
| ------ | ----------------------------------- |
| 副作用与范围 | 是否写数据、发消息或调用外部系统？影响哪些对象？是否允许部分成功？   |
| 身份与权限  | 是否要求最终用户上下文？如何限制工作区、对象和外部账号权限？      |
| 幂等     | 是否保证重复调用不重复产生业务效果？适用条件是什么？          |
| 幂等键    | 若需要，键对应哪个已声明参数、作用域和有效期？相同键不同参数如何处理？ |
| 超时与取消  | 客户端超时后服务端是否继续？是否有明确支持的取消能力？         |
| 错误与重试  | 哪些错误可重试、等待规则及次数限制是什么？哪些错误需先修正输入或权限？ |
| 未知结果   | 用哪个业务标识和查询方法确认最终状态？如何处理已受理但尚未完成？    |

当前方法模型没有平台统一的结构化幂等／重试策略字段。`description` 是开发者与调用方阅读的行为说明，
不触发网关自动执行策略，也不作为平台可验证的幂等证明。不要添加未定义的 JSON 字段。
需要幂等键的方法应把键声明为正常业务参数，并由实现方兑现去重、冲突检查和结果查询语义；
仅在请求中增加一个键不会产生这些保证。

## 描述示例

下面是业务方法 `description` 的示意文本，只有实现确实满足这些条件时才能使用：

> 创建订单，可能写入订单并提交下游。要求当前用户拥有目标组织的下单权限。
> orderRequestId 是必填业务参数，在同一组织内唯一；重复提交相同键和参数返回同一订单，
> 相同键不同参数返回冲突。客户端超时不代表取消；先按 orderRequestId 查询订单状态，
> 只有确认不存在且仍在方法约定的去重有效期内，才按相同参数重试。

实际方法还应写清去重有效期、状态查询方法、错误码和重试上限，不能照抄示例代替业务实现。

## 调用方默认规则

- HTTP `200` 后仍检查 CModel；传输失败或超时可能表示结果未知，不代表没有副作用。
- 行为未声明时，不自动重试可能写入的方法，也不因连接失败改用新业务键重新提交。
- 声明幂等的方法仍需遵守错误分类、次数限制和退避要求；权限错误不能通过循环重试解决。
- 签名兼容只检查数据契约；从只读变为写入、缩短去重窗口、改变事务边界等行为变化，需要显式评估消费者影响并按 SemVer 发布。

调用链和响应检查见[模块服务间调用协议](/development/bundle-development/module-development/service-to-service-calls/)。