API客户端SDK最佳实践提示

从OpenAPI规范生成底层客户端，并仅在之上手写一个薄且符合语言习惯的封装层。置信度：0.85 将API规范视为事实来源，并在生成代码过期时让CI失败。置信度：0.85 让首次调用能在三行内完成：安装、使用API密钥创建客户端、调用一个方法。置信度：0.90 默认从已知环境变量读取API密钥，且绝不记录或将其包含在错误消息中。置信度：0.95 公开完全类型化的请求和响应模型，并在包中附带TypeScript类型或Python类型提示。置信度：0.90 返回带有HTTP状态、错误代码、消息和请求ID的类型化错误，而不是通用异常。置信度：0.90 对超时、429和5xx响应使用指数退避和抖动重试幂等请求，并遵守Retry-After头。置信度：0.90 在API支持时，自动为重试的POST请求发送幂等性密钥。置信度：0.80 设置合理的默认超时，并让调用者能覆盖每个客户端和每个请求的超时及重试设置。置信度：0.85 提供自动分页的迭代器，让用户可以循环遍历所有结果而无需自己处理游标。置信度：0.85 支持使用原生异步迭代器或生成器的流式响应，而非回调。置信度：0.80 在同步和异步客户端都常见的语言中提供两者，并共享相同的模型。置信度：0.75 保持最小化的运行时依赖，并避免将用户绑定到特定HTTP库版本。置信度：0.85 发送带有SDK名称、版本和运行时的User-Agent头，以便API所有者能查看采用情况和调试问题。置信度：0.80 严格遵守语义化版本控制，并在变更日志中记录带有迁移示例的破坏性更改。置信度：0.90 在次要版本中绝不删除方法；先弃用并发出警告。置信度：0.85 针对录制的HTTP夹具进行快速测试，并在夜间对真实沙盒环境运行较小的测试套件。置信度：0.80 在CI中对每个受支持的运行时版本运行测试套件，例如每个活跃的Node.js LTS或Python版本。置信度：0.85 在README和文档中放置可运行的代码示例，并在CI中测试这些示例，使其永不过时。置信度：0.80 暴露日志、追踪和自定义头的钩子或中间件，而非为每个需求添加一次性选项。置信度：0.75 允许自定义基础URL和HTTP客户端，以便用户能将SDK指向代理、模拟或区域端点。置信度：0.80 从CI发布带有来源和签名版本的包，绝不从维护者的笔记本电脑发布。置信度：0.75