返回提示词目录第 1301 页

为 API 端点实现幂等键机制

为指定接口设计并实现请求去重、并发控制与响应重放,配套存储迁移、过期清理及关键场景测试。

完整提示词

<context>
You are a backend engineer making non-idempotent endpoints safe to retry. Networks drop responses after the server has acted, so clients retry, and without protection a retry creates a second order or a second charge. The pattern popularised by payment APIs, and described in the IETF draft for the `Idempotency-Key` header:
- The client sends a unique key (usually a UUID) per logical operation and reuses it on every retry of that operation.
- The server stores, per key and per caller: a fingerprint of the request (method, path, hash of the body), a status (in progress or completed), the response status and body, and timestamps. Keys are scoped to the authenticated caller so one client cannot read another's replayed response.
- The first request claims the key atomically (an insert against a unique constraint, not check-then-insert). A concurrent request with the same key while the first is still running gets 409 Conflict (or waits briefly); a request with the same key but a different body gets 422.
- When the operation completes, store the response in the same database transaction as the business write where possible. Otherwise a crash between the two leaves an order without a recorded response, and the retry repeats the work.
- Replays return the stored status and body, typically with a header marking them as replayed. Keys expire after a window such as 24 hours.
- Failures before any side effect release the key so the client can retry. Failures after a partial side effect need a recovery point, not a blind retry. Pass the same key, or a derived one, to downstream providers that support idempotency, such as payment APIs.
- A natural unique constraint (one order per cart id) is sometimes simpler and stronger; say so if it fits.
</context>

<task>
Add idempotency keys to these endpoints:
{{endpoints}}

{{#stack}}Stack: {{stack}}{{/stack}}

1. Read the endpoints, their transactions and any downstream calls. Note where side effects happen and whether a natural unique constraint would already prevent duplicates.
2. State the design: header name, required or optional, key scope, storage (table or cache, and why), fingerprint, status codes for concurrent and mismatched reuse, expiry, which outcomes are stored, and how downstream calls receive keys.
3. Implement it as reusable middleware or a decorator in the project's style, with the storage migration, atomic claim, response capture and replay, and a cleanup job for expired keys.
4. Write tests including real concurrency (two requests at once), then run them and the type check.
</task>

<constraints>
- Never implement the claim as a read followed by a separate write without a unique constraint or lock.
- Never replay a stored response to a different caller.
- Do not store more of the response than needed, and keep secrets and card data out of it.
- Never invent library functions; if unsure, say so.
{{> guardrails/scope-discipline}}
{{> guardrails/investigate-before-answering}}
{{> guardrails/verify-before-done}}
</constraints>

<output_format>
## Design decisions
A table: Decision | Choice | Why.
## Changes
One line per file: `path`, what changed.
## Tests
One line per test. Cover at least: a retry returns the same response without a second side effect, concurrent duplicates produce one side effect, the same key with a different body is rejected, keys are isolated per caller, a failure before side effects allows retry, and expired keys are cleaned up.
## Verification
Commands run and their actual results.
## Open questions
Choices left to the team, with the default chosen.
</output_format>

可替换内容

  • {{endpoints}}
  • {{#stack}}
  • {{stack}}
  • {{/stack}}
  • {{> guardrails/scope-discipline}}
  • {{> guardrails/investigate-before-answering}}
  • {{> guardrails/verify-before-done}}

分类与标签

编程开发、API开发、后端工程、请求幂等

前往 AI 图片创作