返回提示词目录第 1293 页

设计多语言接口客户端开发包

依据接口规范与目标语言规划客户端结构,输出重试、分页、错误处理、版本发布规则及调用示例。

完整提示词

<context>
An SDK is a second API: once developers write code against its method names and error classes, changing them is a breaking change with its own semver, independent of the HTTP API's version. Good SDKs feel native to each language (async patterns, naming, packaging) while sharing one behaviour model: a client object configured once with credentials, base URL, timeouts and retry policy; resource-grouped methods; automatic retries with backoff only for idempotent requests or requests with an idempotency key; auto-paginating iterators; typed errors that carry the HTTP status, error code and request id for support. Generating SDKs from an OpenAPI or Protobuf spec keeps many languages in sync but produces awkward code unless the spec is clean and the generator is customised; hand-written SDKs feel better but drift. Most teams generate the low-level layer and hand-write a thin ergonomic layer, and run the same contract tests against every language.
</context>

<task>
<api>
{{api}}
</api>

<languages>
{{languages}}
</languages>

{{#team}}
<team>
{{team}}
</team>
{{/team}}

1. If a repository or spec file is available, read it first and note spec problems that would make generated code poor (missing operation ids, inline anonymous schemas, inconsistent naming). Say what you read.
2. Choose the build approach (generated, hand-written or generated core plus hand-written layer) from the number of languages, API change rate and team capacity, with the trade-offs.
3. Design the public surface: client construction and configuration, resource namespaces and method naming per language idiom, request and response types, optional parameters, and what is deliberately not exposed.
4. Specify cross-cutting behaviour: authentication and token refresh, timeouts, retries with backoff and jitter limited to safe requests, idempotency key handling, pagination iterators, file uploads and downloads, logging hooks with secrets redacted, user-agent with SDK version, and proxy or custom HTTP client support.
5. Specify errors: an error class hierarchy (authentication, permission, not found, validation, rate limit with retry-after, server, network), the fields every error carries, and how validation details are exposed.
6. Specify versioning and releases: SDK semver independent of the API version, how new API fields and endpoints reach the SDK, deprecation warnings, supported runtime versions, changelog, and contract tests shared across languages.
7. Show example usage in each target language for one common flow, including error handling and pagination.
</task>

<constraints>
- Do not retry non-idempotent requests automatically unless they carry an idempotency key.
- Do not swallow errors or return null for failures; errors must be typed and carry a request id when the API provides one.
- Example code must use only methods the design defines; mark it as illustrative.
- Do not invent the API's endpoints or error codes; work from the given API and list gaps.
{{> output/uncertainty}}
</constraints>

<output_format>
## Build approach
Recommendation and trade-offs in at most 8 lines.
## Public surface
Bullets and a short type or method listing per language.
## Cross-cutting behaviour
Table: concern, behaviour, configurable (yes or no), default.
## Errors
Error hierarchy as a list, with the fields each carries.
## Versioning and releases
## Example usage
One code block per language.
## Open questions
Numbered.
</output_format>

可替换内容

  • {{api}}
  • {{languages}}
  • {{#team}}
  • {{team}}
  • {{/team}}
  • {{> output/uncertainty}}

分类与标签

编程开发、客户端开发包、接口设计、多语言支持、版本管理

前往 AI 图片创作