实时接口文档与客户端示例编写
读取服务端实现,整理连接、消息、心跳与重连规则,编写接口参考文档和可运行客户端示例。
完整提示词
<context>
Realtime APIs fail clients in ways REST does not: the connection drops silently behind a proxy, a token expires mid-session, the client reconnects and misses events, two messages arrive out of the expected order. A usable reference therefore covers the lifecycle, not just message shapes: how to connect and authenticate (browsers cannot set headers on a WebSocket, so tokens go in a query string, a cookie, a subprotocol or a first message), what the server sends first, heartbeats and idle timeouts, close codes and what each means, how to resume after reconnect (last event id, sequence numbers, a snapshot), rate limits on client messages, and backpressure. SSE adds its own rules: `Last-Event-ID` on reconnect, the `retry:` field, and the browser's per-domain connection limit over HTTP/1.1.
</context>
<task>
Document the realtime API in:
<target>
{{target}}
</target>
1. Read the server code: the upgrade or SSE endpoint, auth checks, the message router, every message type sent and received, heartbeat and timeout settings, close codes, and any replay or resume logic.
2. Write the reference page with these parts:
- Connecting: URL, protocol (WebSocket or SSE), subprotocols, authentication method and token expiry behaviour.
- Lifecycle: a sequence of what happens from connect to first data (handshake, welcome or snapshot message, subscriptions), as a short numbered list or sequence diagram in Mermaid.
- Messages: a table per direction (client to server, server to client) with type, when it is sent, payload fields and an example JSON.
- Heartbeats and timeouts: ping or keepalive interval and what the client must do.
- Errors and close codes: each code or error message, its meaning and whether to reconnect.
- Reconnection: backoff advice and how to resume without losing or duplicating events.
- Limits: message size, client message rate, subscriptions per connection.
3. Write a minimal working client in {{client_languages}} that connects, authenticates, handles heartbeats and reconnects with backoff and resume.
4. Test the example against a local server if you can run one, and report the result.
</task>
<constraints>
- Every message type, field, interval and close code must come from the code. Mark unknowns as "to confirm".
- If there is no resume mechanism, say plainly that events during a disconnect are lost; do not imply delivery guarantees the server does not give.
- Never put long-lived secrets in example URLs; show short-lived tokens and note that query strings can end up in logs.
{{> guardrails/investigate-before-answering}}
</constraints>
<output_format>
Write the reference page. Then reply with:
## Page written
Path and what it covers, and whether the client example was run.
## Protocol gaps
Missing protocol pieces that hurt clients (no heartbeat, no resume, undocumented close codes).
## Questions for the owners
Facts you could not confirm from code.
</output_format>可替换内容
- {{target}}
- {{client_languages}}
- {{> guardrails/investigate-before-answering}}
分类与标签
编程开发、实时接口、接口文档、客户端示例、断线重连