api design skill

该技能资料围绕“设计开发者喜爱的 API”展开，原则是接口直观、一致、难以误用。主要能力包括：REST 基础（资源用复数名词、路径参数表身份、查询参数做过滤）、各 HTTP 方法的幂等与安全性、常见状态码的使用时机；契约优先流程（先用 OpenAPI/Swagger 定义契约并评审、再生成服务端桩、实现业务逻辑、按契约校验响应）；版本策略（URL 路径、Header、查询参数对比，推荐 URL 大版本，并给出 Active/Deprecated/Sunset 生命周期）；分页（offset 与 cursor 两种模式及各自优劣）；统一错误结构（机器可读 code、人类可读 message、request_id，禁止暴露堆栈）；请求与响应一致性规则（命名风格、ISO 8601 时间、ID 用字符串、封装响应、字段裁剪、批量操作）；缓存（Cache-Control、ETag、Last-Modified、Vary 及决策矩阵与失效策略）；限流（固定窗口、滑动窗口、令牌桶、漏桶，限流响应头、分层与作用域、客户端处理重试）；以及企业集成模式（Microsoft Graph Planner、Azure DevOps、Qualtrics v3、Microsoft Fabric 的异步 202 轮询与令牌获取）和以队列解耦、持久映射的多平台同步架构。还包含安全清单、文档要求与上线前审查清单。使用方式：将本资料作为 API 设计与评审的参考准则；文中给出的 OpenAPI 骨架、缓存与限流代码、PowerShell 示例属于示意，需按实际项目适配。限制：未提供安装命令、许可、价格或具体运行环境；示例仅用于说明设计模式，具体平台接口行为可能随版本变化，使用前应查阅对应官方文档。